Right now, the "virtual hole" API feature of lseek(2) is very vaguely

documented and easy to miss.

At the same time, it's pretty important for anyone who is trying to use
SEEK_HOLE/SEEK_DATA in real app. Try to bridge that gap by making that
description more pronounced and also document how it affects failure codes.

Reviewed by:	kib
Differential Revision:	https://reviews.freebsd.org/D5162

1 files changed, 12 insertions, 4 deletions

diff --git a/lib/libc/sys/lseek.2 b/lib/libc/sys/lseek.2
index 349940a..ed75138 100644
--- a/lib/libc/sys/lseek.2
+++ b/lib/libc/sys/lseek.2
@@ -131,8 +131,14 @@ 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.
+Each file is presented as having a zero-size virtual hole at the very
+end of the 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.
+programming and also provides compatibility to the original imlementation
+in Solaris.
+It also causes the current file size (i.e. end-of-file offset) to be returned
+to indicate that there are no more holes past the supplied
+.Fa offset .
 Applications should use
 .Fn fpathconf _PC_MIN_HOLE_SIZE
 or
@@ -176,9 +182,11 @@ be negative for a non-character special file.
 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.
+Due to existence of the hole at the end of the file, for
+.Dv SEEK_HOLE
+this error is only returned when the
+.Fa offset
+already points to the end-of-file position.
 .It Bq Er EOVERFLOW
 The resulting file offset would be a value which cannot be represented
 correctly in an object of type