lib/libc/readdir.3

   1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
   4 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   7 .\"  This notice shall appear on any product containing this material.
   8 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  10 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  11 .Dd Dec 5, 2016
  12 .Dt READDIR 3
  13 .Os
  14 .
  15 .Sh NAME
  16 .
  17 .Nm readdir ,
  18 .Nm readdir_r
  19 .Nd read directory
  20 .
  21 .Sh SYNOPSIS
  22 .
  23 .In dirent.h
  24 .
  25 .Ft "struct dirent *"
  26 .Fo readdir
  27 .Fa "DIR *dirp"
  28 .Fc
  29 .
  30 .Ft int
  31 .Fo readdir_r
  32 .Fa "DIR *restrict dirp"
  33 .Fa "struct dirent **restrict result"
  34 .Fc
  35 .
  36 .Sh DESCRIPTION
  37 The type
  38 .Vt DIR ,
  39 which is defined in the header
  40 .In dirent.h ,
  41 represents
  42 a
  43 .Em directory stream ,
  44 which is an ordered sequence of all the directory
  45 entries in a particular directory.
  46 Directory entries represent files.
  47 Files can be removed from a directory or added to a directory asynchronously
  48 to the operation of
  49 .Fn readdir
  50 and
  51 .Fn readdir_r .
  52 .Ss Fn readdir
  53 The
  54 .Fn readdir
  55 function returns a pointer to a structure representing the directory entry at
  56 the current position in the directory stream specified by the argument
  57 .Fa dirp ,
  58 and positions the directory stream at the next entry.
  59 It returns a null pointer upon reaching the end of the directory stream.
  60 The structure
  61 .Vt dirent
  62 defined by the
  63 .In dirent.h
  64 header describes a directory entry.
  65 .Lp
  66 The
  67 .Fn readdir
  68 function will not return directory entries containing empty names.
  69 If entries for . (dot) or .. (dot-dot) exist, one entry will be returned
  70 for dot and one entry will be returned for dot-dot; otherwise they will not be
  71 returned.
  72 .Lp
  73 The pointer returned by
  74 .Fn readdir
  75 points to data that can be overwritten by another call to
  76 .Fn readdir
  77 on the same directory stream.
  78 These data are not overwritten by another call to
  79 .Fn readdir
  80 on a different directory stream.
  81 .Lp
  82 If a file is removed from or added to the directory after the most recent call
  83 to
  84 .Xr opendir 3C
  85 or
  86 .Xr rewinddir 3C ,
  87 whether a subsequent call to
  88 .Fn readdir
  89 returns an entry for that file is unspecified.
  90 .Lp
  91 The
  92 .Fn readdir
  93 function can buffer several directory entries per actual read operation.
  94 It marks for update the
  95 .Vt st_atime
  96 field of the directory each time the directory is actually read.
  97 .Lp
  98 After a call to
  99 .Xr fork 2 ,
 100 either the parent or child (but not both) can
 101 continue processing the directory stream using
 102 .Fn readdir ,
 103 .Xr rewinddir 3C
 104 or
 105 .Xr seekdir 3C .
 106 If both the parent and child processes
 107 use these functions, the result is undefined.
 108 .Lp
 109 If the entry names a symbolic link, the value of the
 110 .Vt d_ino
 111 member is unspecified.
 112 .Ss Fn readdir_r
 113 Unless the end of the directory stream has been reached or an error occurred,
 114 the
 115 .Fn readdir_r
 116 function initializes the
 117 .Vt dirent
 118 structure referenced by
 119 .Fa entry
 120 to represent the directory entry at the current
 121 position in the directory stream referred to by
 122 .Fa dirp ,
 123 and positions the directory stream at the next entry.
 124 .Lp
 125 The caller must allocate storage pointed to by
 126 .Fa entry
 127 to be large enough for a
 128 .Vt dirent
 129 structure with an array of
 130 .Vt char Vn d_name
 131 member containing at least
 132 .Bro Dv NAME_MAX Brc Ns Li +1
 133 elements.
 134 .Lp
 135 The
 136 .Fn readdir_r
 137 function will not return directory entries containing empty names.
 138 It is unspecified whether entries are returned for . (dot) or ..
 139 (dot-dot).
 140 .Lp
 141 If a file is removed from or added to the directory after the most recent call
 142 to
 143 .Xr opendir 3C
 144 or
 145 .Xr rewinddir 3C ,
 146 whether a subsequent call to
 147 .Fn readdir_r
 148 returns an entry for that file is unspecified.
 149 .Lp
 150 The
 151 .Fn readdir_r
 152 function can buffer several directory entries per actual read operation.
 153 It marks for update the
 154 .Vt st_atime
 155 field of the directory each time the directory is actually read.
 156 .Lp
 157 The
 158 .Fn readdir_r
 159 also sets the pointer pointed to by
 160 .Fa result .
 161 If a directory entry is returned,
 162 the pointer will be set to the same value as the
 163 .Fa entry
 164 argument; otherwise, it will be set to
 165 .Dv NULL .
 166 .
 167 .Sh RETURN VALUES
 168 .
 169 Upon successful completion,
 170 .Fn readdir
 171 function returns a pointer to an object of type
 172 .Vt "struct dirent" .
 173 When an error is encountered, a null pointer is returned and
 174 .Va errno
 175 is set to indicate the error.
 176 When the end of the directory is encountered, a null pointer is returned
 177 and
 178 .Va errno
 179 is not changed.
 180 .Lp
 181 The readdir_r
 182 function returns 0 if the end of the
 183 directory is encountered or a directory entry is stored in the structure
 184 referenced by
 185 .Fa entry .
 186 Otherwise, an error number is returned to indicate the failure.
 187 .
 188 .Sh EXAMPLES
 189 .
 190 .Ss Example 1 Search the current directory for an entry.
 191 The following sample program will search the current directory for each of the
 192 arguments supplied on the command line:
 193 .Bd -literal -offset Ds
 194 #include <sys/types.h>
 195 #include <dirent.h>
 196 #include <errno.h>
 197 #include <stdio.h>
 198 #include <strings.h>
 199
 200 static void lookup(const char *arg)
 201 {
 202         DIR *dirp;
 203         struct dirent *dp;
 204
 205         if ((dirp = opendir(".")) == NULL) {
 206                 perror("couldn't open '.'");
 207                 return;
 208         }
 209
 210         do {
 211                 errno = 0;
 212                 if ((dp = readdir(dirp)) != NULL) {
 213                         if (strcmp(dp->d_name, arg) != 0)
 214                                 continue;
 215
 216                         (void) printf("found %s\en", arg);
 217                         (void) closedir(dirp);
 218                         return;
 219                 }
 220         } while (dp != NULL);
 221
 222         if (errno != 0)
 223                 perror("error reading directory");
 224         else
 225                 (void) printf("failed to find %s\en", arg);
 226         (void) closedir(dirp);
 227         return;
 228 }
 229
 230 int main(int argc, char *argv[])
 231 {
 232         int i;
 233         for (i = 1; i < argc; i++)
 234                 lookup(argv[i]);
 235         return (0);
 236 }
 237 .Ed
 238 .
 239 .Sh ERRORS
 240 .
 241 The
 242 .Fn readdir
 243 and
 244 .Fn readdir_r
 245 functions will fail if:
 246 .Bl -tag -width Er
 247 .It Bq Er EOVERFLOW
 248 One of the values in the structure to be returned cannot be represented
 249 correctly.
 250 .El
 251 .Lp
 252 The
 253 .Fn readdir
 254 and
 255 .Fn readdir_r
 256 functions may fail if:
 257 .Bl -tag -width Er
 258 .It Bq Er EBADF
 259 The
 260 .Fa dirp
 261 argument does not refer to an open directory stream.
 262 .It Bq Er ENOENT
 263 The current position of the directory stream is invalid.
 264 .El
 265 .
 266 .Sh USAGE
 267 .
 268 The
 269 .Fn readdir
 270 and
 271 .Fn readdir_r
 272 functions should be used in
 273 conjunction with
 274 .Xr opendir 3C ,
 275 .Xr closedir 3C , and
 276 .Xr rewinddir 3C
 277 to examine the contents of the directory.
 278 Since
 279 .Fn readdir
 280 returns a null pointer both at the end of the directory and on error,
 281 an application wanting to check for error situations should set
 282 .Va errno
 283 to 0 before calling this function.
 284 If
 285 .Va errno
 286 is set to non-zero on return, an error occurred.
 287 .Lp
 288 It is safe to use
 289 .Fn readdir
 290 in a threaded application, so long as only
 291 one thread reads from the directory stream at any given time.
 292 .Lp
 293 These functions have transitional interfaces for 64-bit file offsets.
 294 See
 295 .Xr lf64 5 .
 296 .
 297 .Sh SEE ALSO
 298 .Xr fork 2 ,
 299 .Xr lstat 2 ,
 300 .Xr symlink 2 ,
 301 .Xr Intro 3 ,
 302 .Xr closedir 3C ,
 303 .Xr opendir 3C ,
 304 .Xr rewinddir 3C ,
 305 .Xr scandir 3C ,
 306 .Xr seekdir 3C ,
 307 .Xr lf64 5
 308 .
 309 .Sh STANDARDS
 310 .Fn readdir
 311 and
 312 .Fn readdir_r
 313 conform to
 314 .St -p1003.1-2008 .