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