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