Import of man-pages 1.70man-pages-1.70

1 files changed, 133 insertions, 0 deletions

diff --git a/man3p/lseek.3p b/man3p/lseek.3p
new file mode 100644
index 000000000..87e3805f1
--- /dev/null
+++ b/man3p/lseek.3p
@@ -0,0 +1,133 @@
+.\" 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 .