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

NAME

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

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

95   Open a Directory Stream
96       The  following program fragment demonstrates how the opendir() function
97       is used.
98
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
119           #include <stdio.h>
120           #include <dirent.h>
121           #include <fcntl.h>
122           #include <sys/stat.h>
123           #include <stdint.h>
124           #include <stdlib.h>
125           #include <unistd.h>
126
127           int
128           main(int argc, char *argv[])
129           {
130               struct stat statbuf;
131               DIR *d;
132               struct dirent *dp;
133               int dfd, ffd;
134
135               if ((d = fdopendir((dfd = open("./tmp", O_RDONLY)))) == NULL) {
136                   fprintf(stderr, "Cannot open ./tmp directory\n");
137                   exit(1);
138               }
139               while ((dp = readdir(d)) != NULL) {
140                   if (dp->d_name[0] == '.')
141                       continue;
142                   /* there is a possible race condition here as the file
143                    * could be renamed between the readdir and the open */
144                   if ((ffd = openat(dfd, dp->d_name, O_RDONLY)) == -1) {
145                       perror(dp->d_name);
146                       continue;
147                   }
148                   if (fstat(ffd, &statbuf) == 0 && statbuf.st_size > (1024*1024)) {
149                       /* found it ... */
150                       printf("%s: %jdK\n", dp->d_name,
151                           (intmax_t)(statbuf.st_size / 1024));
152                   }
153                   close(ffd);
154               }
155               closedir(d); // note this implicitly closes dfd
156               return 0;
157           }
158

APPLICATION USAGE

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

RATIONALE

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

FUTURE DIRECTIONS

201       None.
202

SEE ALSO

204       closedir(),  dirfd(),  fstatat(),  open(), readdir(), rewinddir(), sym‐
205       link()
206
207       The Base Definitions volume of POSIX.1‐2017, <dirent.h>, <sys_types.h>
208
210       Portions of this text are reprinted and reproduced in  electronic  form
211       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
212       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
213       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
214       Electrical and Electronics Engineers, Inc and The Open Group.   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.opengroup.org/unix/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                  2017                        FDOPENDIR(3P)
Impressum