llsseeeekk() -- System Call (libc)

Set read/write position
#iinncclluuddee <uunniissttdd.hh>
lloonngg llsseeeekk(_f_d, _w_h_e_r_e, _h_o_w)
iinntt _f_d, _h_o_w; lloonngg _w_h_e_r_e;

llsseeeekk() changes  the _s_e_e_k _p_o_s_i_t_i_o_n,  or the point  within a file  where the
next  read  or  write  operation  is  performed.  _f_d  is  the  file's  file
descriptor, which is returned by ooppeenn().

_w_h_e_r_e and  _h_o_w describe the new  seek position.  _w_h_e_r_e gives  the number of
bytes that  you wish to  move the seek  position.  It is  measured from the
beginning of the file if _h_o_w  equals SSEEEEKK_SSEETT (zero), from the current seek
position if _h_o_w equals SSEEEEKK_CCUURR (one),  and from the end of the file if _h_o_w
equals two  SSEEEEKK_EENNDD (two).  A  successful call to llsseeeekk()  returns the new
seek position.  For example

    position = lseek(fd, 100L, 0);

moves the seek position 100 bytes past the beginning of the file; whereas

    position = lseek(fd, 0L, 1);

merely  returns the  current seek  position, and does  not change  the seek
position at all.

Sparse files may be created by  seeking beyond the current size of the file
and writing.  The ``hole'' between the  end of the file and where the write
occurs is read as zero and  will occupy no disk space.  For example, if you
llsseeeekk() 10,000 bytes  past the current end of file  and write a string, the
data  will  be written  10,000  bytes past  the  old end  of  file and  all
intervening matter will be considered part of the file.

llsseeeekk() differs  from its cousin ffsseeeekk()  in that llsseeeekk() is  a system call
and uses a file descriptor, whereas ffsseeeekk() is a C function and uses a FFIILLEE
pointer.

_S_e_e _A_l_s_o
lliibbcc, uunniissttdd.hh
POSIX Standard, section 6.5.3

_D_i_a_g_n_o_s_t_i_c_s
llsseeeekk() returns  -11LL on an error,  such as seeking to  a negative position.
If no error occurs, it returns the new seek position.

_N_o_t_e_s
llsseeeekk()  is  permitted  on  character-special  files,  but drivers  do  not
generally implement it.  As a  result, seeking a terminal will not generate
an error but will have no discernible effect.
