diff options
Diffstat (limited to 'man-pages-posix-2013/man3p/lseek.3p')
| -rw-r--r-- | man-pages-posix-2013/man3p/lseek.3p | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/man-pages-posix-2013/man3p/lseek.3p b/man-pages-posix-2013/man3p/lseek.3p new file mode 100644 index 0000000..38d3bd5 --- /dev/null +++ b/man-pages-posix-2013/man3p/lseek.3p @@ -0,0 +1,183 @@ +'\" et +.TH LSEEK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.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. + +.SH NAME +lseek +\(em move the read/write file offset +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> +.P +off_t lseek(int \fIfildes\fP, off_t \fIoffset\fP, int \fIwhence\fP); +.fi +.SH DESCRIPTION +The +\fIlseek\fR() +function shall set the file offset for the open file description +associated with the file descriptor +.IR fildes, +as follows: +.IP " *" 4 +If +.IR whence +is SEEK_SET, the file offset shall be set to +.IR offset +bytes. +.IP " *" 4 +If +.IR whence +is SEEK_CUR, the file offset shall be set to its current location plus +.IR offset . +.IP " *" 4 +If +.IR whence +is SEEK_END, the file offset shall be set to the size of the file plus +.IR offset . +.P +The symbolic constants SEEK_SET, SEEK_CUR, and SEEK_END +are defined in +.IR <unistd.h> . +.P +The behavior of +\fIlseek\fR() +on devices which are incapable of seeking is implementation-defined. +The value of the file offset associated with such a device is +undefined. +.P +The +\fIlseek\fR() +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. +.P +The +\fIlseek\fR() +function shall not, by itself, extend the size of a file. +.P +If +.IR fildes +refers to a shared memory object, the result of the +\fIlseek\fR() +function is unspecified. +.P +If +.IR fildes +refers to a typed memory object, the result of the +\fIlseek\fR() +function is unspecified. +.SH "RETURN VALUE" +Upon successful completion, the resulting offset, as measured in bytes +from the beginning of the file, shall be returned. Otherwise, \(mi1 +shall be returned, +.IR errno +shall be set to indicate the error, and the file offset shall remain +unchanged. +.SH ERRORS +The +\fIlseek\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not an open file descriptor. +.TP +.BR EINVAL +The +.IR whence +argument is not a proper value, or the resulting file offset would be +negative for a regular file, block special file, or directory. +.TP +.BR EOVERFLOW +The resulting file offset would be a value which cannot be represented +correctly in an object of type +.BR off_t . +.TP +.BR ESPIPE +The +.IR fildes +argument is associated with a pipe, FIFO, or socket. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The ISO\ C standard includes the functions +\fIfgetpos\fR() +and +\fIfsetpos\fR(), +which work on very large files by use of a special positioning type. +.P +Although +\fIlseek\fR() +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\(hy2008 that may directly extend the size of the file is +\fIwrite\fR(), +\fItruncate\fR(), +and +\fIftruncate\fR(), +several functions originally derived from the ISO\ C standard, such as +\fIfwrite\fR(), +\fIfprintf\fR(), +and so on, may do so (by causing calls on +\fIwrite\fR()). +.P +An invalid file offset that would cause +.BR [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. +.P +The POSIX.1\(hy1990 standard did not specifically prohibit +\fIlseek\fR() +from returning a negative offset. Therefore, an application was +required to clear +.IR errno +prior to the call and check +.IR errno +upon return to determine whether a return value of (\c +.BR off_t )\(mi1 +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 +.IR errno +be set to +.BR [EINVAL] +when the resulting file offset would be negative for a regular file, +block special file, or directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB<sys_types.h>\fP", +.IR "\fB<unistd.h>\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |