1OPENDIR(P) POSIX Programmer's Manual OPENDIR(P)
2
6 opendir - open a directory
7
9 #include <dirent.h>
10 DIR *opendir(const char *dirname);
12
15 The opendir() function shall open a directory stream corresponding to
16 the directory named by the dirname argument. The directory stream is
17 positioned at the first entry. If the type DIR is implemented using a
18 file descriptor, applications shall only be able to open up to a total
19 of {OPEN_MAX} files and directories.
20
22 Upon successful completion, opendir() shall return a pointer to an
23 object of type DIR. Otherwise, a null pointer shall be returned and
24 errno set to indicate the error.
25
27 The opendir() function shall fail if:
28 EACCES Search permission is denied for the component of the path prefix
30 of dirname or read permission is denied for dirname.
31 ELOOP A loop exists in symbolic links encountered during resolution of
33 the dirname argument.
34 ENAMETOOLONG
36 The length of the dirname argument exceeds {PATH_MAX} or a path‐
37 name component is longer than {NAME_MAX}.
38 ENOENT A component of dirname does not name an existing directory or
40 dirname is an empty string.
41 ENOTDIR
43 A component of dirname is not a directory.
44 The opendir() function may fail if:
47 ELOOP More than {SYMLOOP_MAX} symbolic links were encountered during
49 resolution of the dirname argument.
50 EMFILE {OPEN_MAX} file descriptors are currently open in the calling
52 process.
53 ENAMETOOLONG
55 As a result of encountering a symbolic link in resolution of the
56 dirname argument, the length of the substituted pathname string
57 exceeded {PATH_MAX}.
58 ENFILE Too many files are currently open in the system.
60 The following sections are informative.
64
66 Open a Directory Stream
67 The following program fragment demonstrates how the opendir() function
68 is used.
69 #include <sys/types.h>
72 #include <dirent.h>
73 #include <libgen.h>
74 ...
75 DIR *dir;
76 struct dirent *dp;
77 ...
78 if ((dir = opendir (".")) == NULL) {
79 perror ("Cannot open .");
80 exit (1);
81 }
82 while ((dp = readdir (dir)) != NULL) {
85 ...
86
88 The opendir() function should be used in conjunction with readdir(),
89 closedir(), and rewinddir() to examine the contents of the directory
90 (see the EXAMPLES section in readdir() ). This method is recommended
91 for portability.
92
94 Based on historical implementations, the rules about file descriptors
95 apply to directory streams as well. However, this volume of
96 IEEE Std 1003.1-2001 does not mandate that the directory stream be
97 implemented using file descriptors. The description of closedir() clar‐
98 ifies that if a file descriptor is used for the directory stream, it is
99 mandatory that closedir() deallocate the file descriptor. When a file
100 descriptor is used to implement the directory stream, it behaves as if
101 the FD_CLOEXEC had been set for the file descriptor.
102 The directory entries for dot and dot-dot are optional. This volume of
104 IEEE Std 1003.1-2001 does not provide a way to test a priori for their
105 existence because an application that is portable must be written to
106 look for (and usually ignore) those entries. Writing code that presumes
107 that they are the first two entries does not always work, as many
108 implementations permit them to be other than the first two entries,
109 with a "normal" entry preceding them. There is negligible value in pro‐
110 viding a way to determine what the implementation does because the code
111 to deal with dot and dot-dot must be written in any case and because
112 such a flag would add to the list of those flags (which has proven in
113 itself to be objectionable) and might be abused.
114 Since the structure and buffer allocation, if any, for directory opera‐
116 tions are defined by the implementation, this volume of
117 IEEE Std 1003.1-2001 imposes no portability requirements for erroneous
118 program constructs, erroneous data, or the use of unspecified values
119 such as the use or referencing of a dirp value or a dirent structure
120 value after a directory stream has been closed or after a fork() or one
121 of the exec function calls.
122
124 None.
125
127 closedir() , lstat() , readdir() , rewinddir() , symlink() , the Base
128 Definitions volume of IEEE Std 1003.1-2001, <dirent.h>, <limits.h>,
129 <sys/types.h>
130
132 Portions of this text are reprinted and reproduced in electronic form
133 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
134 -- Portable Operating System Interface (POSIX), The Open Group Base
135 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
136 Electrical and Electronics Engineers, Inc and The Open Group. In the
137 event of any discrepancy between this version and the original IEEE and
138 The Open Group Standard, the original IEEE and The Open Group Standard
139 is the referee document. The original Standard can be obtained online
140 at http://www.opengroup.org/unix/online.html .
141IEEE/The Open Group 2003 OPENDIR(P)