summaryrefslogtreecommitdiffstats
path: root/man/man2/lseek.2
diff options
context:
space:
mode:
Diffstat (limited to 'man/man2/lseek.2')
-rw-r--r--man/man2/lseek.2252
1 files changed, 252 insertions, 0 deletions
diff --git a/man/man2/lseek.2 b/man/man2/lseek.2
new file mode 100644
index 0000000..5e458f4
--- /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 2024-05-02 "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)