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