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:
Michael Kerrisk
parent
b9d482436e
commit
1e0819c860
92
man2/lseek.2
92
man2/lseek.2
|
|
@ -1,5 +1,6 @@
|
|||
'\" t
|
||||
.\" Copyright (c) 1980, 1991 Regents of the University of California.
|
||||
.\" and Copyright (c) 2011, Michael Kerrisk <mtk.manpages@gmail.com>
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
|
|
@ -39,10 +40,9 @@
|
|||
.\" <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
|
||||
.\"
|
||||
.\" FIXME: Linux 3.1 adds SEEK_HOLE and SEEK_DATA
|
||||
.\"
|
||||
.TH LSEEK 2 2011-09-18 "Linux" "Linux Programmer's Manual"
|
||||
.TH LSEEK 2 2011-09-20 "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
lseek \- reposition read/write file offset
|
||||
.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
|
||||
in the gap (a "hole") return null bytes (\(aq\\0\(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.
|
||||
|
||||
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"
|
||||
Upon successful completion,
|
||||
.BR lseek ()
|
||||
|
|
@ -101,11 +165,8 @@ is not an open file descriptor.
|
|||
.TP
|
||||
.B EINVAL
|
||||
.I whence
|
||||
is not one of
|
||||
.BR SEEK_SET ,
|
||||
.BR SEEK_CUR ,
|
||||
.BR SEEK_END ;
|
||||
or the resulting file offset would be negative,
|
||||
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 file systems.
|
||||
|
|
@ -118,8 +179,23 @@ The resulting file offset cannot be represented in an
|
|||
.B ESPIPE
|
||||
.I fd
|
||||
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"
|
||||
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
|
||||
Some devices are incapable of seeking and POSIX does not specify which
|
||||
devices must support
|
||||
|
|
|
|||
Loading…
Reference in New Issue