Changeset View
Standalone View
lib/libc/sys/getdirentries.2
Show First 20 Lines • Show All 82 Lines • ▼ Show 20 Lines | |||||
.Fa d_fileno | .Fa d_fileno | ||||
entry is a number which is unique for each | entry is a number which is unique for each | ||||
distinct file in the file system. | distinct file in the file system. | ||||
Files that are linked by hard links (see | Files that are linked by hard links (see | ||||
.Xr link 2 ) | .Xr link 2 ) | ||||
have the same | have the same | ||||
.Fa d_fileno . | .Fa d_fileno . | ||||
The | The | ||||
.Fa d_off | |||||
entry is the distance from the start of the directory to the start of the | |||||
kib: I still do not like/cannot agree with this terminology. What are the units for this metric ? | |||||
.I next | |||||
dirent. | |||||
Not Done Inline ActionsWhat does the distance mean ? If I take it literally as the number of bytes which should be read to get from current dirent to the next one, it is false, see UDF. If the interpretation should be as the value passed to lseek(2) to position the read at the next dirent (I dare to say 'cookie'), then it has not much to do with any byte count. kib: What does the distance mean ? If I take it literally as the number of bytes which should be… | |||||
Done Inline ActionsYou are correct in most cases it isn't equivalent to d_reclen and is entirely calculated by the underlying filesystem. I took the 'distance' term from the linux manpage and I feel it is correct here because it fits the mathematical meaning of 'distance' (see https://en.wikipedia.org/wiki/Metric_(mathematics) ). Cleary it shouldn't be confused for byte count because it's not, if you like I can change the term to 'offset' or 'cookie' jack_gandi.net: You are correct in most cases it isn't equivalent to `d_reclen` and is entirely calculated by… | |||||
Not Done Inline ActionsNo, what is missing is not the juggling of the terms. What can user do with the value from d_off ? Man page must answer this question to be useful. If the only answer is for d_off to serve as the argument to lseek(2), just state it. I wondered for long time if there are any other uses or restrictions. kib: No, what is missing is not the juggling of the terms. What can user do with the value from… | |||||
Not Done Inline ActionsYou might also mention that d_off is meant to be compatible with the rmacklem: You might also mention that d_off is meant to be compatible with the
directory_offset_cookie in… | |||||
Done Inline Actions@kib It's stated that it can be used with lseek(2) in the next chunk (lines 149-151) already, along with the other lseek compatible values. It's probably not a good idea to mention nfs in the manpage as the d_off field can potentially have other uses and nfs is just one of many applications. jack_gandi.net: @kib It's stated that it can be used with `lseek(2)` in the next chunk (lines 149-151) already… | |||||
Not Done Inline ActionsFormally, the next chunk does not state what you get when you lseek(2) to the d_off. I do not see a problem with reformulating this chunk like this: kib: Formally, the next chunk does not state what you get when you lseek(2) to the d_off.
I do not… | |||||
The | |||||
.Fa d_reclen | .Fa d_reclen | ||||
entry is the length, in bytes, of the directory record. | entry is the length, in bytes, of the directory record. | ||||
The | The | ||||
.Fa d_type | .Fa d_type | ||||
entry is the type of the file pointed to by the directory record. | entry is the type of the file pointed to by the directory record. | ||||
The file type values are defined in | The file type values are defined in | ||||
.Fa <sys/dirent.h> . | .Fa <sys/dirent.h> . | ||||
The | The | ||||
Show All 36 Lines | |||||
Alternatively, the current position pointer may be set and retrieved by | Alternatively, the current position pointer may be set and retrieved by | ||||
.Xr lseek 2 . | .Xr lseek 2 . | ||||
The current position pointer should only be set to a value returned by | The current position pointer should only be set to a value returned by | ||||
.Xr lseek 2 , | .Xr lseek 2 , | ||||
a value returned in the location pointed to by | a value returned in the location pointed to by | ||||
.Fa basep | .Fa basep | ||||
.Po Fn getdirentries | .Po Fn getdirentries | ||||
only | only | ||||
.Pc | .Pc , | ||||
a value returned in the | |||||
.Fa d_off | |||||
field, | |||||
or zero. | or zero. | ||||
.Sh RETURN VALUES | .Sh RETURN VALUES | ||||
If successful, the number of bytes actually transferred is returned. | If successful, the number of bytes actually transferred is returned. | ||||
Otherwise, -1 is returned and the global variable | Otherwise, -1 is returned and the global variable | ||||
.Va errno | .Va errno | ||||
Not Done Inline ActionsStart a new sentence from the new line. kib: Start a new sentence from the new line. | |||||
is set to indicate the error. | is set to indicate the error. | ||||
.Sh ERRORS | .Sh ERRORS | ||||
The | The | ||||
.Fn getdirentries | .Fn getdirentries | ||||
system call | system call | ||||
will fail if: | will fail if: | ||||
.Bl -tag -width Er | .Bl -tag -width Er | ||||
.It Bq Er EBADF | .It Bq Er EBADF | ||||
Show All 34 Lines |
I still do not like/cannot agree with this terminology. What are the units for this metric ?
Traditionally, we use the terms 'handle' when describing some abstract value which allows to manipulate an object. The handle from d_off allows lseek(2) to position the directory descriptor to the location for returning the next dirent, is this correct ? I do not see a reason why the term handle would be not appropriate there.