'\" 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
.\" <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 2010-09-11 "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
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 zeros 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 zeros 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 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
.SH "RETURN VALUE"
Upon successful completion,
.BR lseek ()
.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.
.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.
-.SH NOTES
-This document's use of
-.I whence
-is incorrect English, but maintained for historical reasons.
+.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
.BR lseek ().
OSDN Git Service
