Differential D17917 Diff 50397 lib/libc/sys/getdirentries.2

Changeset View

Standalone View

lib/libc/sys/getdirentries.2

	Show All 22 Lines
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" @(#)getdirentries.2 8.2 (Berkeley) 5/3/95			.\" @(#)getdirentries.2 8.2 (Berkeley) 5/3/95
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd May 28, 2017			.Dd Nov 14, 2018
	.Dt GETDIRENTRIES 2			.Dt GETDIRENTRIES 2
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm getdirentries ,			.Nm getdirentries ,
	.Nm getdents			.Nm getdents
	.Nd "get directory entries in a file system independent format"			.Nd "get directory entries in a file system independent format"
	.Sh LIBRARY			.Sh LIBRARY
	.Lb libc			.Lb libc
	▲ Show 20 Lines • Show All 43 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
				field returns a cookie which can be used with
				kibUnsubmitted Not Done Inline Actions 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. kib: I still do not like/cannot agree with this terminology. What are the units for this metric ?
				.Xr lseek 2
				to position the directory descriptor to the next entry.
				kibUnsubmitted Not Done Inline Actions What 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…
				jack_gandi.netAuthorUnsubmitted Done Inline Actions You 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…
				kibUnsubmitted Not Done Inline Actions No, 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…
				rmacklemUnsubmitted Not Done Inline Actions You might also mention that d_off is meant to be compatible with the directory_offset_cookie in an NFS Readdir reply, since that is what you are using it for. (Just a possible suggestion. I'll leave it up to you.) rmacklem: You might also mention that d_off is meant to be compatible with the directory_offset_cookie in…
				jack_gandi.netAuthorUnsubmitted 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…
				kibUnsubmitted Not Done Inline Actions Formally, 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: The d_off entry returns a handle which can be used with lseek(2) to position the directory descriptor to the start of the entry next to the current. 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 IMPLEMENTATION NOTES
				The
				.Fa d_off
				field is being used as a cookie to readdir for nfs servers. These cookies can be
				kibUnsubmitted Not Done Inline Actions Start a new sentence from the new line. kib: Start a new sentence from the new line.
				cached and allow to read directory entries at a specific offset on demand.
	.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
	is set to indicate the error.			is set to indicate the error.
	.Sh ERRORS			.Sh ERRORS
	The			The
	.Fn getdirentries			.Fn getdirentries
	Show All 38 Lines