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 April 16, 2008
  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 The
  69 .Fn opendir
  70 function
  71 opens the directory named by
  72 .Fa filename ,
  73 associates a
  74 .Em directory stream
  75 with it
  76 and
  77 returns a pointer to be used to identify the
  78 .Em directory stream
  79 in subsequent operations.
  80 The pointer
  81 .Dv NULL
  82 is returned if
  83 .Fa filename
  84 cannot be accessed, or if it cannot
  85 .Xr malloc 3
  86 enough memory to hold the whole thing,
  87 and sets the global variable
  88 .Va errno
  89 to indicate the error.
  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.  Note that the order of the directory entries vended by
 133 .Fn readdir
 134 is not specified. Some filesystems may return entries in lexicographic sort order and others may not.
 135 .Pp
 136 The
 137 .Fn readdir_r
 138 function
 139 provides the same functionality as
 140 .Fn readdir ,
 141 but the caller must provide a directory
 142 .Fa entry
 143 buffer to store the results in.
 144 If the read succeeds,
 145 .Fa result
 146 is pointed at the
 147 .Fa entry ;
 148 upon reaching the end of the directory
 149 .Fa result
 150 is set to
 151 .Dv NULL .
 152 The
 153 .Fn readdir_r
 154 function
 155 returns 0 on success or an error number to indicate failure.
 156 .Pp
 157 The
 158 .Fn telldir
 159 function
 160 returns the current location associated with the named
 161 .Em directory stream .
 162 Values returned by
 163 .Fn telldir
 164 are good only for the lifetime of the
 165 .Dv DIR
 166 pointer,
 167 .Fa dirp ,
 168 from which they are derived.
 169 If the directory is closed and then
 170 reopened, prior values returned by
 171 .Fn telldir
 172 will no longer be valid.
 173 .Pp
 174 The
 175 .Fn seekdir
 176 function
 177 sets the position of the next
 178 .Fn readdir
 179 operation on the
 180 .Em directory stream .
 181 The new position reverts to the one associated with the
 182 .Em directory stream
 183 when the
 184 .Fn telldir
 185 operation was performed.
 186 .Pp
 187 The
 188 .Fn rewinddir
 189 function
 190 resets the position of the named
 191 .Em directory stream
 192 to the beginning of the directory.
 193 .Pp
 194 The
 195 .Fn closedir
 196 function
 197 closes the named
 198 .Em directory stream
 199 and frees the structure associated with the
 200 .Fa dirp
 201 pointer,
 202 returning 0 on success.
 203 On failure, \-1 is returned and the global variable
 204 .Va errno
 205 is set to indicate the error.
 206 .Pp
 207 The
 208 .Fn dirfd
 209 function
 210 returns the integer file descriptor associated with the named
 211 .Em directory stream ,
 212 see
 213 .Xr open 2 .
 214 On failure, \-1 is returned and the global variable
 215 .Va errno
 216 is set to indicate the error.
 217 .Pp
 218 Sample code which searches a directory for entry ``name'' is:
 219 .Bd -literal -offset indent
 220 dirp = opendir(".");
 221 if (dirp == NULL)
 222         return (ERROR);
 223 len = strlen(name);
 224 while ((dp = readdir(dirp)) != NULL) {
 225         if (dp->d_namlen == len && strcmp(dp->d_name, name) == 0) {
 226                 (void)closedir(dirp);
 227                 return (FOUND);
 228         }
 229 }
 230 (void)closedir(dirp);
 231 return (NOT_FOUND);
 232 .Ed
 233 .Sh SEE ALSO
 234 .Xr close 2 ,
 235 .Xr lseek 2 ,
 236 .Xr open 2 ,
 237 .Xr read 2 ,
 238 .Xr dir 5
 239 .Sh HISTORY
 240 The
 241 .Fn opendir ,
 242 .Fn readdir ,
 243 .Fn telldir ,
 244 .Fn seekdir ,
 245 .Fn rewinddir ,
 246 .Fn closedir ,
 247 and
 248 .Fn dirfd
 249 functions appeared in
 250 .Bx 4.2 .
 251 The
 252 .Fn fdopendir
 253 function appeared in
 254 .Fx 8.0 .