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