lseek() -- System Call (libc)

Set read/write position
#include <unistd.h>
long lseek(fd, where, how)
int fd, how; long where;

lseek() changes  the seek position,  or the point  within a file  where the
next  read  or  write  operation  is  performed.  fd  is  the  file's  file
descriptor, which is returned by open().

where and  how describe the new  seek position.  where gives  the number of
bytes that  you wish to  move the seek  position.  It is  measured from the
beginning of the file if how  equals SEEK_SET (zero), from the current seek
position if how equals SEEK_CUR (one),  and from the end of the file if how
equals SEEK_END  (two).  A successful call to lseek()  returns the new seek
position.  For example,

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

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

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

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

You can create a sparse file 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
lseek() 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.

lseek() differs  from its cousin fseek()  in that lseek() is  a system call
and uses a file descriptor, whereas fseek() is a C function and uses a FILE
pointer.

If  all goes  well, lseek()  returns the  new seek  position.  If  an error
occurs, such  as seeking  to a negative  position, lseek() returns  -1L and
sets errno to an appropriate value.

See Also

libc,
unistd.h
POSIX Standard, §6.5.3

Notes

lseek()  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.

© 2012 by Stephen A. Ness