mirror of https://github.com/mkerrisk/man-pages
lseek.2: Document SEEK_HOLE and SEEK_DATA
These flags, designed for discovering holes in a file, were added in Linux 3.1. Included comments from Eric Blake and Sunil Mushran. Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Sunil Mushran <sunil.mushran@oracle.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
b9d482436e
commit
1e0819c860
92
man2/lseek.2
92
man2/lseek.2
|
@ -1,5 +1,6 @@
|
||||||
'\" t
|
'\" t
|
||||||
.\" Copyright (c) 1980, 1991 Regents of the University of California.
|
.\" Copyright (c) 1980, 1991 Regents of the University of California.
|
||||||
|
.\" and Copyright (c) 2011, Michael Kerrisk <mtk.manpages@gmail.com>
|
||||||
.\" All rights reserved.
|
.\" All rights reserved.
|
||||||
.\"
|
.\"
|
||||||
.\" Redistribution and use in source and binary forms, with or without
|
.\" Redistribution and use in source and binary forms, with or without
|
||||||
|
@ -39,10 +40,9 @@
|
||||||
.\" <michael@cantor.informatik.rwth-aachen.de>
|
.\" <michael@cantor.informatik.rwth-aachen.de>
|
||||||
.\" Modified 2001-09-24 by Michael Haardt <michael@moria.de>
|
.\" Modified 2001-09-24 by Michael Haardt <michael@moria.de>
|
||||||
.\" Modified 2003-08-21 by Andries Brouwer <aeb@cwi.nl>
|
.\" Modified 2003-08-21 by Andries Brouwer <aeb@cwi.nl>
|
||||||
|
.\" 2011-09-18, mtk, Added SEEK_DATA + SEEK_HOLE
|
||||||
.\"
|
.\"
|
||||||
.\" FIXME: Linux 3.1 adds SEEK_HOLE and SEEK_DATA
|
.TH LSEEK 2 2011-09-20 "Linux" "Linux Programmer's Manual"
|
||||||
.\"
|
|
||||||
.TH LSEEK 2 2011-09-18 "Linux" "Linux Programmer's Manual"
|
|
||||||
.SH NAME
|
.SH NAME
|
||||||
lseek \- reposition read/write file offset
|
lseek \- reposition read/write file offset
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
|
@ -85,6 +85,70 @@ 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
|
If data is later written at this point, subsequent reads of the data
|
||||||
in the gap (a "hole") return null bytes (\(aq\\0\(aq) until
|
in the gap (a "hole") return null bytes (\(aq\\0\(aq) until
|
||||||
data is actually written into the gap.
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
For the purposes of these operations, a hole is a sequence of zeroes that
|
||||||
|
(normally) has not been allocated in the underlying file storage.
|
||||||
|
However, a file system 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 zeroes that actually has been written
|
||||||
|
to the underlying storage may not be reported as a hole.)
|
||||||
|
In the simplest implementation,
|
||||||
|
a file system 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
|
||||||
|
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 zeroes).
|
||||||
|
.\" https://lkml.org/lkml/2011/4/22/79
|
||||||
|
.\" http://lwn.net/Articles/440255/
|
||||||
|
.\" http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data
|
||||||
.SH "RETURN VALUE"
|
.SH "RETURN VALUE"
|
||||||
Upon successful completion,
|
Upon successful completion,
|
||||||
.BR lseek ()
|
.BR lseek ()
|
||||||
|
@ -101,11 +165,8 @@ is not an open file descriptor.
|
||||||
.TP
|
.TP
|
||||||
.B EINVAL
|
.B EINVAL
|
||||||
.I whence
|
.I whence
|
||||||
is not one of
|
is not valid.
|
||||||
.BR SEEK_SET ,
|
Or: the resulting file offset would be negative,
|
||||||
.BR SEEK_CUR ,
|
|
||||||
.BR SEEK_END ;
|
|
||||||
or the resulting file offset would be negative,
|
|
||||||
or beyond the end of a seekable device.
|
or beyond the end of a seekable device.
|
||||||
.\" Some systems may allow negative offsets for character devices
|
.\" Some systems may allow negative offsets for character devices
|
||||||
.\" and/or for remote file systems.
|
.\" and/or for remote file systems.
|
||||||
|
@ -118,8 +179,23 @@ The resulting file offset cannot be represented in an
|
||||||
.B ESPIPE
|
.B ESPIPE
|
||||||
.I fd
|
.I fd
|
||||||
is associated with a pipe, socket, or FIFO.
|
is associated with a pipe, socket, or FIFO.
|
||||||
|
.TP
|
||||||
|
.B ENXIO
|
||||||
|
.I whence
|
||||||
|
is
|
||||||
|
.B SEEK_DATA
|
||||||
|
or
|
||||||
|
.BR SEEK_HOLE ,
|
||||||
|
and the current file offset is beyond the end of the file.
|
||||||
.SH "CONFORMING TO"
|
.SH "CONFORMING TO"
|
||||||
SVr4, 4.3BSD, POSIX.1-2001.
|
SVr4, 4.3BSD, POSIX.1-2001.
|
||||||
|
|
||||||
|
.BR SEEK_DATA
|
||||||
|
and
|
||||||
|
.BR SEEK_HOLE
|
||||||
|
are nonstandard extensions also present in Solaris;
|
||||||
|
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
|
.SH NOTES
|
||||||
Some devices are incapable of seeking and POSIX does not specify which
|
Some devices are incapable of seeking and POSIX does not specify which
|
||||||
devices must support
|
devices must support
|
||||||
|
|
Loading…
Reference in New Issue