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

[sobomax]

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.

[kib]

lib/libc/sys/lseek.2

134

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.

185–189

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

192

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]

rework a bit based on input from @kib

[sobomax]

Thanks, please see updated revision.

[kib]

lib/libc/sys/lseek.2

139

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

189

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

[sobomax]

@kib please see my comments inline.

lib/libc/sys/lseek.2

139

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

189

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.