Implement SEEK_DATA and SEEK_HOLE extensions to lseek(2) as found in

OpenSolaris. For more information please refer to:

	http://blogs.sun.com/bonwick/entry/seek_hole_and_seek_data

1 files changed, 53 insertions, 1 deletions

diff --git a/lib/libc/sys/lseek.2 b/lib/libc/sys/lseek.2
index df225f3..6fdf79b 100644
--- a/lib/libc/sys/lseek.2
+++ b/lib/libc/sys/lseek.2
@@ -87,6 +87,23 @@ the offset is set to the size of the
 file plus
 .Fa offset
 bytes.
+.It
+If
+.Fa whence
+is
+.Dv SEEK_HOLE ,
+the offset of the start of the next hole greater than or equal to the supplied
+.Fa offset
+is returned.
+The definition of a hole is provided below.
+.It
+If
+.Fa whence
+is
+.Dv SEEK_DATA ,
+the offset is set to the start of the next non-hole file region greater
+than or equal to the supplied
+.Fa offset .
 .El
 .Pp
 The
@@ -100,6 +117,33 @@ bytes of zeros (until data is actually written into the gap).
 Some devices are incapable of seeking.
 The value of the pointer
 associated with such a device is undefined.
+.Pp
+A
+.Qq hole
+is defined as a contiguous range of bytes in a file, all having the value of
+zero, but not all zeros in a file are guaranteed to be represented as holes
+returned with
+.Dv SEEK_HOLE .
+File systems are allowed to expose ranges of zeros with
+.Dv SEEK_HOLE ,
+but not required to.
+Applications can use
+.Dv SEEK_HOLE
+to optimise their behavior for ranges of zeros, but must not depend on it to
+find all such ranges in a file.
+The existence of a hole at the end of every data region allows for easy
+programming and implies that a virtual hole exists at the end of the file.
+Applications should use
+.Fn fpathconf _PC_MIN_HOLE_SIZE
+or
+.Fn pathconf _PC_MIN_HOLE_SIZE
+to determine if a file system supports
+.Dv SEEK_HOLE .
+See
+.Xr pathconf 2 .
+.Pp
+For file systems that do not supply information about holes, the file will be
+represented as one entire data region.
 .Sh RETURN VALUES
 Upon successful completion,
 .Fn lseek
@@ -128,6 +172,13 @@ argument
 is not a proper value
 or the resulting file offset would
 be negative for a non-character special file.
+.It Bq Er ENXIO
+For
+.Dv SEEK_DATA ,
+there are no more data regions past the supplied offset.
+For
+.Dv SEEK_HOLE ,
+there are no more holes past the supplied offset.
 .It Bq Er EOVERFLOW
 The resulting file offset would be a value which cannot be represented
 correctly in an object of type
@@ -140,7 +191,8 @@ is associated with a pipe, socket, or FIFO.
 .El
 .Sh SEE ALSO
 .Xr dup 2 ,
-.Xr open 2
+.Xr open 2 ,
+.Xr pathconf 2
 .Sh STANDARDS
 The
 .Fn lseek