X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/2d21ac55c334faf3a56e5634905ed6987fc787d4..0a7de7458d150b5d4dffc935ba399be265ef0a1a:/bsd/man/man2/getdirentries.2

diff --git a/bsd/man/man2/getdirentries.2 b/bsd/man/man2/getdirentries.2
index b0fedddaa..f465c5790 100644
--- a/bsd/man/man2/getdirentries.2
+++ b/bsd/man/man2/getdirentries.2
@@ -40,12 +40,13 @@
 .Nm getdirentries
 .Nd "get directory entries in a filesystem independent format"
 .Sh SYNOPSIS
+.Fd #include <dirent.h>
 .Fd #include <sys/types.h>
 .Fd #include <sys/dirent.h>
 .Ft int
 .Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep"
 .Sh DESCRIPTION
-.Fn Getdirentries
+.Fn getdirentries
 reads directory entries from the directory
 referenced by the file descriptor
 .Fa fd
@@ -66,14 +67,12 @@ with buffers smaller than this size.
 .Pp
 The data in the buffer is a series of
 .Em dirent
-structures each containing the following entries:
-.Bd -literal -offset indent
-u_int32_t	d_fileno;             /* file number of entry */
-u_int16_t	d_reclen;             /* length of this record */
-u_int8_t	d_type;               /* file type, see below */
-u_int8_t	d_namlen;             /* length of string in d_name */
-char    	d_name[MAXNAMELEN + 1]; /* see below */
-.Ed
+structures (see
+.Xr dir 5)
+The order of the directory entries vended out via 
+.Fn getdirentries
+is not specified. Some filesystems may return entries in lexicographic sort order
+and others may not. 
 .Pp
 The
 .Fa d_fileno
@@ -134,7 +133,7 @@ The pointer may not advance by the number of bytes returned by
 A value of zero is returned when
 the end of the directory has been reached.
 .Pp
-.Fn Getdirentries
+.Fn getdirentries
 writes the position of the block read into the location pointed to by
 .Fa basep .
 Alternatively, the current position pointer may be set and retrieved by
@@ -144,13 +143,39 @@ The current position pointer should only be set to a value returned by
 a value returned in the location pointed to by
 .Fa basep ,
 or zero.
+.Sh NOTES
+.Fn getdirentries
+should rarely be used directly; instead,
+.Xr opendir 3
+and
+.Xr readdir 3
+should be used.
+.Pp
+As of Mac OS X 10.6,
+.Fn getdirentries
+is deprecated, and it is recommended that applications
+use
+.Xr readdir 3
+rather than using
+.Fn getdirentries
+directly.  Due to limitations with the system call, 
+.Fn getdirentries
+will not work
+with 64-bit inodes; in order to use
+.Fn getdirentries ,
+.Dv _DARWIN_NO_64_BIT_INODE
+must be defined.  See
+.Xr stat 2
+for more information on
+.Dv _DARWIN_NO_64_BIT_INODE
+and its other effects.
 .Sh RETURN VALUES
 If successful, the number of bytes actually transferred is returned.
 Otherwise, -1 is returned and the global variable
 .Va errno
 is set to indicate the error.
 .Sh ERRORS
-.Fn Getdirentries
+.Fn getdirentries
 will fail if:
 .Bl -tag -width Er
 .It Bq Er EBADF
@@ -169,7 +194,11 @@ error occurred while reading from or writing to the file system.
 .El
 .Sh SEE ALSO
 .Xr lseek 2 ,
-.Xr open 2
+.Xr open 2 ,
+.Xr stat 2 ,
+.Xr opendir 3 ,
+.Xr readdir 3 ,
+.Xr dir 5
 .Sh HISTORY
 The
 .Fn getdirentries