diff options
Diffstat (limited to 'man/man2/lseek.2')
| -rw-r--r-- | man/man2/lseek.2 | 252 |
1 files changed, 252 insertions, 0 deletions
diff --git a/man/man2/lseek.2 b/man/man2/lseek.2 new file mode 100644 index 000000000..14fc13734 --- /dev/null +++ b/man/man2/lseek.2 @@ -0,0 +1,252 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" and Copyright (c) 2011, Michael Kerrisk <mtk.manpages@gmail.com> +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)lseek.2 6.5 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu> +.\" Modified 1995-06-10 by Andries Brouwer <aeb@cwi.nl> +.\" Modified 1996-10-31 by Eric S. Raymond <esr@thyrsus.com> +.\" Modified 1998-01-17 by Michael Haardt +.\" <michael@cantor.informatik.rwth-aachen.de> +.\" Modified 2001-09-24 by Michael Haardt <michael@moria.de> +.\" Modified 2003-08-21 by Andries Brouwer <aeb@cwi.nl> +.\" 2011-09-18, mtk, Added SEEK_DATA + SEEK_HOLE +.\" +.TH lseek 2 (date) "Linux man-pages (unreleased)" +.SH NAME +lseek \- reposition read/write file offset +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "off_t lseek(int " fd ", off_t " offset ", int " whence ); +.fi +.SH DESCRIPTION +.BR lseek () +repositions the file offset of the open file description +associated with the file descriptor +.I fd +to the argument +.I offset +according to the directive +.I whence +as follows: +.TP +.B SEEK_SET +The file offset is set to +.I offset +bytes. +.TP +.B SEEK_CUR +The file offset is set to its current location plus +.I offset +bytes. +.TP +.B SEEK_END +The file offset is set to the size of the file plus +.I offset +bytes. +.P +.BR lseek () +allows the file offset to be set beyond the end +of the file (but this does not change the size of the file). +If data is later written at this point, subsequent reads of the data +in the gap (a "hole") return null bytes (\[aq]\e0\[aq]) until +data is actually written into the gap. +.SS Seeking file data and holes +Since Linux 3.1, Linux supports the following additional values for +.IR whence : +.TP +.B SEEK_DATA +Adjust the file offset to the next location +in the file greater than or equal to +.I offset +containing data. +If +.I offset +points to data, +then the file offset is set to +.IR offset . +.TP +.B SEEK_HOLE +Adjust the file offset to the next hole in the file +greater than or equal to +.IR offset . +If +.I offset +points into the middle of a hole, +then the file offset is set to +.IR offset . +If there is no hole past +.IR offset , +then the file offset is adjusted to the end of the file +(i.e., there is an implicit hole at the end of any file). +.P +In both of the above cases, +.BR lseek () +fails if +.I offset +points past the end of the file. +.P +These operations allow applications to map holes in a sparsely +allocated file. +This can be useful for applications such as file backup tools, +which can save space when creating backups and preserve holes, +if they have a mechanism for discovering holes. +.P +For the purposes of these operations, a hole is a sequence of zeros that +(normally) has not been allocated in the underlying file storage. +However, a filesystem is not obliged to report holes, +so these operations are not a guaranteed mechanism for +mapping the storage space actually allocated to a file. +(Furthermore, a sequence of zeros that actually has been written +to the underlying storage may not be reported as a hole.) +In the simplest implementation, +a filesystem can support the operations by making +.B SEEK_HOLE +always return the offset of the end of the file, +and making +.B SEEK_DATA +always return +.I offset +(i.e., even if the location referred to by +.I offset +is a hole, +it can be considered to consist of data that is a sequence of zeros). +.\" https://lkml.org/lkml/2011/4/22/79 +.\" http://lwn.net/Articles/440255/ +.\" http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data +.P +The +.B _GNU_SOURCE +feature test macro must be defined in order to obtain the definitions of +.B SEEK_DATA +and +.B SEEK_HOLE +from +.IR <unistd.h> . +.P +The +.B SEEK_HOLE +and +.B SEEK_DATA +operations are supported for the following filesystems: +.IP \[bu] 3 +Btrfs (since Linux 3.1) +.IP \[bu] +OCFS (since Linux 3.2) +.\" commit 93862d5e1ab875664c6cc95254fc365028a48bb1 +.IP \[bu] +XFS (since Linux 3.5) +.IP \[bu] +ext4 (since Linux 3.8) +.IP \[bu] +.BR tmpfs (5) +(since Linux 3.8) +.IP \[bu] +NFS (since Linux 3.18) +.\" commit 1c6dcbe5ceff81c2cf8d929646af675cd59fe7c0 +.\" commit 24bab491220faa446d945624086d838af41d616c +.IP \[bu] +FUSE (since Linux 4.5) +.\" commit 0b5da8db145bfd44266ac964a2636a0cf8d7c286 +.IP \[bu] +GFS2 (since Linux 4.15) +.\" commit 3a27411cb4bc3ce31db228e3569ad01b462a4310 +.SH RETURN VALUE +Upon successful completion, +.BR lseek () +returns the resulting offset location as measured in bytes from the +beginning of the file. +On error, the value \fI(off_t)\ \-1\fP is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not an open file descriptor. +.TP +.B EINVAL +.I whence +is not valid. +Or: the resulting file offset would be negative, +or beyond the end of a seekable device. +.\" Some systems may allow negative offsets for character devices +.\" and/or for remote filesystems. +.TP +.B ENXIO +.I whence +is +.B SEEK_DATA +or +.BR SEEK_HOLE , +and +.I offset +is beyond the end of the file, or +.I whence +is +.B SEEK_DATA +and +.I offset +is within a hole at the end of the file. +.TP +.B EOVERFLOW +.\" HP-UX 11 says EINVAL for this case (but POSIX.1 says EOVERFLOW) +The resulting file offset cannot be represented in an +.IR off_t . +.TP +.B ESPIPE +.I fd +is associated with a pipe, socket, or FIFO. +.SH VERSIONS +On Linux, using +.BR lseek () +on a terminal device fails with the error +.BR ESPIPE . +.\" Other systems return the number of written characters, +.\" using SEEK_SET to set the counter. (Of written characters.) +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.P +.B SEEK_DATA +and +.B SEEK_HOLE +are nonstandard extensions also present in Solaris, +FreeBSD, and DragonFly BSD; +they are proposed for inclusion in the next POSIX revision (Issue 8). +.\" FIXME . Review http://austingroupbugs.net/view.php?id=415 in the future +.SH NOTES +See +.BR open (2) +for a discussion of the relationship between file descriptors, +open file descriptions, and files. +.P +If the +.B O_APPEND +file status flag is set on the open file description, +then a +.BR write (2) +.I always +moves the file offset to the end of the file, regardless of the use of +.BR lseek (). +.P +Some devices are incapable of seeking and POSIX does not specify which +devices must support +.BR lseek (). +.SH SEE ALSO +.BR dup (2), +.BR fallocate (2), +.BR fork (2), +.BR open (2), +.BR fseek (3), +.BR lseek64 (3), +.BR posix_fallocate (3) |