Page MenuHomeFreeBSD

Better document "virtual hole" feature of the lseek(SEEK_HOLE)
ClosedPublic

Authored by sobomax on Feb 1 2016, 8:11 PM.
Tags
None
Referenced Files
Unknown Object (File)
Sun, Mar 10, 11:00 AM
Unknown Object (File)
Feb 4 2024, 10:46 PM
Unknown Object (File)
Jan 5 2024, 4:50 PM
Unknown Object (File)
Jan 5 2024, 4:15 AM
Unknown Object (File)
Dec 20 2023, 1:40 AM
Unknown Object (File)
Nov 13 2023, 9:42 AM
Unknown Object (File)
Oct 16 2023, 1:55 AM
Unknown Object (File)
Sep 20 2023, 1:36 AM

Details

Summary

Right now, the "virtual hole" 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.

Diff Detail

Repository
rS FreeBSD src repository - subversion
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

sobomax retitled this revision from to Better document "virtual hole" feature of the lseek(SEEK_HOLE).
sobomax updated this object.
sobomax edited the test plan for this revision. (Show Details)
sobomax set the repository for this revision to rS FreeBSD src repository - subversion.
sobomax added a subscriber: kib.
lib/libc/sys/lseek.2
134 ↗(On Diff #12934)

I do not see a need in the introductory 'for convinience ...' construction in the statement. You could add that to the next sentence, where the justification about ease of programming is made.

181 ↗(On Diff #12934)

... hole at the end of the file, for ...

188 ↗(On Diff #12934)

And this description describes your confusion, I do not think that it is needed in the man page. In other words, I do not see a need to explain, in the error description, why the error is not returned at all.

You may add a note nearby the virtual hole explanation, that its existence make SEEK_HOLE at EOF return file length, which would be also less confusing to readers.

sobomax edited edge metadata.

rework a bit based on input from @kib

Thanks, please see updated revision.

lib/libc/sys/lseek.2
139 ↗(On Diff #12935)

This sentence should specify when this happens (at the offset equal to the EOF).

189 ↗(On Diff #12935)

This statement is simply not true. Your test program proves that.

@kib please see my comments inline.

lib/libc/sys/lseek.2
139 ↗(On Diff #12935)

Well, not really, it would happen at any offset as long as there is no "real" holes past this offset till EOF.

189 ↗(On Diff #12935)

No it does not. We are not testing for that really in my test program, to do so you'd need to use "lseek(fd, <file_size>, SEEK_HOLE)", not "lseek(fd, 0, SEEK_HOLE)" and it indeed returns ENXIO. This is the reason why both lseek(0, SEEK_HOLE) and lseek(0, SEEK_DATA) return ENXIO on empty file, since offset 0 is EOF. Which is why I am talking about zero-size hole here. When probing any offset within a real hole, the lseek(fd, <offset_within_hole>, SEEK_HOLE) returns just <offset_within_hole>, but the virtual hole has no size, so if you hit that offset with SEEK_HOLE it would ENXIO.

kib added a reviewer: kib.
This revision is now accepted and ready to land.Feb 1 2016, 9:23 PM
This revision was automatically updated to reflect the committed changes.