Libc-1044.1.2.tar.gz

[apple/libc.git] / gen / directory.3

diff --git a/gen/directory.3 b/gen/directory.3
index 3b21d9a756d389daaf5577061a7ec1ea8c98edff..b94998bea5b19ef310371dee2d3f43e3b5a183b7 100644 (file)
--- a/gen/directory.3
+++ b/gen/directory.3
@@ -26,62 +26,97 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)directory.3        8.1 (Berkeley) 6/4/93
-.\" $FreeBSD: src/lib/libc/gen/directory.3,v 1.12 2001/10/01 16:08:50 ru Exp $
+.\" $FreeBSD$
 .\"
-.Dd June 4, 1993
+.Dd April 16, 2008
 .Dt DIRECTORY 3
 .Os
 .Sh NAME
-.Nm closedir ,
-.Nm dirfd ,
 .Nm opendir ,
+.Nm fdopendir ,
 .Nm readdir ,
 .Nm readdir_r ,
-.Nm rewinddir ,
+.Nm telldir ,
 .Nm seekdir ,
-.Nm telldir
+.Nm rewinddir ,
+.Nm closedir ,
+.Nm dirfd
 .Nd directory operations
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In dirent.h
-.Ft int
-.Fn closedir "DIR *dirp"
-.Ft int
-.Fn dirfd "DIR *dirp"
 .Ft DIR *
-.Fn opendir "const char *dirname"
+.Fn opendir "const char *filename"
+.Ft DIR *
+.Fn fdopendir "int fd"
 .Ft struct dirent *
 .Fn readdir "DIR *dirp"
 .Ft int
-.Fn readdir_r "DIR *restrict dirp" "struct dirent *restrict entry" \
-    "struct dirent **restrict result"
-.Ft void
-.Fn rewinddir "DIR *dirp"
-.Ft void
-.Fn seekdir "DIR *dirp" "long loc"
+.Fn readdir_r "DIR *dirp" "struct dirent *entry" "struct dirent **result"
 .Ft long
 .Fn telldir "DIR *dirp"
+.Ft void
+.Fn seekdir "DIR *dirp" "long loc"
+.Ft void
+.Fn rewinddir "DIR *dirp"
+.Ft int
+.Fn closedir "DIR *dirp"
+.Ft int
+.Fn dirfd "DIR *dirp"
 .Sh DESCRIPTION
 The
 .Fn opendir
 function
 opens the directory named by
-.Fa dirname ,
+.Fa filename ,
 associates a
 .Em directory stream
-with it,
-and returns a pointer to be used to identify the
+with it
+and
+returns a pointer to be used to identify the
 .Em directory stream
 in subsequent operations.
-In the event of an error, NULL
-is returned and
-.Va errno
-will be set to reflect if
-.Fa dirname
-cannot be accessed or if it cannot
+The pointer
+.Dv NULL
+is returned if
+.Fa filename
+cannot be accessed, or if it cannot
 .Xr malloc 3
-enough memory to hold the whole thing.
+enough memory to hold the whole thing,
+and sets the global variable
+.Va errno
+to indicate the error.
+.Pp
+The
+.Fn fdopendir
+function is equivalent to the
+.Fn opendir
+function except that the directory is specified by a file descriptor
+.Fa fd
+rather than by a name.
+./"The file offset associated with the file descriptor at the time of the call
+./"determines which entries are returned.
+.Pp
+Upon successful return from
+.Fn fdopendir ,
+the file descriptor is under the control of the system,
+and if any attempt is made to close the file descriptor,
+or to modify the state of the associated description other than by means
+of
+.Fn closedir ,
+.Fn readdir ,
+.Fn readdir_r ,
+or
+.Fn rewinddir ,
+the behavior is undefined.
+Upon calling
+.Fn closedir
+the file descriptor is closed.
+The
+.Dv FD_CLOEXEC
+flag is set on the file descriptor by a successful call to
+.Fn fdopendir .
 .Pp
 The
 .Fn readdir
@@ -92,7 +127,7 @@ It returns
 upon reaching the end of the directory or on error.
 In the event of an error,
 .Va errno
-will be set to any of the values documented for the
+may be set to any of the values documented for the
 .Xr getdirentries 2
 system call.
 .Pp
@@ -108,7 +143,7 @@ If the read succeeds,
 .Fa result
 is pointed at the
 .Fa entry ;
-upon reaching the end of the directory,
+upon reaching the end of the directory
 .Fa result
 is set to
 .Dv NULL .
@@ -126,8 +161,8 @@ Values returned by
 .Fn telldir
 are good only for the lifetime of the
 .Dv DIR
-pointer (e.g.,
-.Fa dirp )
+pointer,
+.Fa dirp ,
 from which they are derived.
 If the directory is closed and then
 reopened, prior values returned by
@@ -171,8 +206,8 @@ The
 .Fn dirfd
 function
 returns the integer file descriptor associated with the named
-.Em directory stream 
-on success, see
+.Em directory stream ,
+see
 .Xr open 2 .
 On failure, \-1 is returned and the global variable
 .Va errno
@@ -193,28 +228,25 @@ while ((dp = readdir(dirp)) != NULL) {
 (void)closedir(dirp);
 return (NOT_FOUND);
 .Ed
-.Sh LEGACY SYNOPSIS
-.Fd #include <sys/types.h>
-.Fd #include <dirent.h>
-.Pp
-.In sys/types.h
-is necessary for these functions.
 .Sh SEE ALSO
 .Xr close 2 ,
 .Xr lseek 2 ,
 .Xr open 2 ,
 .Xr read 2 ,
-.Xr compat 5 ,
 .Xr dir 5
 .Sh HISTORY
 The
-.Fn closedir ,
-.Fn dirfd ,
 .Fn opendir ,
 .Fn readdir ,
-.Fn rewinddir ,
+.Fn telldir ,
 .Fn seekdir ,
+.Fn rewinddir ,
+.Fn closedir ,
 and
-.Fn telldir
+.Fn dirfd
 functions appeared in
 .Bx 4.2 .
+The
+.Fn fdopendir
+function appeared in
+.Fx 8.0 .