lib/libc/gen/directory.3

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  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 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)directory.3 8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd April 16, 2008
  32 .Dt DIRECTORY 3
  33 .Os
  34 .Sh NAME
  35 .Nm opendir ,
  36 .Nm fdopendir ,
  37 .Nm readdir ,
  38 .Nm readdir_r ,
  39 .Nm telldir ,
  40 .Nm seekdir ,
  41 .Nm rewinddir ,
  42 .Nm closedir ,
  43 .Nm dirfd
  44 .Nd directory operations
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In sys/types.h
  49 .In dirent.h
  50 .Ft DIR *
  51 .Fn opendir "const char *filename"
  52 .Ft DIR *
  53 .Fn fdopendir "int fd"
  54 .Ft struct dirent *
  55 .Fn readdir "DIR *dirp"
  56 .Ft int
  57 .Fn readdir_r "DIR *dirp" "struct dirent *entry" "struct dirent **result"
  58 .Ft long
  59 .Fn telldir "DIR *dirp"
  60 .Ft void
  61 .Fn seekdir "DIR *dirp" "long loc"
  62 .Ft void
  63 .Fn rewinddir "DIR *dirp"
  64 .Ft int
  65 .Fn closedir "DIR *dirp"
  66 .Ft int
  67 .Fn dirfd "DIR *dirp"
  68 .Sh DESCRIPTION
  69 The
  70 .Fn opendir
  71 function
  72 opens the directory named by
  73 .Fa filename ,
  74 associates a
  75 .Em directory stream
  76 with it
  77 and
  78 returns a pointer to be used to identify the
  79 .Em directory stream
  80 in subsequent operations.
  81 The pointer
  82 .Dv NULL
  83 is returned if
  84 .Fa filename
  85 cannot be accessed, or if it cannot
  86 .Xr malloc 3
  87 enough memory to hold the whole thing.
  88 .Pp
  89 The
  90 .Fn fdopendir
  91 function is equivalent to the
  92 .Fn opendir
  93 function except that the directory is specified by a file descriptor
  94 .Fa fd
  95 rather than by a name.
  96 The file offset associated with the file descriptor at the time of the call
  97 determines which entries are returned.
  98 .Pp
  99 Upon successful return from
 100 .Fn fdopendir ,
 101 the file descriptor is under the control of the system,
 102 and if any attempt is made to close the file descriptor,
 103 or to modify the state of the associated description other than by means
 104 of
 105 .Fn closedir ,
 106 .Fn readdir ,
 107 .Fn readdir_r ,
 108 or
 109 .Fn rewinddir ,
 110 the behavior is undefined.
 111 Upon calling
 112 .Fn closedir
 113 the file descriptor is closed.
 114 The
 115 .Dv FD_CLOEXEC
 116 flag is set on the file descriptor by a successful call to
 117 .Fn fdopendir .
 118 .Pp
 119 The
 120 .Fn readdir
 121 function
 122 returns a pointer to the next directory entry.
 123 It returns
 124 .Dv NULL
 125 upon reaching the end of the directory or detecting an invalid
 126 .Fn seekdir
 127 operation.
 128 .Pp
 129 The
 130 .Fn readdir_r
 131 function
 132 provides the same functionality as
 133 .Fn readdir ,
 134 but the caller must provide a directory
 135 .Fa entry
 136 buffer to store the results in.
 137 If the read succeeds,
 138 .Fa result
 139 is pointed at the
 140 .Fa entry ;
 141 upon reaching the end of the directory
 142 .Fa result
 143 is set to
 144 .Dv NULL .
 145 The
 146 .Fn readdir_r
 147 function
 148 returns 0 on success or an error number to indicate failure.
 149 .Pp
 150 The
 151 .Fn telldir
 152 function
 153 returns the current location associated with the named
 154 .Em directory stream .
 155 Values returned by
 156 .Fn telldir
 157 are good only for the lifetime of the
 158 .Dv DIR
 159 pointer,
 160 .Fa dirp ,
 161 from which they are derived.
 162 If the directory is closed and then
 163 reopened, prior values returned by
 164 .Fn telldir
 165 will no longer be valid.
 166 .Pp
 167 The
 168 .Fn seekdir
 169 function
 170 sets the position of the next
 171 .Fn readdir
 172 operation on the
 173 .Em directory stream .
 174 The new position reverts to the one associated with the
 175 .Em directory stream
 176 when the
 177 .Fn telldir
 178 operation was performed.
 179 .Pp
 180 The
 181 .Fn rewinddir
 182 function
 183 resets the position of the named
 184 .Em directory stream
 185 to the beginning of the directory.
 186 .Pp
 187 The
 188 .Fn closedir
 189 function
 190 closes the named
 191 .Em directory stream
 192 and frees the structure associated with the
 193 .Fa dirp
 194 pointer,
 195 returning 0 on success.
 196 On failure, \-1 is returned and the global variable
 197 .Va errno
 198 is set to indicate the error.
 199 .Pp
 200 The
 201 .Fn dirfd
 202 function
 203 returns the integer file descriptor associated with the named
 204 .Em directory stream ,
 205 see
 206 .Xr open 2 .
 207 .Pp
 208 Sample code which searches a directory for entry ``name'' is:
 209 .Bd -literal -offset indent
 210 len = strlen(name);
 211 dirp = opendir(".");
 212 while ((dp = readdir(dirp)) != NULL)
 213         if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
 214                 (void)closedir(dirp);
 215                 return FOUND;
 216         }
 217 (void)closedir(dirp);
 218 return NOT_FOUND;
 219 .Ed
 220 .Sh SEE ALSO
 221 .Xr close 2 ,
 222 .Xr lseek 2 ,
 223 .Xr open 2 ,
 224 .Xr read 2 ,
 225 .Xr dir 5
 226 .Sh HISTORY
 227 The
 228 .Fn opendir ,
 229 .Fn readdir ,
 230 .Fn telldir ,
 231 .Fn seekdir ,
 232 .Fn rewinddir ,
 233 .Fn closedir ,
 234 and
 235 .Fn dirfd
 236 functions appeared in
 237 .Bx 4.2 .
 238 The
 239 .Fn fdopendir
 240 function appeared in
 241 .Fx 8.0 .