2.9BSD/usr/man/cat2/lseek.2

LSEEK(2)            UNIX Programmer's Manual             LSEEK(2)

NAME
     lseek, tell - move read/write pointer

SYNOPSIS
     #include <sys/types.h>
     #include <sys/file.h>

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

     long tell(fildes)

DESCRIPTION
     The file descriptor refers to a file open for reading or
     writing.  The read (resp. write) pointer for the file is set
     as follows:

          If _w_h_e_n_c_e is FSEEK_ABSOLUTE, the pointer is set to
          _o_f_f_s_e_t bytes.

          If _w_h_e_n_c_e is FSEEK_RELATIVE, the pointer is set to its
          current location plus _o_f_f_s_e_t.

          If _w_h_e_n_c_e is FSEEK_EOF, the pointer is set to the size
          of the file plus _o_f_f_s_e_t.

     The returned value is the resulting pointer location.

     The obsolete function _t_e_l_l(_f_i_l_d_e_s) is identical to
     _l_s_e_e_k(_f_i_l_d_e_s, _0_L, _F_S_E_E_K__R_E_L_A_T_I_V_E).

     Seeking far beyond the end of a file, then writing, creates
     a gap or `hole', which occupies no physical space and reads
     as zeros.

RETURN VALUE
     Upon successful completion, the new file offset returned.
     Otherwise, a value of -1 is returned and _e_r_r_n_o is set to
     indicate the error.

ERRORS
     _L_s_e_e_k will fail and the file pointer will remain unchanged
     if:

     [EBADF]             _F_i_l_d_e_s is not an open file descriptor.

     [ESPIPE]            _F_i_l_d_e_s is associated with a pipe.

SEE ALSO
     creat(2), open(2), fseek(3S)

Printed 6/30/83                                                 1

LSEEK(2)            UNIX Programmer's Manual             LSEEK(2)

BUGS
     _L_s_e_e_k is a no-op on character special files.  No bounds
     check is made on _o_f_f_s_e_t.  It is permissible to seek past the
     end of a file open only for reading.

ASSEMBLER
     (lseek = 19.)
     (file descriptor in r0)
     sys lseek; offset1; offset2; whence

     _O_f_f_s_e_t_1 and _o_f_f_s_e_t_2 are the high and low words of _o_f_f_s_e_t; r0
     and r1 contain the pointer upon return.

Printed 6/30/83                                                 2