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