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 July 5, 2012
  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 sys/types.h
  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 dirfd "DIR *dirp"
  68 .Sh DESCRIPTION
  69 The
  70 .Fn opendir
  71 function
  72 opens the directory named by
  73 .Fa filename ,
  74 associates a
  75 .Em directory stream
  76 with it
  77 and
  78 returns a pointer to be used to identify the
  79 .Em directory stream
  80 in subsequent operations.
  81 The pointer
  82 .Dv NULL
  83 is returned if
  84 .Fa filename
  85 cannot be accessed, or if it cannot
  86 .Xr malloc 3
  87 enough memory to hold the whole thing.
  88 .Pp
  89 The
  90 .Fn fdopendir
  91 function is equivalent to the
  92 .Fn opendir
  93 function except that the directory is specified by a file descriptor
  94 .Fa fd
  95 rather than by a name.
  96 The file offset associated with the file descriptor at the time of the call
  97 determines which entries are returned.
  98 .Pp
  99 Upon successful return from
 100 .Fn fdopendir ,
 101 the file descriptor is under the control of the system,
 102 and if any attempt is made to close the file descriptor,
 103 or to modify the state of the associated description other than by means
 104 of
 105 .Fn closedir ,
 106 .Fn readdir ,
 107 .Fn readdir_r ,
 108 or
 109 .Fn rewinddir ,
 110 the behavior is undefined.
 111 Upon calling
 112 .Fn closedir
 113 the file descriptor is closed.
 114 The
 115 .Dv FD_CLOEXEC
 116 flag is set on the file descriptor by a successful call to
 117 .Fn fdopendir .
 118 .Pp
 119 The
 120 .Fn readdir
 121 function
 122 returns a pointer to the next directory entry.
 123 It returns
 124 .Dv NULL
 125 upon reaching the end of the directory or on error.
 126 In the event of an error,
 127 .Va errno
 128 may be set to any of the values documented for the
 129 .Xr getdirentries 2
 130 system call.
 131 .Pp
 132 The
 133 .Fn readdir_r
 134 function
 135 provides the same functionality as
 136 .Fn readdir ,
 137 but the caller must provide a directory
 138 .Fa entry
 139 buffer to store the results in.
 140 If the read succeeds,
 141 .Fa result
 142 is pointed at the
 143 .Fa entry ;
 144 upon reaching the end of the directory
 145 .Fa result
 146 is set to
 147 .Dv NULL .
 148 The
 149 .Fn readdir_r
 150 function
 151 returns 0 on success or an error number to indicate failure.
 152 .Pp
 153 The
 154 .Fn telldir
 155 function
 156 returns a token representing the current location associated with the named
 157 .Em directory stream .
 158 Values returned by
 159 .Fn telldir
 160 are good only for the lifetime of the
 161 .Dv DIR
 162 pointer,
 163 .Fa dirp ,
 164 from which they are derived.
 165 If the directory is closed and then
 166 reopened, prior values returned by
 167 .Fn telldir
 168 will no longer be valid.
 169 .Pp
 170 The
 171 .Fn seekdir
 172 function
 173 sets the position of the next
 174 .Fn readdir
 175 operation on the
 176 .Em directory stream .
 177 The new position reverts to the one associated with the
 178 .Em directory stream
 179 when the
 180 .Fn telldir
 181 operation was performed.
 182 State associated with the token returned by
 183 .Fn telldir is freed when it is passed to
 184 .Fn seekdir .
 185 If you wish return to the same location again,
 186 then you must create a new token with another
 187 .Fn telldir
 188 call.
 189 .Pp
 190 The
 191 .Fn rewinddir
 192 function
 193 resets the position of the named
 194 .Em directory stream
 195 to the beginning of the directory.
 196 .Pp
 197 The
 198 .Fn closedir
 199 function
 200 closes the named
 201 .Em directory stream
 202 and frees the structure associated with the
 203 .Fa dirp
 204 pointer,
 205 returning 0 on success.
 206 On failure, \-1 is returned and the global variable
 207 .Va errno
 208 is set to indicate the error.
 209 .Pp
 210 The
 211 .Fn dirfd
 212 function
 213 returns the integer file descriptor associated with the named
 214 .Em directory stream ,
 215 see
 216 .Xr open 2 .
 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 .
 255 .Sh BUGS
 256 The invalidation of
 257 .Fn telldir
 258 tokens when calling
 259 .Fn seekdir
 260 is non-standard.