SAS/C Library Reference, Vol. 1

lseek -- Position a UNIX Style File

SYNOPSIS

 #include <fcntl.h>

 long lseek(int fn, long offset, int pos);

The synopsis for the POSIX implementation is

 #include <unistd.h>

 off_t lseek(int fn, off_t offset, int pos);

DESCRIPTION

lseek replaces the current offset with a new position in the file. fn is the file descriptor. offset is the specified byte offset; it can be positive or negative. pos is the position from which offset is specified. The next I/O operation on the file begins at offset.

pos can be one of the following symbols defined in <unistd.h> and <fcntl.h>:

SEEK_SET: is the beginning of the file; the value is 0.
SEEK_CUR: is the current file offset; the value is 1.
SEEK_END: is the end of the file; the value is 2.

lseek(fn, 0L, SEEK_CUR) determines the current file position without changing it. You can use lseek to set the position past the current end of file, but after such positioning, attempts to read data shows end of file. If you call write while the file is so positioned, 0s are written into all character positions between the previous end of file and the current position, after which the specified data are written.

If fn represents a non-HFS file opened as text, offset does not represent a physical offset in bytes. In this case, the lseek offset is interpreted according to the same rules as an fseek offset. For more information, see File positioning with standard I/O (fseek and ftell) .

RETURN VALUE

If successful, lseek returns the new file position; otherwise, it returns - 1L.

EXAMPLE

This example determines the size of a file by using lseek:

  #include <fcntl.h>

  main()
  {
     long size;
     int fileno;

     fileno = open("tso:TEST", O_RDONLY);

        /* accesses the file as binary */

     if ((size = lseek(fileno, 0L, SEEK_END)) == -1)
        perror("lseek() error");
     else {
        printf("Size of file is: %ldn", size);
        close(fileno);
     }
  }

RELATED FUNCTIONS