Return to directory.3 CVS log

Up to [cvs.NetBSD.org] / src / lib / libc / gen

Annotation of src/lib/libc/gen/directory.3, Revision 1.5

1.1       cgd         1: .\" Copyright (c) 1983, 1991 Regents of the University of California.
                      2: .\" All rights reserved.
                      3: .\"
                      4: .\" Redistribution and use in source and binary forms, with or without
                      5: .\" modification, are permitted provided that the following conditions
                      6: .\" are met:
                      7: .\" 1. Redistributions of source code must retain the above copyright
                      8: .\"    notice, this list of conditions and the following disclaimer.
                      9: .\" 2. Redistributions in binary form must reproduce the above copyright
                     10: .\"    notice, this list of conditions and the following disclaimer in the
                     11: .\"    documentation and/or other materials provided with the distribution.
                     12: .\" 3. All advertising materials mentioning features or use of this software
                     13: .\"    must display the following acknowledgement:
                     14: .\"    This product includes software developed by the University of
                     15: .\"    California, Berkeley and its contributors.
                     16: .\" 4. Neither the name of the University nor the names of its contributors
                     17: .\"    may be used to endorse or promote products derived from this software
                     18: .\"    without specific prior written permission.
                     19: .\"
                     20: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
                     21: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     22: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     23: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     24: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     25: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     26: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     27: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     28: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     29: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     30: .\" SUCH DAMAGE.
                     31: .\"
1.2       mycroft    32: .\"     from: @(#)directory.3  6.7 (Berkeley) 4/19/91
1.5     ! jtc        33: .\"    $Id: directory.3,v 1.4 1993/08/20 16:46:14 jtc Exp $
1.1       cgd        34: .\"
                     35: .Dd April 19, 1991
                     36: .Dt DIRECTORY 3
                     37: .Os BSD 4.2
                     38: .Sh NAME
                     39: .Nm opendir ,
                     40: .Nm readdir ,
                     41: .Nm telldir ,
                     42: .Nm seekdir ,
                     43: .Nm rewinddir ,
                     44: .Nm closedir ,
                     45: .Nm dirfd
                     46: .Nd directory operations
                     47: .Sh SYNOPSIS
                     48: .Fd #include <sys/types.h>
                     49: .Fd #include <dirent.h>
                     50: .Ft DIR *
                     51: .Fn opendir "const char *filename"
1.4       jtc        52: .Ft struct dirent *
1.1       cgd        53: .Fn readdir "DIR *dirp"
                     54: .Ft long
                     55: .Fn telldir "const DIR *dirp"
                     56: .Ft void
                     57: .Fn seekdir "DIR *dirp" "long  loc"
                     58: .Ft void
                     59: .Fn rewinddir "DIR *dirp"
                     60: .Ft int
                     61: .Fn closedir "DIR *dirp"
                     62: .Ft int
                     63: .Fn dirfd "DIR *dirp"
                     64: .Sh DESCRIPTION
                     65: The
                     66: .Fn opendir
                     67: function
                     68: opens the directory named by
                     69: .Fa filename ,
                     70: associates a
                     71: .Em directory stream
                     72: with it
                     73: and
                     74: returns a pointer to be used to identify the
                     75: .Em directory stream
                     76: in subsequent operations.  The pointer
                     77: .Dv NULL
                     78: is returned if
                     79: .Fa filename
                     80: cannot be accessed, or if it cannot
                     81: .Xr malloc 3
                     82: enough memory to hold the whole thing.
                     83: .Pp
                     84: The
                     85: .Fn readdir
                     86: function
                     87: returns a pointer to the next directory entry.  It returns
                     88: .Dv NULL
                     89: upon reaching the end of the directory or detecting an invalid
                     90: .Fn seekdir
                     91: operation.
                     92: .Pp
                     93: The
                     94: .Fn telldir
                     95: function
                     96: returns the current location associated with the named
                     97: .Em directory stream .
                     98: .Pp
                     99: The
                    100: .Fn seekdir
                    101: function
                    102: sets the position of the next
                    103: .Fn readdir
                    104: operation on the
                    105: .Em directory stream .
                    106: The new position reverts to the one associated with the
                    107: .Em directory stream
                    108: when the
                    109: .Fn telldir
                    110: operation was performed.  Values returned by
                    111: .Fn telldir
                    112: are good only for the lifetime of the
                    113: .Dv DIR
                    114: pointer,
                    115: .Fa dirp ,
                    116: from which they are derived.
                    117: If the directory is closed and then reopened, the
                    118: .Fn telldir
                    119: value may be invalidated due to undetected directory compaction.
                    120: It is safe to use a previous
                    121: .Fn telldir
                    122: value immediately after a call to
                    123: .Fn opendir
                    124: and before any calls to
                    125: .Fn readdir .
                    126: .Pp
                    127: The
                    128: .Fn rewinddir
                    129: function
                    130: resets the position of the named
                    131: .Em directory stream
                    132: to the beginning of the directory.
                    133: .Pp
                    134: The
                    135: .Fn closedir
                    136: function
                    137: closes the named
                    138: .Em directory stream
                    139: and frees the structure associated with the
                    140: .Fa dirp
                    141: pointer,
                    142: returning 0 on success.
                    143: On failure, \-1 is returned and the global variable
                    144: .Va errno
                    145: is set to indicate the error.
                    146: .Pp
                    147: The
                    148: .Fn dirfd
                    149: function
                    150: returns the integer file descriptor associated with the named
                    151: .Em directory stream ,
                    152: see
                    153: .Xr open 2 .
                    154: .Pp
1.5     ! jtc       155: Sample code which searches a directory for entry ``name'' is:
1.1       cgd       156: .Bd -literal -offset indent
                    157: len = strlen(name);
                    158: dirp = opendir(".");
                    159: for (dp = readdir(dirp); dp != NULL; dp = readdir(dirp))
                    160:        if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
                    161:                (void)closedir(dirp);
                    162:                return FOUND;
                    163:        }
                    164: (void)closedir(dirp);
                    165: return NOT_FOUND;
                    166: .Ed
                    167: .Sh SEE ALSO
                    168: .Xr open 2 ,
                    169: .Xr close 2 ,
                    170: .Xr read 2 ,
                    171: .Xr lseek 2 ,
                    172: .Xr dir 5
                    173: .Sh HISTORY
                    174: The
                    175: .Fn opendir ,
                    176: .Fn readdir ,
                    177: .Fn telldir ,
                    178: .Fn seekdir ,
                    179: .Fn rewinddir ,
                    180: .Fn closedir ,
                    181: and
                    182: .Fn dirfd
                    183: functions appeared in
                    184: .Bx 4.2 .