1FDOPENDIR(3P)              POSIX Programmer's Manual             FDOPENDIR(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       fdopendir, opendir — open directory associated with file descriptor
14

SYNOPSIS

16       #include <dirent.h>
17
18       DIR *fdopendir(int fd);
19       DIR *opendir(const char *dirname);
20

DESCRIPTION

22       The fdopendir() function shall be equivalent to the opendir()  function
23       except that the directory is specified by a file descriptor rather than
24       by a name. The file offset associated with the file descriptor  at  the
25       time of the call determines which entries are returned.
26
27       Upon  successful  return from fdopendir(), the file descriptor is under
28       the control of the system, and if any attempt is made to close the file
29       descriptor, or to modify the state of the associated description, other
30       than by means of closedir(), readdir(),  readdir_r(),  rewinddir(),  or
31       seekdir(),  the behavior is undefined. Upon calling closedir() the file
32       descriptor shall be closed.
33
34       It is unspecified whether the FD_CLOEXEC flag will be set on  the  file
35       descriptor by a successful call to fdopendir().
36
37       The  opendir()  function shall open a directory stream corresponding to
38       the directory named by the dirname argument. The  directory  stream  is
39       positioned  at  the first entry. If the type DIR is implemented using a
40       file descriptor, applications shall only be able to open up to a  total
41       of {OPEN_MAX} files and directories.
42
43       If  the type DIR is implemented using a file descriptor, the descriptor
44       shall be obtained as if the O_DIRECTORY flag was passed to open().
45

RETURN VALUE

47       Upon successful completion, these functions shall return a  pointer  to
48       an  object of type DIR.  Otherwise, these functions shall return a null
49       pointer and set errno to indicate the error.
50

ERRORS

52       The fdopendir() function shall fail if:
53
54       EBADF  The fd argument is not a valid file descriptor open for reading.
55
56       ENOTDIR
57              The descriptor fd is not associated with a directory.
58
59       The opendir() function shall fail if:
60
61       EACCES Search permission is denied for the component of the path prefix
62              of dirname or read permission is denied for dirname.
63
64       ELOOP  A loop exists in symbolic links encountered during resolution of
65              the dirname argument.
66
67       ENAMETOOLONG
68              The  length  of  a  component  of  a  pathname  is  longer  than
69              {NAME_MAX}.
70
71       ENOENT A  component  of  dirname does not name an existing directory or
72              dirname is an empty string.
73
74       ENOTDIR
75              A component of dirname names an existing file that is neither  a
76              directory nor a symbolic link to a directory.
77
78       The opendir() function may fail if:
79
80       ELOOP  More  than  {SYMLOOP_MAX} symbolic links were encountered during
81              resolution of the dirname argument.
82
83       EMFILE All file descriptors available  to  the  process  are  currently
84              open.
85
86       ENAMETOOLONG
87              The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
88              tion of a symbolic link produced an intermediate result  with  a
89              length that exceeds {PATH_MAX}.
90
91       ENFILE Too many files are currently open in the system.
92
93       The following sections are informative.
94

EXAMPLES

96   Open a Directory Stream
97       The  following program fragment demonstrates how the opendir() function
98       is used.
99
100           #include <dirent.h>
101           ...
102               DIR *dir;
103               struct dirent *dp;
104           ...
105               if ((dir = opendir (".")) == NULL) {
106                   perror ("Cannot open .");
107                   exit (1);
108               }
109
110               while ((dp = readdir (dir)) != NULL) {
111           ...
112
113   Find And Open a File
114       The following program searches through a given  directory  looking  for
115       files  whose  name  does  not begin with a dot and whose size is larger
116       than 1 MiB.
117
118           #include <stdio.h>
119           #include <dirent.h>
120           #include <fcntl.h>
121           #include <sys/stat.h>
122           #include <stdint.h>
123           #include <stdlib.h>
124           #include <unistd.h>
125
126           int
127           main(int argc, char *argv[])
128           {
129               struct stat statbuf;
130               DIR *d;
131               struct dirent *dp;
132               int dfd, ffd;
133
134               if ((d = fdopendir((dfd = open("./tmp", O_RDONLY)))) == NULL) {
135                   fprintf(stderr, "Cannot open ./tmp directory\n");
136                   exit(1);
137               }
138               while ((dp = readdir(d)) != NULL) {
139                   if (dp->d_name[0] == '.')
140                       continue;
141                   /* there is a possible race condition here as the file
142                    * could be renamed between the readdir and the open */
143                   if ((ffd = openat(dfd, dp->d_name, O_RDONLY)) == -1) {
144                       perror(dp->d_name);
145                       continue;
146                   }
147                   if (fstat(ffd, &statbuf) == 0 && statbuf.st_size > (1024*1024)) {
148                       /* found it ... */
149                       printf("%s: %jdK\n", dp->d_name,
150                           (intmax_t)(statbuf.st_size / 1024));
151                   }
152                   close(ffd);
153               }
154               closedir(d); // note this implicitly closes dfd
155               return 0;
156           }
157

APPLICATION USAGE

159       The opendir() function should be used in  conjunction  with  readdir(),
160       closedir(),  and  rewinddir()  to examine the contents of the directory
161       (see the EXAMPLES section in readdir()).  This  method  is  recommended
162       for portability.
163

RATIONALE

165       The  purpose  of the fdopendir() function is to enable opening files in
166       directories other than the current working directory  without  exposure
167       to  race conditions. Any part of the path of a file could be changed in
168       parallel to a call to opendir(), resulting in unspecified behavior.
169
170       Based on historical implementations, the rules about  file  descriptors
171       apply   to   directory   streams  as  well.  However,  this  volume  of
172       POSIX.1‐2008 does not mandate that the directory stream be  implemented
173       using file descriptors. The description of closedir() clarifies that if
174       a file descriptor is used for the directory  stream,  it  is  mandatory
175       that  closedir() deallocate the file descriptor. When a file descriptor
176       is used to implement  the  directory  stream,  it  behaves  as  if  the
177       FD_CLOEXEC had been set for the file descriptor.
178
179       The  directory entries for dot and dot-dot are optional. This volume of
180       POSIX.1‐2008 does not provide a way to test a priori  for  their  exis‐
181       tence  because  an application that is portable must be written to look
182       for (and usually ignore) those entries. Writing code that presumes that
183       they  are the first two entries does not always work, as many implemen‐
184       tations permit them to be other than the  first  two  entries,  with  a
185       ``normal'' entry preceding them. There is negligible value in providing
186       a way to determine what the implementation does  because  the  code  to
187       deal  with dot and dot-dot must be written in any case and because such
188       a flag would add to the list of those flags (which has proven in itself
189       to be objectionable) and might be abused.
190
191       Since the structure and buffer allocation, if any, for directory opera‐
192       tions are defined by the implementation, this  volume  of  POSIX.1‐2008
193       imposes  no  portability requirements for erroneous program constructs,
194       erroneous data, or the use of unspecified values such  as  the  use  or
195       referencing  of a dirp value or a dirent structure value after a direc‐
196       tory stream has been closed or after a fork() or one of the exec  func‐
197       tion calls.
198

FUTURE DIRECTIONS

200       None.
201

SEE ALSO

203       closedir(),  dirfd(),  fstatat(),  open(), readdir(), rewinddir(), sym‐
204       link()
205
206       The Base Definitions volume of POSIX.1‐2008, <dirent.h>, <sys_types.h>
207
209       Portions of this text are reprinted and reproduced in  electronic  form
210       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
211       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
212       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
213       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
214       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
215       event of any discrepancy between this version and the original IEEE and
216       The  Open Group Standard, the original IEEE and The Open Group Standard
217       is the referee document. The original Standard can be  obtained  online
218       at http://www.unix.org/online.html .
219
220       Any  typographical  or  formatting  errors that appear in this page are
221       most likely to have been introduced during the conversion of the source
222       files  to  man page format. To report such errors, see https://www.ker
223       nel.org/doc/man-pages/reporting_bugs.html .
224
225
226
227IEEE/The Open Group                  2013                        FDOPENDIR(3P)
Impressum