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 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)directory.3 8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libc/gen/directory.3,v 1.7.2.5 2003/03/15 15:11:05 trhodes Exp $
  34 .\" $DragonFly: src/lib/libc/gen/directory.3,v 1.2 2003/06/17 04:26:42 dillon Exp $
  35 .\"
  36 .Dd August 2, 2009
  37 .Dt DIRECTORY 3
  38 .Os
  39 .Sh NAME
  40 .Nm fdopendir ,
  41 .Nm opendir ,
  42 .Nm readdir ,
  43 .Nm readdir_r ,
  44 .Nm telldir ,
  45 .Nm seekdir ,
  46 .Nm rewinddir ,
  47 .Nm closedir ,
  48 .Nm dirfd
  49 .Nd directory operations
  50 .Sh LIBRARY
  51 .Lb libc
  52 .Sh SYNOPSIS
  53 .In sys/types.h
  54 .In dirent.h
  55 .Ft DIR *
  56 .Fn fdopendir "int fd"
  57 .Ft DIR *
  58 .Fn opendir "const char *filename"
  59 .Ft struct dirent *
  60 .Fn readdir "DIR *dirp"
  61 .Ft int
  62 .Fn readdir_r "DIR *dirp" "struct dirent *entry" "struct dirent **result"
  63 .Ft long
  64 .Fn telldir "DIR *dirp"
  65 .Ft void
  66 .Fn seekdir "DIR *dirp" "long  loc"
  67 .Ft void
  68 .Fn rewinddir "DIR *dirp"
  69 .Ft int
  70 .Fn closedir "DIR *dirp"
  71 .Ft int
  72 .Fn dirfd "DIR *dirp"
  73 .Sh DESCRIPTION
  74 The
  75 .Fn opendir
  76 function
  77 opens the directory named by
  78 .Fa filename ,
  79 associates a
  80 .Em directory stream
  81 with it
  82 and
  83 returns a pointer to be used to identify the
  84 .Em directory stream
  85 in subsequent operations.  The pointer
  86 .Dv NULL
  87 is returned if
  88 .Fa filename
  89 cannot be accessed, or if it cannot
  90 .Xr malloc 3
  91 enough memory to hold the whole thing.
  92 .Pp
  93 The
  94 .Fn fdopendir
  95 function associates a
  96 .Em directory stream
  97 with the directory file descriptor
  98 .Fa fd .
  99 The file offset associated with
 100 .Fa fd
 101 at the time of the call determines which entries are returned.
 102 The file descriptor must not be used further by the caller in any way.
 103 .Pp
 104 The
 105 .Fn readdir
 106 function
 107 returns a pointer to the next directory entry.  It returns
 108 .Dv NULL
 109 upon reaching the end of the directory or detecting an invalid
 110 .Fn seekdir
 111 operation.
 112 .Pp
 113 The
 114 .Fn readdir_r
 115 function
 116 provides the same functionality as
 117 .Fn readdir ,
 118 but the caller must provide a directory
 119 .Fa entry
 120 buffer to store the results in.  If the read succeeds,
 121 .Fa result
 122 is pointed at the
 123 .Fa entry ;
 124 upon reaching the end of the directory
 125 .Fa result
 126 is set to
 127 .Dv NULL .
 128 The
 129 .Fn readdir_r
 130 function
 131 returns 0 on success or an error number to indicate failure.
 132 .Pp
 133 The
 134 .Fn telldir
 135 function
 136 returns the current location associated with the named
 137 .Em directory stream .
 138 Values returned by
 139 .Fn telldir
 140 are good only for the lifetime of the
 141 .Dv DIR
 142 pointer,
 143 .Fa dirp ,
 144 from which they are derived.  If the directory is closed and then
 145 reopened, prior values returned by
 146 .Fn telldir
 147 will no longer be valid.
 148 .Pp
 149 The
 150 .Fn seekdir
 151 function
 152 sets the position of the next
 153 .Fn readdir
 154 operation on the
 155 .Em directory stream .
 156 The new position reverts to the one associated with the
 157 .Em directory stream
 158 when the
 159 .Fn telldir
 160 operation was performed.
 161 .Pp
 162 The
 163 .Fn rewinddir
 164 function
 165 resets the position of the named
 166 .Em directory stream
 167 to the beginning of the directory.
 168 .Pp
 169 The
 170 .Fn closedir
 171 function
 172 closes the named
 173 .Em directory stream
 174 and frees the structure associated with the
 175 .Fa dirp
 176 pointer,
 177 returning 0 on success.
 178 On failure, \-1 is returned and the global variable
 179 .Va errno
 180 is set to indicate the error.
 181 .Pp
 182 The
 183 .Fn dirfd
 184 function
 185 returns the integer file descriptor associated with the named
 186 .Em directory stream ,
 187 see
 188 .Xr open 2 .
 189 .Pp
 190 Sample code which searches a directory for entry ``name'' is:
 191 .Bd -literal -offset indent
 192 len = strlen(name);
 193 dirp = opendir(".");
 194 while ((dp = readdir(dirp)) != NULL)
 195         if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
 196                 (void)closedir(dirp);
 197                 return FOUND;
 198         }
 199 (void)closedir(dirp);
 200 return NOT_FOUND;
 201 .Ed
 202 .Sh SEE ALSO
 203 .Xr close 2 ,
 204 .Xr lseek 2 ,
 205 .Xr open 2 ,
 206 .Xr read 2 ,
 207 .Xr dir 5
 208 .Sh HISTORY
 209 The
 210 .Fn opendir ,
 211 .Fn readdir ,
 212 .Fn telldir ,
 213 .Fn seekdir ,
 214 .Fn rewinddir ,
 215 .Fn closedir ,
 216 and
 217 .Fn dirfd
 218 functions appeared in
 219 .Bx 4.2 .