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 August 1, 2020
  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 .Sh EXAMPLES
 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 ERRORS
 262 The
 263 .Fn opendir
 264 function will fail if:
 265 .Bl -tag -width Er
 266 .It Bq Er EACCES
 267 Search permission is denied for the component of the path prefix of
 268 .Fa filename
 269 or read permission is denied for
 270 .Fa filename .
 271 .It Bq Er ELOOP
 272 A loop exists in symbolic links encountered during resolution of the
 273 .Fa filename
 274 argument.
 275 .It Bq Er ENAMETOOLONG
 276 The length of the
 277 .Fa filename
 278 argument exceeds
 279 .Brq Dv PATH_MAX
 280 or
 281 a pathname component is longer than
 282 .Brq Dv NAME_MAX .
 283 .It Bq Er ENOENT
 284 A component of
 285 .Fa filename
 286 does not name an existing directory or
 287 .Fa filename
 288 is an empty string.
 289 .It Bq Er ENOTDIR
 290 A component of
 291 .Fa filename
 292 is not a directory.
 293 .El
 294 .Pp
 295 The
 296 .Fn fdopendir
 297 function will fail if:
 298 .Bl -tag -width Er
 299 .It Bq Er EBADF
 300 The
 301 .Fa fd
 302 argument is not a valid file descriptor open for reading.
 303 .It Bq Er ENOTDIR
 304 The descriptor
 305 .Fa fd
 306 is not associated with a directory.
 307 .El
 308 .Pp
 309 The
 310 .Fn readdir
 311 and
 312 .Fn readdir_r
 313 functions may also fail and set
 314 .Va errno
 315 for any of the errors specified for the routine
 316 .Xr getdents 2 .
 317 .Pp
 318 The
 319 .Fn telldir
 320 function may also fail and set
 321 .Va errno
 322 for any of the errors specified for the routine
 323 .Xr realloc 3 .
 324 .Pp
 325 The
 326 .Fn closedir
 327 function may also fail and set
 328 .Va errno
 329 for any of the errors specified for the routine
 330 .Xr close 2 .
 331 .Sh SEE ALSO
 332 .Xr close 2 ,
 333 .Xr lseek 2 ,
 334 .Xr open 2 ,
 335 .Xr read 2 ,
 336 .Xr dir 5
 337 .Sh STANDARDS
 338 The
 339 .Fn closedir ,
 340 .Fn dirfd ,
 341 .Fn fdopendir ,
 342 .Fn opendir ,
 343 .Fn readdir ,
 344 .Fn readdir_r ,
 345 .Fn rewinddir ,
 346 .Fn seekdir
 347 and
 348 .Fn telldir
 349 functions are expected to conform to
 350 .St -p1003.1-2008 .
 351 The
 352 .Fn fdclosedir
 353 function and the
 354 .Fa d_off ,
 355 .Fa d_reclen
 356 and
 357 .Fa d_type
 358 fields of
 359 .Vt struct dirent
 360 are non-standard, and should not be used in portable programs.
 361 .Sh HISTORY
 362 The
 363 .Fn opendir ,
 364 .Fn readdir ,
 365 .Fn telldir ,
 366 .Fn seekdir ,
 367 .Fn rewinddir ,
 368 .Fn closedir ,
 369 and
 370 .Fn dirfd
 371 functions appeared in
 372 .Bx 4.2 .
 373 The
 374 .Fn fdopendir
 375 function appeared in
 376 .Fx 8.0 .
 377 .Fn fdclosedir
 378 function appeared in
 379 .Fx 10.0 .
 380 .Sh BUGS
 381 The behaviour of
 382 .Fn telldir
 383 and
 384 .Fn seekdir
 385 is likely to be wrong if there are parallel unlinks happening
 386 and the directory is larger than one page.
 387 There is code to ensure that a
 388 .Fn seekdir
 389 to the location given by a
 390 .Fn telldir
 391 immediately before the last
 392 .Fn readdir
 393 will always set the correct location to return the same value as that last
 394 .Fn readdir
 395 performed.
 396 This is enough for some applications which want to
 397 "push back the last entry read", e.g., Samba.
 398 Seeks back to any other location,
 399 other than the beginning of the directory,
 400 may result in unexpected behaviour if deletes are present.
 401 It is hoped that this situation will be resolved with changes to
 402 .Fn getdirentries
 403 and the VFS.