BSD 4_3_Net_2 release

[unix-history] / usr / src / lib / libc / gen / directory.3

diff --git a/usr/src/lib/libc/gen/directory.3 b/usr/src/lib/libc/gen/directory.3
index c863ea8..cae5ea3 100644 (file)
--- a/usr/src/lib/libc/gen/directory.3
+++ b/usr/src/lib/libc/gen/directory.3
@@ -1,115 +1,158 @@
-.\" Copyright (c) 1983 Regents of the University of California.
+.\" Copyright (c) 1983, 1991 Regents of the University of California.

 .\" All rights reserved.
 .\"
 .\" All rights reserved.
 .\"

-.\" %sccs.include.redist.man%
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.

 .\"
 .\"

-.\"    @(#)directory.3 6.6 (Berkeley) %G%
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" 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
+.\" SUCH DAMAGE.

 .\"
 .\"

-.TH DIRECTORY 3 ""
-.UC 5
-.SH NAME
-opendir, readdir, telldir, seekdir, rewinddir, closedir, dirfd \- directory operations
-.SH SYNOPSIS
-.nf
-.ft B
-#include <sys/types.h>
-#include <dirent.h>
-
-DIR *
-opendir(const char *filename);
-
-struct direct
-*readdir(DIR * dirp);
-
-long
-telldir(const DIR *dirp);
-
-void
-seekdir(DIR *dirp, long loc);
-
-void
-rewinddir(DIR *dirp);
-
-int
-closedir(DIR *dirp);
-
-int
-dirfd(DIR *dirp)
-.ft R
-.fi
-.SH DESCRIPTION
-.I Opendir
+.\"     @(#)directory.3        6.7 (Berkeley) 4/19/91
+.\"
+.Dd April 19, 1991
+.Dt DIRECTORY 3
+.Os BSD 4.2
+.Sh NAME
+.Nm opendir ,
+.Nm readdir ,
+.Nm telldir ,
+.Nm seekdir ,
+.Nm rewinddir ,
+.Nm closedir ,
+.Nm dirfd
+.Nd directory operations
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <dirent.h>
+.Ft DIR *
+.Fn opendir "const char *filename"
+.Ft struct direct
+.Fn readdir "DIR *dirp"
+.Ft long
+.Fn telldir "const 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
 opens the directory named by

-.I filename
-and associates a
-.I directory stream
-with it.
-.I Opendir
+.Fa filename ,
+associates a
+.Em directory stream
+with it
+and

 returns a pointer to be used to identify the
 returns a pointer to be used to identify the

-.I directory stream
+.Em directory stream

 in subsequent operations.  The pointer
 in subsequent operations.  The pointer

-.SM
-.B NULL
+.Dv NULL

 is returned if
 is returned if

-.I filename
+.Fa filename

 cannot be accessed, or if it cannot
 cannot be accessed, or if it cannot

-.IR malloc (3)
+.Xr malloc 3

 enough memory to hold the whole thing.
 enough memory to hold the whole thing.

-.PP
-.I Readdir
+.Pp
+The
+.Fn readdir
+function

 returns a pointer to the next directory entry.  It returns
 returns a pointer to the next directory entry.  It returns

-.B NULL
+.Dv NULL

 upon reaching the end of the directory or detecting an invalid
 upon reaching the end of the directory or detecting an invalid

-.I seekdir
+.Fn seekdir

 operation.
 operation.

-.PP
-.I Telldir
+.Pp
+The
+.Fn telldir
+function

 returns the current location associated with the named
 returns the current location associated with the named

-.I directory stream.
-.PP
-.I Seekdir
+.Em directory stream .
+.Pp
+The
+.Fn seekdir
+function

 sets the position of the next
 sets the position of the next

-.I readdir
+.Fn readdir

 operation on the
 operation on the

-.I directory stream.
+.Em directory stream .

 The new position reverts to the one associated with the
 The new position reverts to the one associated with the

-.I directory stream
+.Em directory stream

 when the
 when the

-.I telldir
+.Fn telldir

 operation was performed.  Values returned by
 operation was performed.  Values returned by

-.I telldir
-are good only for the lifetime of the DIR pointer from which they are derived.
+.Fn telldir
+are good only for the lifetime of the
+.Dv DIR
+pointer,
+.Fa dirp ,
+from which they are derived.

 If the directory is closed and then reopened, the 
 If the directory is closed and then reopened, the 

-.I telldir
+.Fn telldir

 value may be invalidated due to undetected directory compaction.
 It is safe to use a previous
 value may be invalidated due to undetected directory compaction.
 It is safe to use a previous

-.I telldir
+.Fn telldir

 value immediately after a call to
 value immediately after a call to

-.I opendir
+.Fn opendir

 and before any calls to
 and before any calls to

-.I readdir.
-.PP
-.I Rewinddir
+.Fn readdir .
+.Pp
+The
+.Fn rewinddir
+function

 resets the position of the named
 resets the position of the named

-.I directory stream
+.Em directory stream

 to the beginning of the directory.
 to the beginning of the directory.

-.PP
-.I Closedir
+.Pp
+The
+.Fn closedir
+function

 closes the named
 closes the named

-.I directory stream
-and frees the structure associated with the DIR pointer,
+.Em directory stream
+and frees the structure associated with the
+.Fa dirp
+pointer,

 returning 0 on success.
 returning 0 on success.

-On failure, -1 is returned and errno is set to indicate the error.
-.PP
-.I Dirfd
+On failure, \-1 is returned and the global variable
+.Va errno
+is set to indicate the error.
+.Pp
+The
+.Fn dirfd
+function

 returns the integer file descriptor associated with the named
 returns the integer file descriptor associated with the named

-.I directory stream,
-see open(2).
-.PP
+.Em directory stream ,
+see
+.Xr open 2 .
+.Pp

 Sample code which searchs a directory for entry ``name'' is:
 Sample code which searchs a directory for entry ``name'' is:

-.PP
-.nf
-.RS
+.Bd -literal -offset indent

 len = strlen(name);
 dirp = opendir(".");
 for (dp = readdir(dirp); dp != NULL; dp = readdir(dirp))
 len = strlen(name);
 dirp = opendir(".");
 for (dp = readdir(dirp); dp != NULL; dp = readdir(dirp))


@@ -119,7 +162,22 @@ for (dp = readdir(dirp); dp != NULL; dp = readdir(dirp))
        }
 (void)closedir(dirp);
 return NOT_FOUND;
        }
 (void)closedir(dirp);
 return NOT_FOUND;

-.RE
-.fi
-.SH "SEE ALSO"
-open(2), close(2), read(2), lseek(2), dir(5)
+.Ed
+.Sh SEE ALSO
+.Xr open 2 ,
+.Xr close 2 ,
+.Xr read 2 ,
+.Xr lseek 2 ,
+.Xr dir 5
+.Sh HISTORY
+The
+.Fn opendir ,
+.Fn readdir ,
+.Fn telldir ,
+.Fn seekdir ,
+.Fn rewinddir ,
+.Fn closedir ,
+and
+.Fn dirfd
+functions appeared in
+.Bx 4.2 .