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 .\" 3. 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 30, 2019
  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 fdclosedir ,
  44 .Nm dirfd
  45 .Nd directory operations
  46 .Sh LIBRARY
  47 .Lb libc
  48 .Sh SYNOPSIS
  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 fdclosedir "DIR *dirp"
  68 .Ft int
  69 .Fn dirfd "DIR *dirp"
  70 .Sh DESCRIPTION
  71 .Bf -symbolic
  72 The
  73 .Fn readdir_r
  74 interface is deprecated
  75 because it cannot be used correctly unless
  76 .Brq Va NAME_MAX
  77 is a fixed value.
  78 .Ef
  79 .Pp
  80 The
  81 .Fn opendir
  82 function
  83 opens the directory named by
  84 .Fa filename ,
  85 associates a
  86 .Em directory stream
  87 with it
  88 and
  89 returns a pointer to be used to identify the
  90 .Em directory stream
  91 in subsequent operations.
  92 The pointer
  93 .Dv NULL
  94 is returned if
  95 .Fa filename
  96 cannot be accessed, or if it cannot
  97 .Xr malloc 3
  98 enough memory to hold the whole thing.
  99 .Pp
 100 The
 101 .Fn fdopendir
 102 function is equivalent to the
 103 .Fn opendir
 104 function except that the directory is specified by a file descriptor
 105 .Fa fd
 106 rather than by a name.
 107 The file offset associated with the file descriptor at the time of the call
 108 determines which entries are returned.
 109 .Pp
 110 Upon successful return from
 111 .Fn fdopendir ,
 112 the file descriptor is under the control of the system,
 113 and if any attempt is made to close the file descriptor,
 114 or to modify the state of the associated description other than by means
 115 of
 116 .Fn closedir ,
 117 .Fn readdir ,
 118 .Fn readdir_r ,
 119 or
 120 .Fn rewinddir ,
 121 the behavior is undefined.
 122 Upon calling
 123 .Fn closedir
 124 the file descriptor is closed.
 125 The
 126 .Dv FD_CLOEXEC
 127 flag is set on the file descriptor by a successful call to
 128 .Fn fdopendir .
 129 .Pp
 130 The
 131 .Fn readdir
 132 function
 133 returns a pointer to the next directory entry.
 134 The directory entry remains valid until the next call to
 135 .Fn readdir
 136 or
 137 .Fn closedir
 138 on the same
 139 .Em directory stream .
 140 The function returns
 141 .Dv NULL
 142 upon reaching the end of the directory or on error.
 143 In the event of an error,
 144 .Va errno
 145 may be set to any of the values documented for the
 146 .Xr getdirentries 2
 147 system call.
 148 .Pp
 149 The
 150 .Fn readdir_r
 151 function
 152 provides the same functionality as
 153 .Fn readdir ,
 154 but the caller must provide a directory
 155 .Fa entry
 156 buffer to store the results in.
 157 The buffer must be large enough for a
 158 .Vt struct dirent
 159 with a
 160 .Va d_name
 161 array with
 162 .Brq Va NAME_MAX
 163 + 1 elements.
 164 If the read succeeds,
 165 .Fa result
 166 is pointed at the
 167 .Fa entry ;
 168 upon reaching the end of the directory
 169 .Fa result
 170 is set to
 171 .Dv NULL .
 172 The
 173 .Fn readdir_r
 174 function
 175 returns 0 on success or an error number to indicate failure.
 176 .Pp
 177 The
 178 .Fn telldir
 179 function
 180 returns a token representing the current location associated with the named
 181 .Em directory stream .
 182 Values returned by
 183 .Fn telldir
 184 are good only for the lifetime of the
 185 .Dv DIR
 186 pointer,
 187 .Fa dirp ,
 188 from which they are derived.
 189 If the directory is closed and then
 190 reopened, prior values returned by
 191 .Fn telldir
 192 will no longer be valid.
 193 Values returned by
 194 .Fn telldir
 195 are also invalidated by a call to
 196 .Fn rewinddir .
 197 .Pp
 198 The
 199 .Fn seekdir
 200 function
 201 sets the position of the next
 202 .Fn readdir
 203 operation on the
 204 .Em directory stream .
 205 The new position reverts to the one associated with the
 206 .Em directory stream
 207 when the
 208 .Fn telldir
 209 operation was performed.
 210 .Pp
 211 The
 212 .Fn rewinddir
 213 function
 214 resets the position of the named
 215 .Em directory stream
 216 to the beginning of the directory.
 217 .Pp
 218 The
 219 .Fn closedir
 220 function
 221 closes the named
 222 .Em directory stream
 223 and frees the structure associated with the
 224 .Fa dirp
 225 pointer,
 226 returning 0 on success.
 227 On failure, \-1 is returned and the global variable
 228 .Va errno
 229 is set to indicate the error.
 230 .Pp
 231 The
 232 .Fn fdclosedir
 233 function is equivalent to the
 234 .Fn closedir
 235 function except that this function returns directory file descriptor instead of
 236 closing it.
 237 .Pp
 238 The
 239 .Fn dirfd
 240 function
 241 returns the integer file descriptor associated with the named
 242 .Em directory stream ,
 243 see
 244 .Xr open 2 .
 245 .Pp
 246 Sample code which searches a directory for entry ``name'' is:
 247 .Bd -literal -offset indent
 248 dirp = opendir(".");
 249 if (dirp == NULL)
 250         return (ERROR);
 251 len = strlen(name);
 252 while ((dp = readdir(dirp)) != NULL) {
 253         if (dp->d_namlen == len && strcmp(dp->d_name, name) == 0) {
 254                 (void)closedir(dirp);
 255                 return (FOUND);
 256         }
 257 }
 258 (void)closedir(dirp);
 259 return (NOT_FOUND);
 260 .Ed
 261 .Sh SEE ALSO
 262 .Xr close 2 ,
 263 .Xr lseek 2 ,
 264 .Xr open 2 ,
 265 .Xr read 2 ,
 266 .Xr dir 5
 267 .Sh STANDARDS
 268 The
 269 .Fn closedir ,
 270 .Fn dirfd ,
 271 .Fn fdopendir ,
 272 .Fn opendir ,
 273 .Fn readdir ,
 274 .Fn readdir_r ,
 275 .Fn rewinddir ,
 276 .Fn seekdir
 277 and
 278 .Fn telldir
 279 functions are expected to conform to
 280 .St -p1003.1-2008 .
 281 The
 282 .Fn fdclosedir
 283 function and the
 284 .Fa d_off ,
 285 .Fa d_reclen
 286 and
 287 .Fa d_type
 288 fields of
 289 .Vt struct dirent
 290 are non-standard, and should not be used in portable programs.
 291 .Sh HISTORY
 292 The
 293 .Fn opendir ,
 294 .Fn readdir ,
 295 .Fn telldir ,
 296 .Fn seekdir ,
 297 .Fn rewinddir ,
 298 .Fn closedir ,
 299 and
 300 .Fn dirfd
 301 functions appeared in
 302 .Bx 4.2 .
 303 The
 304 .Fn fdopendir
 305 function appeared in
 306 .Fx 8.0 .
 307 .Fn fdclosedir
 308 function appeared in
 309 .Fx 10.0 .
 310 .Sh BUGS
 311 The behaviour of
 312 .Fn telldir
 313 and
 314 .Fn seekdir
 315 is likely to be wrong if there are parallel unlinks happening
 316 and the directory is larger than one page.
 317 There is code to ensure that a
 318 .Fn seekdir
 319 to the location given by a
 320 .Fn telldir
 321 immediately before the last
 322 .Fn readdir
 323 will always set the correct location to return the same value as that last
 324 .Fn readdir
 325 performed.
 326 This is enough for some applications which want to
 327 "push back the last entry read", e.g., Samba.
 328 Seeks back to any other location,
 329 other than the beginning of the directory,
 330 may result in unexpected behaviour if deletes are present.
 331 It is hoped that this situation will be resolved with changes to
 332 .Fn getdirentries
 333 and the VFS.