mirror of https://github.com/mkerrisk/man-pages
280 lines
8.0 KiB
Groff
280 lines
8.0 KiB
Groff
.\" Copyright (c) 1980, 1991 Regents of the University of California.
|
|
.\" and Copyright (c) 2011, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" @(#)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 2021-03-22 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
lseek \- reposition read/write file offset
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <unistd.h>
|
|
.PP
|
|
.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.
|
|
.PP
|
|
.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 version 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).
|
|
.PP
|
|
In both of the above cases,
|
|
.BR lseek ()
|
|
fails if
|
|
.I offset
|
|
points past the end of the file.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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
|
|
.BR SEEK_HOLE
|
|
always return the offset of the end of the file,
|
|
and making
|
|
.BR SEEK_DATA
|
|
always return
|
|
.IR 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
|
|
.PP
|
|
The
|
|
.BR _GNU_SOURCE
|
|
feature test macro must be defined in order to obtain the definitions of
|
|
.BR SEEK_DATA
|
|
and
|
|
.BR SEEK_HOLE
|
|
from
|
|
.IR <unistd.h> .
|
|
.PP
|
|
The
|
|
.BR SEEK_HOLE
|
|
and
|
|
.BR SEEK_DATA
|
|
operations are supported for the following filesystems:
|
|
.IP * 3
|
|
Btrfs (since Linux 3.1)
|
|
.IP * 3
|
|
OCFS (since Linux 3.2)
|
|
.\" commit 93862d5e1ab875664c6cc95254fc365028a48bb1
|
|
.IP *
|
|
XFS (since Linux 3.5)
|
|
.IP *
|
|
ext4 (since Linux 3.8)
|
|
.IP *
|
|
.BR tmpfs (5)
|
|
(since Linux 3.8)
|
|
.IP *
|
|
NFS (since Linux 3.18)
|
|
.\" commit 1c6dcbe5ceff81c2cf8d929646af675cd59fe7c0
|
|
.\" commit 24bab491220faa446d945624086d838af41d616c
|
|
.IP *
|
|
FUSE (since Linux 4.5)
|
|
.\" commit 0b5da8db145bfd44266ac964a2636a0cf8d7c286
|
|
.IP *
|
|
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 CONFORMING TO
|
|
POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
|
|
.PP
|
|
.BR SEEK_DATA
|
|
and
|
|
.BR 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.
|
|
.PP
|
|
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 ().
|
|
.PP
|
|
The
|
|
.I off_t
|
|
data type is a signed integer data type specified by POSIX.1.
|
|
.PP
|
|
Some devices are incapable of seeking and POSIX does not specify which
|
|
devices must support
|
|
.BR lseek ().
|
|
.PP
|
|
On Linux, using
|
|
.BR lseek ()
|
|
on a terminal device fails with the error
|
|
\fBESPIPE\fP.
|
|
.\" Other systems return the number of written characters,
|
|
.\" using SEEK_SET to set the counter. (Of written characters.)
|
|
.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)
|