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.
Details
Details
- Reviewers
kib - Group Reviewers
manpages - Commits
- rS295764: Right now, the "virtual hole" API feature of lseek(2) is very vaguely
Diff Detail
Diff Detail
- Repository
- rS FreeBSD src repository - subversion
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
| 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. |
Comment Actions
@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. |