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.
 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 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 .Pp
 172 The
 173 .Fn seekdir
 174 function
 175 sets the position of the next
 176 .Fn readdir
 177 operation on the
 178 .Em directory stream .
 179 The new position reverts to the one associated with the
 180 .Em directory stream
 181 when the
 182 .Fn telldir
 183 operation was performed.
 184 .Pp
 185 The
 186 .Fn rewinddir
 187 function
 188 resets the position of the named
 189 .Em directory stream
 190 to the beginning of the directory.
 191 .Pp
 192 The
 193 .Fn closedir
 194 function
 195 closes the named
 196 .Em directory stream
 197 and frees the structure associated with the
 198 .Fa dirp
 199 pointer,
 200 returning 0 on success.
 201 On failure, \-1 is returned and the global variable
 202 .Va errno
 203 is set to indicate the error.
 204 .Pp
 205 The
 206 .Fn dirfd
 207 function
 208 returns the integer file descriptor associated with the named
 209 .Em directory stream ,
 210 see
 211 .Xr open 2 .
 212 On failure, \-1 is returned and the global variable
 213 .Va errno
 214 is set to indicate the error.
 215 .Pp
 216 Sample code which searches a directory for entry ``name'' is:
 217 .Bd -literal -offset indent
 218 dirp = opendir(".");
 219 if (dirp == NULL)
 220         return (ERROR);
 221 len = strlen(name);
 222 while ((dp = readdir(dirp)) != NULL) {
 223         if (dp->d_namlen == len && strcmp(dp->d_name, name) == 0) {
 224                 (void)closedir(dirp);
 225                 return (FOUND);
 226         }
 227 }
 228 (void)closedir(dirp);
 229 return (NOT_FOUND);
 230 .Ed
 231 .Sh SEE ALSO
 232 .Xr close 2 ,
 233 .Xr lseek 2 ,
 234 .Xr open 2 ,
 235 .Xr read 2 ,
 236 .Xr dir 5
 237 .Sh HISTORY
 238 The
 239 .Fn opendir ,
 240 .Fn readdir ,
 241 .Fn telldir ,
 242 .Fn seekdir ,
 243 .Fn rewinddir ,
 244 .Fn closedir ,
 245 and
 246 .Fn dirfd
 247 functions appeared in
 248 .Bx 4.2 .
 249 The
 250 .Fn fdopendir
 251 function appeared in
 252 .Fx 8.0 .