svn commit: r295764 - head/lib/libc/sys

[Maxim Sobolev]

Author: sobomax
Date: Thu Feb 18 18:41:40 2016
New Revision: 295764
URL: https://svnweb.freebsd.org/changeset/base/295764

Log:
  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

Modified:
  head/lib/libc/sys/lseek.2

Modified: head/lib/libc/sys/lseek.2
==============================================================================
--- head/lib/libc/sys/lseek.2	Thu Feb 18 17:09:55 2016	(r295763)
+++ head/lib/libc/sys/lseek.2	Thu Feb 18 18:41:40 2016	(r295764)
@@ -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 
 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