]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) |
2 | .\" | |
3 | .\" Permission is granted to make and distribute verbatim copies of this | |
4 | .\" manual provided the copyright notice and this permission notice are | |
5 | .\" preserved on all copies. | |
6 | .\" | |
7 | .\" Permission is granted to copy and distribute modified versions of this | |
8 | .\" manual under the conditions for verbatim copying, provided that the | |
9 | .\" entire resulting derived work is distributed under the terms of a | |
10 | .\" permission notice identical to this one. | |
c13182ef | 11 | .\" |
fea681da MK |
12 | .\" Since the Linux kernel and libraries are constantly changing, this |
13 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
14 | .\" responsibility for errors or omissions, or for damages resulting from | |
15 | .\" the use of the information contained herein. The author(s) may not | |
16 | .\" have taken the same level of care in the production of this manual, | |
17 | .\" which is licensed free of charge, as they might when working | |
18 | .\" professionally. | |
c13182ef | 19 | .\" |
fea681da MK |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
23 | .\" References consulted: | |
24 | .\" Linux libc source code | |
25 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
26 | .\" 386BSD man pages | |
27 | .\" Modified Sat Jul 24 16:09:49 1993 by Rik Faith (faith@cs.unc.edu) | |
28 | .\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) | |
29 | .\" Modified 22 July 1996 by Andries Brouwer (aeb@cwi.nl) | |
24b31b7b MK |
30 | .\" 2007-07-30 Ulrich Drepper <drepper@redhat.com>, mtk: |
31 | .\" Rework discussion of non-standard structure fields. | |
fea681da | 32 | .\" |
58f362c3 | 33 | .TH READDIR 3 2008-06-20 "" "Linux Programmer's Manual" |
fea681da MK |
34 | .SH NAME |
35 | readdir \- read a directory | |
36 | .SH SYNOPSIS | |
37 | .nf | |
38 | .B #include <sys/types.h> | |
39 | .sp | |
40 | .B #include <dirent.h> | |
41 | .sp | |
42 | .BI "struct dirent *readdir(DIR *" dir ); | |
43 | .fi | |
44 | .SH DESCRIPTION | |
60a90ecd MK |
45 | The |
46 | .BR readdir () | |
47 | function returns a pointer to a \fIdirent\fP structure | |
fea681da | 48 | representing the next directory entry in the directory stream pointed |
1c44bd5b MK |
49 | to by \fIdir\fP. |
50 | It returns NULL on reaching the end-of-file or if | |
fea681da MK |
51 | an error occurred. |
52 | .PP | |
a03d317b MK |
53 | On Linux, the |
54 | .I dirent | |
55 | structure is defined as follows: | |
56 | .PP | |
bd191423 | 57 | .in +4n |
a03d317b MK |
58 | .nf |
59 | struct dirent { | |
60 | ino_t d_ino; /* inode number */ | |
61 | off_t d_off; /* offset to the next dirent */ | |
62 | unsigned short d_reclen; /* length of this record */ | |
63 | unsigned char d_type; /* type of file */ | |
64 | char d_name[256]; /* filename */ | |
65 | }; | |
66 | .fi | |
bd191423 | 67 | .in |
a03d317b | 68 | .PP |
fea681da MK |
69 | According to POSIX, the |
70 | .I dirent | |
71 | structure contains a field | |
72 | .I "char d_name[]" | |
73 | of unspecified size, with at most | |
74 | .B NAME_MAX | |
28d88c17 | 75 | characters preceding the terminating null byte. |
68e1685c | 76 | POSIX.1-2001 also documents the field |
fea681da MK |
77 | .I "ino_t d_ino" |
78 | as an XSI extension. | |
237dedac MK |
79 | The other fields are unstandardized, and not present on all systems; |
80 | see NOTES below for some further details. | |
fea681da | 81 | .PP |
60a90ecd MK |
82 | The data returned by |
83 | .BR readdir () | |
237dedac | 84 | may be overwritten by subsequent calls to |
60a90ecd MK |
85 | .BR readdir () |
86 | for the same directory stream. | |
fea681da | 87 | .SH "RETURN VALUE" |
60a90ecd MK |
88 | The |
89 | .BR readdir () | |
90 | function returns a pointer to a | |
c13182ef | 91 | .I dirent |
28d88c17 | 92 | structure, or |
fea681da | 93 | NULL if an error occurs or end-of-file is reached. |
cca657e2 MK |
94 | On error, |
95 | .I errno | |
96 | is set appropriately. | |
fea681da MK |
97 | .SH ERRORS |
98 | .TP | |
99 | .B EBADF | |
100 | Invalid directory stream descriptor \fIdir\fP. | |
101 | .SH "CONFORMING TO" | |
68e1685c | 102 | SVr4, 4.3BSD, POSIX.1-2001 |
624c55e8 | 103 | .SH NOTES |
237dedac MK |
104 | Only the fields |
105 | .I d_name | |
106 | and | |
107 | .I d_ino | |
108 | are specified in POSIX.1-2001. | |
109 | The remaining fields are available on many, but not all systems. | |
110 | Under glibc, | |
111 | programs can check for the availability of the fields not defined | |
bf1c0ede | 112 | in POSIX.1 by testing whether the macros |
237dedac MK |
113 | .BR _DIRENT_HAVE_D_NAMLEN , |
114 | .BR _DIRENT_HAVE_D_RECLEN , | |
115 | .BR _DIRENT_HAVE_D_OFF , | |
116 | or | |
0daa9e92 | 117 | .B _DIRENT_HAVE_D_TYPE |
237dedac MK |
118 | are defined. |
119 | ||
120 | Other than Linux, the | |
121 | .I d_type | |
122 | field is available mainly only on BSD systems. | |
0dd0df4e | 123 | This field makes it possible to avoid the expense of calling |
3273a01d | 124 | .BR stat (2) |
237dedac MK |
125 | if further |
126 | actions depend on the type of the file. | |
624c55e8 MK |
127 | If the |
128 | .B _BSD_SOURCE | |
129 | feature test macro is defined, | |
130 | then glibc defines the following macro constants | |
131 | for the value returned in | |
237dedac | 132 | .IR d_type : |
624c55e8 MK |
133 | .TP 12 |
134 | .B DT_UNKNOWN | |
135 | The file type is unknown. | |
136 | .\" The glibc manual says that on some systems this is the only | |
137 | .\" value returned | |
138 | .TP | |
139 | .B DT_REG | |
140 | This is a regular file. | |
141 | .TP | |
58f362c3 MK |
142 | .B DT_LNK |
143 | This is a symbolic link. | |
144 | .TP | |
624c55e8 MK |
145 | .B DT_DIR |
146 | This is a directory. | |
147 | .TP | |
148 | .B DT_FIFO | |
149 | This is a named pipe, or FIFO. | |
150 | .TP | |
151 | .B DT_SOCK | |
237dedac | 152 | This is a Unix domain socket. |
624c55e8 MK |
153 | .TP |
154 | .B DT_CHR | |
155 | This is a character device. | |
156 | .TP | |
157 | .B DT_BLK | |
158 | This is a block device. | |
237dedac MK |
159 | .PP |
160 | If the file type could not be determined, the value | |
0daa9e92 | 161 | .B DT_UNKNOWN |
237dedac MK |
162 | is returned in |
163 | .IR d_type . | |
fea681da MK |
164 | .SH "SEE ALSO" |
165 | .BR read (2), | |
166 | .BR closedir (3), | |
167 | .BR dirfd (3), | |
53eef14c | 168 | .BR ftw (3), |
fea681da MK |
169 | .BR opendir (3), |
170 | .BR rewinddir (3), | |
171 | .BR scandir (3), | |
172 | .BR seekdir (3), | |
624c55e8 MK |
173 | .BR telldir (3), |
174 | .BR feature_test_macros (7) |