lseek

Purpose

     Moves read/write file pointer.

Syntax

     #include <sys/types.h>
     #include <unistd.h>

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

Description

     The lseek system call sets  the file pointer for the file
     specified by  the fildes parameter.  If  Distributed Ser-
     vices is installed  on your system, this  file can reside
     on  another  node.   The   fildes  parameter  is  a  file
     descriptor  obtained from  a creat,  open, dup,  or fcntl
     system call.

     The lseek  system call  sets the file  pointer associated
     with  the fildes  stream according  to the  value of  the
     whence parameter, as follows:

     SEEK_SET   Sets  the file  pointer  to the  value of  the
                offset parameter.

     SEEK_CUR   Sets the file pointer  to its current location
                plus the value of the offset parameter.

     SEEK_END   Sets the file pointer to  the size of the file
                plus the value of the offset parameter.

Return Value

     Upon   successful  completion,   the  resulting   pointer
     location as measured  in bytes from the  beginning of the
     file  is returned.   If lseek  fails,  a value  of -1  is
     returned and errno is set to indicate the error.

Diagnostics

     The lseek system call fails  and the file pointer remains
     unchanged if one or more of the following are true:

     EBADF      fildes is not an open file descriptor.

     ESPIPE     fildes is  associated with a pipe  (FIFO) or a
                multiplexed special file.

     EINVAL     whence is not  0, 1 or 2.  This  also causes a
                SIGSYS signal.

     EINVAL     The resulting file pointer would be negative.

     If  Distributed Services  is  installed  on your  system,
     lseek can also  fail if one or more of  the following are
     true:

     EDIST         The   server   has  blocked   new   inbound
                   requests.

     EDIST         Outbound requests are currently blocked.

     EAGAIN        The  server  is  too  busy  to  accept  the
                   request.

     ENOMEM        Either  this node  or the  server does  not
                   have enough memory available to service the
                   request.

     EBADCONNECT   An attempt to use  an existing network con-
                   nection with a remote node failed.

Related Information

     In this  book:  "creat,"   "dup," "fcntl,"   "open," and
     "fseek, rewind, ftell."