lseek(S)                       6 January 1993                       lseek(S)


 Name

    lseek - move read/write file pointer

 Syntax


    cc  . . .  -lc


    #include  <unistd.h>

    long lseek (fildes, offset, whence)
    int fildes;
    long offset;
    int whence;


 Description

    The fildes argument is a file descriptor returned from a creat, open,
    dup, or fcntl system call.  The lseek system call sets the file pointer
    associated with fildes as follows:

    +     If whence is 0, the pointer is set to offset bytes.

    +     If whence is 1, the pointer is set to its current location plus
          offset.

    +     If whence is 2, the pointer is set to the size of the file plus
          offset.

    Symbolic constants for whence are defined in the <unistd.h> header file:

    _________________________________________________________________________
    Name                    Description
    _________________________________________________________________________
    SEEK_CUR                Set file-pointer to current location plus offset.
    SEEK_END                Set file-pointer to EOF plus offset.
    SEEK_SET                Set file-pointer equal to offset bytes.


    Upon successful completion, the resulting pointer location, as measured
    in bytes from the beginning of the file, is returned.  Note that if
    fildes is a remote file descriptor and offset is negative, lseek returns
    the file pointer even if it is negative.

    lseek fails and the file pointer remains unchanged if one or more of the
    following is true:

    [EBADF]     fildes is not an open file descriptor.

    [EINVAL]


                1.  (with SIGSYS signal is present):  The whence argument is
                    not 0, 1, or 2.

                2.  fildes is not a remote file descriptor, and the resulting
                    file pointer would be negative.

    Some devices are incapable of seeking.  The value of the file pointer
    associated with such a device is undefined.

    [ESPIPE]    fildes is associated with a pipe or fifo.


 Diagnostics

    Upon successful completion, a non-negative integer indicating the file
    pointer value is returned.  Otherwise, a value of -1 is returned, and
    errno is set to indicate the error.

 See also

    creat(S), dup(S), fcntl(S), open(S)

 Standards conformance

    lseek is conformant with:
    AT&T SVID Issue 2;
    X/Open Portability Guide, Issue 3, 1989;
    Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2);
    IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C
    Language] (ISO/IEC 9945-1);
    and NIST FIPS 151-1.