2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "LSEEK" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" lseek
|
2007-09-20 06:03:25 +00:00
|
|
|
.SH 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.
|
2004-11-03 13:51:07 +00:00
|
|
|
.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
|
2007-09-20 06:11:55 +00:00
|
|
|
\fIopen\fP(), the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
2004-11-03 13:51:07 +00:00
|
|
|
\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 .
|