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 June 4, 1993
  37 .Dt DIRECTORY 3
  38 .Os
  39 .Sh NAME
  40 .Nm opendir ,
  41 .Nm readdir ,
  42 .Nm readdir_r ,
  43 .Nm telldir ,
  44 .Nm seekdir ,
  45 .Nm rewinddir ,
  46 .Nm closedir ,
  47 .Nm dirfd
  48 .Nd directory operations
  49 .Sh LIBRARY
  50 .Lb libc
  51 .Sh SYNOPSIS
  52 .In sys/types.h
  53 .In dirent.h
  54 .Ft DIR *
  55 .Fn opendir "const char *filename"
  56 .Ft struct dirent *
  57 .Fn readdir "DIR *dirp"
  58 .Ft int
  59 .Fn readdir_r "DIR *dirp" "struct dirent *entry" "struct dirent **result"
  60 .Ft long
  61 .Fn telldir "DIR *dirp"
  62 .Ft void
  63 .Fn seekdir "DIR *dirp" "long  loc"
  64 .Ft void
  65 .Fn rewinddir "DIR *dirp"
  66 .Ft int
  67 .Fn closedir "DIR *dirp"
  68 .Ft int
  69 .Fn dirfd "DIR *dirp"
  70 .Sh DESCRIPTION
  71 The
  72 .Fn opendir
  73 function
  74 opens the directory named by
  75 .Fa filename ,
  76 associates a
  77 .Em directory stream
  78 with it
  79 and
  80 returns a pointer to be used to identify the
  81 .Em directory stream
  82 in subsequent operations.  The pointer
  83 .Dv NULL
  84 is returned if
  85 .Fa filename
  86 cannot be accessed, or if it cannot
  87 .Xr malloc 3
  88 enough memory to hold the whole thing.
  89 .Pp
  90 The
  91 .Fn readdir
  92 function
  93 returns a pointer to the next directory entry.  It returns
  94 .Dv NULL
  95 upon reaching the end of the directory or detecting an invalid
  96 .Fn seekdir
  97 operation.
  98 .Pp
  99 The
 100 .Fn readdir_r
 101 function
 102 provides the same functionality as
 103 .Fn readdir ,
 104 but the caller must provide a directory
 105 .Fa entry
 106 buffer to store the results in.  If the read succeeds,
 107 .Fa result
 108 is pointed at the
 109 .Fa entry ;
 110 upon reaching the end of the directory
 111 .Fa result
 112 is set to
 113 .Dv NULL .
 114 The
 115 .Fn readdir_r
 116 function
 117 returns 0 on success or an error number to indicate failure.
 118 .Pp
 119 The
 120 .Fn telldir
 121 function
 122 returns the current location associated with the named
 123 .Em directory stream .
 124 Values returned by
 125 .Fn telldir
 126 are good only for the lifetime of the
 127 .Dv DIR
 128 pointer,
 129 .Fa dirp ,
 130 from which they are derived.  If the directory is closed and then
 131 reopened, prior values returned by
 132 .Fn telldir
 133 will no longer be valid.
 134 .Pp
 135 The
 136 .Fn seekdir
 137 function
 138 sets the position of the next
 139 .Fn readdir
 140 operation on the
 141 .Em directory stream .
 142 The new position reverts to the one associated with the
 143 .Em directory stream
 144 when the
 145 .Fn telldir
 146 operation was performed.
 147 .Pp
 148 The
 149 .Fn rewinddir
 150 function
 151 resets the position of the named
 152 .Em directory stream
 153 to the beginning of the directory.
 154 .Pp
 155 The
 156 .Fn closedir
 157 function
 158 closes the named
 159 .Em directory stream
 160 and frees the structure associated with the
 161 .Fa dirp
 162 pointer,
 163 returning 0 on success.
 164 On failure, \-1 is returned and the global variable
 165 .Va errno
 166 is set to indicate the error.
 167 .Pp
 168 The
 169 .Fn dirfd
 170 function
 171 returns the integer file descriptor associated with the named
 172 .Em directory stream ,
 173 see
 174 .Xr open 2 .
 175 .Pp
 176 Sample code which searches a directory for entry ``name'' is:
 177 .Bd -literal -offset indent
 178 len = strlen(name);
 179 dirp = opendir(".");
 180 while ((dp = readdir(dirp)) != NULL)
 181         if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
 182                 (void)closedir(dirp);
 183                 return FOUND;
 184         }
 185 (void)closedir(dirp);
 186 return NOT_FOUND;
 187 .Ed
 188 .Sh SEE ALSO
 189 .Xr close 2 ,
 190 .Xr lseek 2 ,
 191 .Xr open 2 ,
 192 .Xr read 2 ,
 193 .Xr dir 5
 194 .Sh HISTORY
 195 The
 196 .Fn opendir ,
 197 .Fn readdir ,
 198 .Fn telldir ,
 199 .Fn seekdir ,
 200 .Fn rewinddir ,
 201 .Fn closedir ,
 202 and
 203 .Fn dirfd
 204 functions appeared in
 205 .Bx 4.2 .