# lseek

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           lseek — move the read/write file offset
    


## SYNOPSIS



           #include <unistd.h>
    
           off_t lseek(int _fildes_ , off_t _offset_ , int _whence_);
    


## DESCRIPTION



           The _lseek_() function shall set the file offset for the open file
           description associated with the file descriptor _fildes,_ as
           follows:
    
            *  If _whence_ is SEEK_SET, the file offset shall be set to _offset_
               bytes.
    
            *  If _whence_ is SEEK_CUR, the file offset shall be set to its
               current location plus _offset_.
    
            *  If _whence_ is SEEK_END, the file offset shall be set to the
               size of the file plus _offset_.
    
           The symbolic constants SEEK_SET, SEEK_CUR, and SEEK_END are
           defined in _< unistd.h>_.
    
           The behavior of _lseek_() on devices which are incapable of seeking
           is implementation-defined.  The value of the file offset
           associated with such a device is undefined.
    
           The _lseek_() function shall allow the file offset to be set beyond
           the end of the existing data in the file. If data is later written
           at this point, subsequent reads of data in the gap shall return
           bytes with the value 0 until data is actually written into the
           gap.
    
           The _lseek_() function shall not, by itself, extend the size of a
           file.
    
           If _fildes_ refers to a shared memory object, the result of the
           _lseek_() function is unspecified.
    
           If _fildes_ refers to a typed memory object, the result of the
           _lseek_() function is unspecified.
    


## RETURN VALUE



           Upon successful completion, the resulting offset, as measured in
           bytes from the beginning of the file, shall be returned.
           Otherwise, -1 shall be returned, _errno_ shall be set to indicate
           the error, and the file offset shall remain unchanged.
    


## ERRORS



           The _lseek_() function shall fail if:
    
           **EBADF** The _fildes_ argument is not an open file descriptor.
    
           **EINVAL** The _whence_ argument is not a proper value, or the resulting
                  file offset would be negative for a regular file, block
                  special file, or directory.
    
           **EOVERFLOW**
                  The resulting file offset would be a value which cannot be
                  represented correctly in an object of type **off_t**.
    
           **ESPIPE** The _fildes_ argument is associated with a pipe, FIFO, or
                  socket.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           The ISO C standard includes the functions _fgetpos_() and _fsetpos_(),
           which work on very large files by use of a special positioning
           type.
    
           Although _lseek_() may position the file offset beyond the end of
           the file, this function does not itself extend the size of the
           file. While the only function in POSIX.1‐2008 that may directly
           extend the size of the file is _write_(), _truncate_(), and
           _ftruncate_(), several functions originally derived from the ISO C
           standard, such as _fwrite_(), _fprintf_(), and so on, may do so (by
           causing calls on _write_()).
    
           An invalid file offset that would cause **[EINVAL]** to be returned
           may be both implementation-defined and device-dependent (for
           example, memory may have few invalid values). A negative file
           offset may be valid for some devices in some implementations.
    
           The POSIX.1‐1990 standard did not specifically prohibit _lseek_()
           from returning a negative offset. Therefore, an application was
           required to clear _errno_ prior to the call and check _errno_ upon
           return to determine whether a return value of (**off_t**)-1 is a
           negative offset or an indication of an error condition. The
           standard developers did not wish to require this action on the
           part of a conforming application, and chose to require that _errno_
           be set to **[EINVAL]** when the resulting file offset would be
           negative for a regular file, block special file, or directory.
    


## FUTURE DIRECTIONS



           None.
    


* * *