summaryrefslogtreecommitdiffstats
path: root/man2/lseek.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/lseek.2')
-rw-r--r--man2/lseek.2252
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)