diff options
Diffstat (limited to 'man2/lseek.2')
| -rw-r--r-- | man2/lseek.2 | 252 |
1 files changed, 0 insertions, 252 deletions
diff --git a/man2/lseek.2 b/man2/lseek.2 deleted file mode 100644 index 93b3f6d..0000000 --- a/man2/lseek.2 +++ /dev/null @@ -1,252 +0,0 @@ -.\" 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 2023-10-31 "Linux man-pages 6.7" -.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) |