.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "LSEEK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" lseek 
.SH NAME
lseek \- move the read/write file offset
.SH SYNOPSIS
.LP
\fB#include <unistd.h>
.br
.sp
off_t lseek(int\fP \fIfildes\fP\fB, off_t\fP \fIoffset\fP\fB, int\fP
\fIwhence\fP\fB);
.br
\fP
.SH DESCRIPTION
.LP
The \fIlseek\fP() function shall set the file offset for the open
file description associated with the file descriptor
\fIfildes,\fP as follows:
.IP " *" 3
If \fIwhence\fP is SEEK_SET, the file offset shall be set to \fIoffset\fP
bytes.
.LP
.IP " *" 3
If \fIwhence\fP is SEEK_CUR, the file offset shall be set to its current
location plus \fIoffset\fP.
.LP
.IP " *" 3
If \fIwhence\fP is SEEK_END, the file offset shall be set to the size
of the file plus \fIoffset\fP.
.LP
.LP
The symbolic constants SEEK_SET, SEEK_CUR, and SEEK_END are defined
in \fI<unistd.h>\fP.
.LP
The behavior of \fIlseek\fP() on devices which are incapable of seeking
is implementation-defined. The value of the file offset
associated with such a device is undefined.
.LP
The \fIlseek\fP() 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.
.LP
The \fIlseek\fP() function shall not, by itself, extend the size of
a file.
.LP
If \fIfildes\fP refers to a shared memory object, the result of the
\fIlseek\fP() function is unspecified. 
.LP
If \fIfildes\fP refers to a typed memory object, the result of the
\fIlseek\fP() function is unspecified. 
.SH RETURN VALUE
.LP
Upon successful completion, the resulting offset, as measured in bytes
from the beginning of the file, shall be returned.
Otherwise, (\fBoff_t\fP)-1 shall be returned, \fIerrno\fP shall be
set to indicate the error, and the file offset shall remain
unchanged.
.SH ERRORS
.LP
The \fIlseek\fP() function shall fail if:
.TP 7
.B EBADF
The \fIfildes\fP argument is not an open file descriptor.
.TP 7
.B EINVAL
The \fIwhence\fP argument is not a proper value, or the resulting
file offset would be negative for a regular file, block
special file, or directory.
.TP 7
.B EOVERFLOW
The resulting file offset would be a value which cannot be represented
correctly in an object of type \fBoff_t\fP.
.TP 7
.B ESPIPE
The \fIfildes\fP argument is associated with a pipe, FIFO, or socket.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
The ISO\ C standard includes the functions \fIfgetpos\fP() and \fIfsetpos\fP(),
which work on very large files by use of a special positioning type.
.LP
Although \fIlseek\fP() 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 IEEE\ Std\ 1003.1-2001 that
may directly extend the size of the file is \fIwrite\fP(), \fItruncate\fP(),
and \fIftruncate\fP(), several functions originally derived from the
ISO\ C standard, such as \fIfwrite\fP(), \fIfprintf\fP(), and so on,
may do so
(by causing calls on \fIwrite\fP()).
.LP
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.
.LP
The POSIX.1-1990 standard did not specifically prohibit \fIlseek\fP()
from returning a negative offset. Therefore, an
application was required to clear \fIerrno\fP prior to the call and
check \fIerrno\fP upon return to determine whether a return
value of ( \fBoff_t\fP)-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 \fIerrno\fP be set to [EINVAL] when the
resulting file offset would be negative for a regular file, block
special file, or directory.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIopen\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
\fI<sys/types.h>\fP, \fI<unistd.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .