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 .\"
  30 .Dd August 1, 2020
  31 .Dt DIRECTORY 3
  32 .Os
  33 .Sh NAME
  34 .Nm opendir ,
  35 .Nm fdopendir ,
  36 .Nm readdir ,
  37 .Nm readdir_r ,
  38 .Nm telldir ,
  39 .Nm seekdir ,
  40 .Nm rewinddir ,
  41 .Nm closedir ,
  42 .Nm fdclosedir ,
  43 .Nm dirfd
  44 .Nd directory operations
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In dirent.h
  49 .Ft DIR *
  50 .Fn opendir "const char *filename"
  51 .Ft DIR *
  52 .Fn fdopendir "int fd"
  53 .Ft struct dirent *
  54 .Fn readdir "DIR *dirp"
  55 .Ft int
  56 .Fn readdir_r "DIR *dirp" "struct dirent *entry" "struct dirent **result"
  57 .Ft long
  58 .Fn telldir "DIR *dirp"
  59 .Ft void
  60 .Fn seekdir "DIR *dirp" "long loc"
  61 .Ft void
  62 .Fn rewinddir "DIR *dirp"
  63 .Ft int
  64 .Fn closedir "DIR *dirp"
  65 .Ft int
  66 .Fn fdclosedir "DIR *dirp"
  67 .Ft int
  68 .Fn dirfd "DIR *dirp"
  69 .Sh DESCRIPTION
  70 .Bf -symbolic
  71 The
  72 .Fn readdir_r
  73 interface is deprecated
  74 because it cannot be used correctly unless
  75 .Brq Va NAME_MAX
  76 is a fixed value.
  77 .Ef
  78 .Pp
  79 The
  80 .Fn opendir
  81 function
  82 opens the directory named by
  83 .Fa filename ,
  84 associates a
  85 .Em directory stream
  86 with it
  87 and
  88 returns a pointer to be used to identify the
  89 .Em directory stream
  90 in subsequent operations.
  91 The pointer
  92 .Dv NULL
  93 is returned if
  94 .Fa filename
  95 cannot be accessed, or if it cannot
  96 .Xr malloc 3
  97 enough memory to hold the whole thing.
  98 .Pp
  99 The
 100 .Fn fdopendir
 101 function is equivalent to the
 102 .Fn opendir
 103 function except that the directory is specified by a file descriptor
 104 .Fa fd
 105 rather than by a name.
 106 The file offset associated with the file descriptor at the time of the call
 107 determines which entries are returned.
 108 .Pp
 109 Upon successful return from
 110 .Fn fdopendir ,
 111 the file descriptor is under the control of the system,
 112 and if any attempt is made to close the file descriptor,
 113 or to modify the state of the associated description other than by means
 114 of
 115 .Fn closedir ,
 116 .Fn readdir ,
 117 .Fn readdir_r ,
 118 or
 119 .Fn rewinddir ,
 120 the behavior is undefined.
 121 Upon calling
 122 .Fn closedir
 123 the file descriptor is closed.
 124 The
 125 .Dv FD_CLOEXEC
 126 flag is set on the file descriptor by a successful call to
 127 .Fn fdopendir .
 128 .Pp
 129 The
 130 .Fn readdir
 131 function
 132 returns a pointer to the next directory entry.
 133 The directory entry remains valid until the next call to
 134 .Fn readdir
 135 or
 136 .Fn closedir
 137 on the same
 138 .Em directory stream .
 139 The function returns
 140 .Dv NULL
 141 upon reaching the end of the directory or on error.
 142 In the event of an error,
 143 .Va errno
 144 may be set to any of the values documented for the
 145 .Xr getdirentries 2
 146 system call.
 147 .Pp
 148 The
 149 .Fn readdir_r
 150 function
 151 provides the same functionality as
 152 .Fn readdir ,
 153 but the caller must provide a directory
 154 .Fa entry
 155 buffer to store the results in.
 156 The buffer must be large enough for a
 157 .Vt struct dirent
 158 with a
 159 .Va d_name
 160 array with
 161 .Brq Va NAME_MAX
 162 + 1 elements.
 163 If the read succeeds,
 164 .Fa result
 165 is pointed at the
 166 .Fa entry ;
 167 upon reaching the end of the directory
 168 .Fa result
 169 is set to
 170 .Dv NULL .
 171 The
 172 .Fn readdir_r
 173 function
 174 returns 0 on success or an error number to indicate failure.
 175 .Pp
 176 The
 177 .Fn telldir
 178 function
 179 returns a token representing the current location associated with the named
 180 .Em directory stream .
 181 Values returned by
 182 .Fn telldir
 183 are good only for the lifetime of the
 184 .Dv DIR
 185 pointer,
 186 .Fa dirp ,
 187 from which they are derived.
 188 If the directory is closed and then
 189 reopened, prior values returned by
 190 .Fn telldir
 191 will no longer be valid.
 192 Values returned by
 193 .Fn telldir
 194 are also invalidated by a call to
 195 .Fn rewinddir .
 196 .Pp
 197 The
 198 .Fn seekdir
 199 function
 200 sets the position of the next
 201 .Fn readdir
 202 operation on the
 203 .Em directory stream .
 204 The new position reverts to the one associated with the
 205 .Em directory stream
 206 when the
 207 .Fn telldir
 208 operation was performed.
 209 .Pp
 210 The
 211 .Fn rewinddir
 212 function
 213 resets the position of the named
 214 .Em directory stream
 215 to the beginning of the directory.
 216 .Pp
 217 The
 218 .Fn closedir
 219 function
 220 closes the named
 221 .Em directory stream
 222 and frees the structure associated with the
 223 .Fa dirp
 224 pointer,
 225 returning 0 on success.
 226 On failure, \-1 is returned and the global variable
 227 .Va errno
 228 is set to indicate the error.
 229 .Pp
 230 The
 231 .Fn fdclosedir
 232 function is equivalent to the
 233 .Fn closedir
 234 function except that this function returns directory file descriptor instead of
 235 closing it.
 236 .Pp
 237 The
 238 .Fn dirfd
 239 function
 240 returns the integer file descriptor associated with the named
 241 .Em directory stream ,
 242 see
 243 .Xr open 2 .
 244 .Sh EXAMPLES
 245 Sample code which searches a directory for entry ``name'' is:
 246 .Bd -literal -offset indent
 247 dirp = opendir(".");
 248 if (dirp == NULL)
 249         return (ERROR);
 250 len = strlen(name);
 251 while ((dp = readdir(dirp)) != NULL) {
 252         if (dp->d_namlen == len && strcmp(dp->d_name, name) == 0) {
 253                 (void)closedir(dirp);
 254                 return (FOUND);
 255         }
 256 }
 257 (void)closedir(dirp);
 258 return (NOT_FOUND);
 259 .Ed
 260 .Sh ERRORS
 261 The
 262 .Fn opendir
 263 function will fail if:
 264 .Bl -tag -width Er
 265 .It Bq Er EACCES
 266 Search permission is denied for the component of the path prefix of
 267 .Fa filename
 268 or read permission is denied for
 269 .Fa filename .
 270 .It Bq Er ELOOP
 271 A loop exists in symbolic links encountered during resolution of the
 272 .Fa filename
 273 argument.
 274 .It Bq Er ENAMETOOLONG
 275 The length of the
 276 .Fa filename
 277 argument exceeds
 278 .Brq Dv PATH_MAX
 279 or
 280 a pathname component is longer than
 281 .Brq Dv NAME_MAX .
 282 .It Bq Er ENOENT
 283 A component of
 284 .Fa filename
 285 does not name an existing directory or
 286 .Fa filename
 287 is an empty string.
 288 .It Bq Er ENOTDIR
 289 A component of
 290 .Fa filename
 291 is not a directory.
 292 .El
 293 .Pp
 294 The
 295 .Fn fdopendir
 296 function will fail if:
 297 .Bl -tag -width Er
 298 .It Bq Er EBADF
 299 The
 300 .Fa fd
 301 argument is not a valid file descriptor open for reading.
 302 .It Bq Er ENOTDIR
 303 The descriptor
 304 .Fa fd
 305 is not associated with a directory.
 306 .El
 307 .Pp
 308 The
 309 .Fn readdir
 310 and
 311 .Fn readdir_r
 312 functions may also fail and set
 313 .Va errno
 314 for any of the errors specified for the routine
 315 .Xr getdents 2 .
 316 .Pp
 317 The
 318 .Fn telldir
 319 function may also fail and set
 320 .Va errno
 321 for any of the errors specified for the routine
 322 .Xr realloc 3 .
 323 .Pp
 324 The
 325 .Fn closedir
 326 function may also fail and set
 327 .Va errno
 328 for any of the errors specified for the routine
 329 .Xr close 2 .
 330 .Sh SEE ALSO
 331 .Xr close 2 ,
 332 .Xr lseek 2 ,
 333 .Xr open 2 ,
 334 .Xr read 2 ,
 335 .Xr dir 5
 336 .Sh STANDARDS
 337 The
 338 .Fn closedir ,
 339 .Fn dirfd ,
 340 .Fn fdopendir ,
 341 .Fn opendir ,
 342 .Fn readdir ,
 343 .Fn readdir_r ,
 344 .Fn rewinddir ,
 345 .Fn seekdir
 346 and
 347 .Fn telldir
 348 functions are expected to conform to
 349 .St -p1003.1-2008 .
 350 The
 351 .Fn fdclosedir
 352 function and the
 353 .Fa d_off ,
 354 .Fa d_reclen
 355 and
 356 .Fa d_type
 357 fields of
 358 .Vt struct dirent
 359 are non-standard, and should not be used in portable programs.
 360 .Sh HISTORY
 361 The
 362 .Fn opendir ,
 363 .Fn readdir ,
 364 .Fn telldir ,
 365 .Fn seekdir ,
 366 .Fn rewinddir ,
 367 .Fn closedir ,
 368 and
 369 .Fn dirfd
 370 functions appeared in
 371 .Bx 4.2 .
 372 The
 373 .Fn fdopendir
 374 function appeared in
 375 .Fx 8.0 .
 376 .Fn fdclosedir
 377 function appeared in
 378 .Fx 10.0 .
 379 .Sh BUGS
 380 The behaviour of
 381 .Fn telldir
 382 and
 383 .Fn seekdir
 384 is likely to be wrong if there are parallel unlinks happening
 385 and the directory is larger than one page.
 386 There is code to ensure that a
 387 .Fn seekdir
 388 to the location given by a
 389 .Fn telldir
 390 immediately before the last
 391 .Fn readdir
 392 will always set the correct location to return the same value as that last
 393 .Fn readdir
 394 performed.
 395 This is enough for some applications which want to
 396 "push back the last entry read", e.g., Samba.
 397 Seeks back to any other location,
 398 other than the beginning of the directory,
 399 may result in unexpected behaviour if deletes are present.
 400 It is hoped that this situation will be resolved with changes to
 401 .Fn getdirentries
 402 and the VFS.