d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Maxim Sobolev 2016-02-18 18:41:40 +00:00
parent 910905c74f
commit a050ef0997
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=295764
1 changed files with 12 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
lib/libc/sys/lseek.2
View File

@ -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