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. 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: src/lib/libc/gen/directory.3,v 1.7.2.5 2003/03/15 15:11:05 trhodes Exp $
  30 .\"
  31 .Dd February 22, 2018
  32 .Dt DIRECTORY 3
  33 .Os
  34 .Sh NAME
  35 .Nm fdopendir ,
  36 .Nm opendir ,
  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 fdopendir "int fd"
  52 .Ft DIR *
  53 .Fn opendir "const char *filename"
  54 .Ft struct dirent *
  55 .Fn readdir "DIR *dirp"
  56 .Ft int
  57 .Fn readdir_r "DIR * restrict dirp" "struct dirent * restrict entry" "struct dirent ** restrict 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.  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 .Pp
  88 The
  89 .Fn fdopendir
  90 function associates a
  91 .Em directory stream
  92 with the directory file descriptor
  93 .Fa fd .
  94 The file offset associated with
  95 .Fa fd
  96 at the time of the call determines which entries are returned.
  97 The file descriptor must not be used further by the caller in any way.
  98 .Pp
  99 The
 100 .Fn readdir
 101 function
 102 returns a pointer to the next directory entry.  It returns
 103 .Dv NULL
 104 upon reaching the end of the directory or detecting an invalid
 105 .Fn seekdir
 106 operation.
 107 .Pp
 108 The
 109 .Fn readdir_r
 110 function
 111 provides the same functionality as
 112 .Fn readdir ,
 113 but the caller must provide a directory
 114 .Fa entry
 115 buffer to store the results in.  If the read succeeds,
 116 .Fa result
 117 is pointed at the
 118 .Fa entry ;
 119 upon reaching the end of the directory
 120 .Fa result
 121 is set to
 122 .Dv NULL .
 123 The
 124 .Fn readdir_r
 125 function
 126 returns 0 on success or an error number to indicate failure.
 127 .Pp
 128 The
 129 .Fn telldir
 130 function
 131 returns the current location associated with the named
 132 .Em directory stream .
 133 Values returned by
 134 .Fn telldir
 135 are good only for the lifetime of the
 136 .Dv DIR
 137 pointer,
 138 .Fa dirp ,
 139 from which they are derived.  If the directory is closed and then
 140 reopened, prior values returned by
 141 .Fn telldir
 142 will no longer be valid.
 143 .Pp
 144 The
 145 .Fn seekdir
 146 function
 147 sets the position of the next
 148 .Fn readdir
 149 operation on the
 150 .Em directory stream .
 151 The new position reverts to the one associated with the
 152 .Em directory stream
 153 when the
 154 .Fn telldir
 155 operation was performed.
 156 .Pp
 157 The
 158 .Fn rewinddir
 159 function
 160 resets the position of the named
 161 .Em directory stream
 162 to the beginning of the directory.
 163 .Pp
 164 The
 165 .Fn closedir
 166 function
 167 closes the named
 168 .Em directory stream
 169 and frees the structure associated with the
 170 .Fa dirp
 171 pointer,
 172 returning 0 on success.
 173 On failure, \-1 is returned and the global variable
 174 .Va errno
 175 is set to indicate the error.
 176 .Pp
 177 The
 178 .Fn dirfd
 179 function
 180 returns the integer file descriptor associated with the named
 181 .Em directory stream ,
 182 see
 183 .Xr open 2 .
 184 .Pp
 185 Sample code which searches a directory for entry ``name'' is:
 186 .Bd -literal -offset indent
 187 len = strlen(name);
 188 dirp = opendir(".");
 189 while ((dp = readdir(dirp)) != NULL)
 190         if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
 191                 (void)closedir(dirp);
 192                 return FOUND;
 193         }
 194 (void)closedir(dirp);
 195 return NOT_FOUND;
 196 .Ed
 197 .Sh SEE ALSO
 198 .Xr close 2 ,
 199 .Xr lseek 2 ,
 200 .Xr open 2 ,
 201 .Xr read 2 ,
 202 .Xr dir 5
 203 .Sh HISTORY
 204 The
 205 .Fn opendir ,
 206 .Fn readdir ,
 207 .Fn telldir ,
 208 .Fn seekdir ,
 209 .Fn rewinddir ,
 210 .Fn closedir ,
 211 and
 212 .Fn dirfd
 213 functions appeared in
 214 .Bx 4.2 .