glibc (2.38)
1 /* Copyright (C) 1991-2023 Free Software Foundation, Inc.
2 This file is part of the GNU C Library.
3
4 The GNU C Library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) any later version.
8
9 The GNU C Library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Lesser General Public License for more details.
13
14 You should have received a copy of the GNU Lesser General Public
15 License along with the GNU C Library; if not, see
16 <https://www.gnu.org/licenses/>. */
17
18 /*
19 * POSIX Standard: 5.1.2 Directory Operations <dirent.h>
20 */
21
22 #ifndef _DIRENT_H
23 #define _DIRENT_H 1
24
25 #include <features.h>
26
27 __BEGIN_DECLS
28
29 #include <bits/types.h>
30
31 #ifdef __USE_XOPEN
32 # ifndef __ino_t_defined
33 # ifndef __USE_FILE_OFFSET64
34 typedef __ino_t ino_t;
35 # else
36 typedef __ino64_t ino_t;
37 # endif
38 # define __ino_t_defined
39 # endif
40 # if defined __USE_LARGEFILE64 && !defined __ino64_t_defined
41 typedef __ino64_t ino64_t;
42 # define __ino64_t_defined
43 # endif
44 #endif
45
46 /* This file defines `struct dirent'.
47
48 It defines the macro `_DIRENT_HAVE_D_NAMLEN' iff there is a `d_namlen'
49 member that gives the length of `d_name'.
50
51 It defines the macro `_DIRENT_HAVE_D_RECLEN' iff there is a `d_reclen'
52 member that gives the size of the entire directory entry.
53
54 It defines the macro `_DIRENT_HAVE_D_OFF' iff there is a `d_off'
55 member that gives the file offset of the next directory entry.
56
57 It defines the macro `_DIRENT_HAVE_D_TYPE' iff there is a `d_type'
58 member that gives the type of the file.
59 */
60
61 #include <bits/dirent.h>
62
63 #if defined __USE_MISC && !defined d_fileno
64 # define d_ino d_fileno /* Backward compatibility. */
65 #endif
66
67 /* These macros extract size information from a `struct dirent *'.
68 They may evaluate their argument multiple times, so it must not
69 have side effects. Each of these may involve a relatively costly
70 call to `strlen' on some systems, so these values should be cached.
71
72 _D_EXACT_NAMLEN (DP) returns the length of DP->d_name, not including
73 its terminating null character.
74
75 _D_ALLOC_NAMLEN (DP) returns a size at least (_D_EXACT_NAMLEN (DP) + 1);
76 that is, the allocation size needed to hold the DP->d_name string.
77 Use this macro when you don't need the exact length, just an upper bound.
78 This macro is less likely to require calling `strlen' than _D_EXACT_NAMLEN.
79 */
80
81 #ifdef _DIRENT_HAVE_D_NAMLEN
82 # define _D_EXACT_NAMLEN(d) ((d)->d_namlen)
83 # define _D_ALLOC_NAMLEN(d) (_D_EXACT_NAMLEN (d) + 1)
84 #else
85 # define _D_EXACT_NAMLEN(d) (strlen ((d)->d_name))
86 # ifdef _DIRENT_HAVE_D_RECLEN
87 # define _D_ALLOC_NAMLEN(d) (((char *) (d) + (d)->d_reclen) - &(d)->d_name[0])
88 # else
89 # define _D_ALLOC_NAMLEN(d) (sizeof (d)->d_name > 1 ? sizeof (d)->d_name \
90 : _D_EXACT_NAMLEN (d) + 1)
91 # endif
92 #endif
93
94
95 #ifdef __USE_MISC
96 /* File types for `d_type'. */
97 enum
98 {
99 DT_UNKNOWN = 0,
100 # define DT_UNKNOWN DT_UNKNOWN
101 DT_FIFO = 1,
102 # define DT_FIFO DT_FIFO
103 DT_CHR = 2,
104 # define DT_CHR DT_CHR
105 DT_DIR = 4,
106 # define DT_DIR DT_DIR
107 DT_BLK = 6,
108 # define DT_BLK DT_BLK
109 DT_REG = 8,
110 # define DT_REG DT_REG
111 DT_LNK = 10,
112 # define DT_LNK DT_LNK
113 DT_SOCK = 12,
114 # define DT_SOCK DT_SOCK
115 DT_WHT = 14
116 # define DT_WHT DT_WHT
117 };
118
119 /* Convert between stat structure types and directory types. */
120 # define IFTODT(mode) (((mode) & 0170000) >> 12)
121 # define DTTOIF(dirtype) ((dirtype) << 12)
122 #endif
123
124
125 /* This is the data type of directory stream objects.
126 The actual structure is opaque to users. */
127 typedef struct __dirstream DIR;
128
129 /* Close the directory stream DIRP.
130 Return 0 if successful, -1 if not.
131
132 This function is a possible cancellation point and therefore not
133 marked with __THROW. */
134 extern int closedir (DIR *__dirp) __nonnull ((1));
135
136 /* Open a directory stream on NAME.
137 Return a DIR stream on the directory, or NULL if it could not be opened.
138
139 This function is a possible cancellation point and therefore not
140 marked with __THROW. */
141 extern DIR *opendir (const char *__name) __nonnull ((1))
142 __attribute_malloc__ __attr_dealloc (closedir, 1);
143
144 #ifdef __USE_XOPEN2K8
145 /* Same as opendir, but open the stream on the file descriptor FD.
146
147 This function is a possible cancellation point and therefore not
148 marked with __THROW. */
149 extern DIR *fdopendir (int __fd)
150 __attribute_malloc__ __attr_dealloc (closedir, 1);
151 #endif
152
153 /* Read a directory entry from DIRP. Return a pointer to a `struct
154 dirent' describing the entry, or NULL for EOF or error. The
155 storage returned may be overwritten by a later readdir call on the
156 same DIR stream.
157
158 If the Large File Support API is selected we have to use the
159 appropriate interface.
160
161 This function is a possible cancellation point and therefore not
162 marked with __THROW. */
163 #ifndef __USE_FILE_OFFSET64
164 extern struct dirent *readdir (DIR *__dirp) __nonnull ((1));
165 #else
166 # ifdef __REDIRECT
167 extern struct dirent *__REDIRECT (readdir, (DIR *__dirp), readdir64)
168 __nonnull ((1));
169 # else
170 # define readdir readdir64
171 # endif
172 #endif
173
174 #ifdef __USE_LARGEFILE64
175 extern struct dirent64 *readdir64 (DIR *__dirp) __nonnull ((1));
176 #endif
177
178 #ifdef __USE_POSIX
179 /* Reentrant version of `readdir'. Return in RESULT a pointer to the
180 next entry.
181
182 This function is a possible cancellation point and therefore not
183 marked with __THROW. */
184 # ifndef __USE_FILE_OFFSET64
185 extern int readdir_r (DIR *__restrict __dirp,
186 struct dirent *__restrict __entry,
187 struct dirent **__restrict __result)
188 __nonnull ((1, 2, 3)) __attribute_deprecated__;
189 # else
190 # ifdef __REDIRECT
191 extern int __REDIRECT (readdir_r,
192 (DIR *__restrict __dirp,
193 struct dirent *__restrict __entry,
194 struct dirent **__restrict __result),
195 readdir64_r)
196 __nonnull ((1, 2, 3)) __attribute_deprecated__;
197 # else
198 # define readdir_r readdir64_r
199 # endif
200 # endif
201
202 # ifdef __USE_LARGEFILE64
203 extern int readdir64_r (DIR *__restrict __dirp,
204 struct dirent64 *__restrict __entry,
205 struct dirent64 **__restrict __result)
206 __nonnull ((1, 2, 3)) __attribute_deprecated__;
207 # endif
208 #endif /* POSIX or misc */
209
210 /* Rewind DIRP to the beginning of the directory. */
211 extern void rewinddir (DIR *__dirp) __THROW __nonnull ((1));
212
213 #if defined __USE_MISC || defined __USE_XOPEN
214 # include <bits/types.h>
215
216 /* Seek to position POS on DIRP. */
217 extern void seekdir (DIR *__dirp, long int __pos) __THROW __nonnull ((1));
218
219 /* Return the current position of DIRP. */
220 extern long int telldir (DIR *__dirp) __THROW __nonnull ((1));
221 #endif
222
223 #ifdef __USE_XOPEN2K8
224
225 /* Return the file descriptor used by DIRP. */
226 extern int dirfd (DIR *__dirp) __THROW __nonnull ((1));
227
228 # if defined __OPTIMIZE__ && defined _DIR_dirfd
229 # define dirfd(dirp) _DIR_dirfd (dirp)
230 # endif
231
232 # ifdef __USE_MISC
233 # ifndef MAXNAMLEN
234 /* Get the definitions of the POSIX.1 limits. */
235 # include <bits/posix1_lim.h>
236
237 /* `MAXNAMLEN' is the BSD name for what POSIX calls `NAME_MAX'. */
238 # ifdef NAME_MAX
239 # define MAXNAMLEN NAME_MAX
240 # else
241 # define MAXNAMLEN 255
242 # endif
243 # endif
244 # endif
245
246 # define __need_size_t
247 # include <stddef.h>
248
249 /* Scan the directory DIR, calling SELECTOR on each directory entry.
250 Entries for which SELECT returns nonzero are individually malloc'd,
251 sorted using qsort with CMP, and collected in a malloc'd array in
252 *NAMELIST. Returns the number of entries selected, or -1 on error.
253
254 This function is a cancellation point and therefore not marked with
255 __THROW. */
256 # ifndef __USE_FILE_OFFSET64
257 extern int scandir (const char *__restrict __dir,
258 struct dirent ***__restrict __namelist,
259 int (*__selector) (const struct dirent *),
260 int (*__cmp) (const struct dirent **,
261 const struct dirent **))
262 __nonnull ((1, 2));
263 # else
264 # ifdef __REDIRECT
265 extern int __REDIRECT (scandir,
266 (const char *__restrict __dir,
267 struct dirent ***__restrict __namelist,
268 int (*__selector) (const struct dirent *),
269 int (*__cmp) (const struct dirent **,
270 const struct dirent **)),
271 scandir64) __nonnull ((1, 2));
272 # else
273 # define scandir scandir64
274 # endif
275 # endif
276
277 # if defined __USE_GNU && defined __USE_LARGEFILE64
278 /* This function is like `scandir' but it uses the 64bit dirent structure.
279 Please note that the CMP function must now work with struct dirent64 **. */
280 extern int scandir64 (const char *__restrict __dir,
281 struct dirent64 ***__restrict __namelist,
282 int (*__selector) (const struct dirent64 *),
283 int (*__cmp) (const struct dirent64 **,
284 const struct dirent64 **))
285 __nonnull ((1, 2));
286 # endif
287
288 # ifdef __USE_GNU
289 /* Similar to `scandir' but a relative DIR name is interpreted relative
290 to the directory for which DFD is a descriptor.
291
292 This function is a cancellation point and therefore not marked with
293 __THROW. */
294 # ifndef __USE_FILE_OFFSET64
295 extern int scandirat (int __dfd, const char *__restrict __dir,
296 struct dirent ***__restrict __namelist,
297 int (*__selector) (const struct dirent *),
298 int (*__cmp) (const struct dirent **,
299 const struct dirent **))
300 __nonnull ((2, 3));
301 # else
302 # ifdef __REDIRECT
303 extern int __REDIRECT (scandirat,
304 (int __dfd, const char *__restrict __dir,
305 struct dirent ***__restrict __namelist,
306 int (*__selector) (const struct dirent *),
307 int (*__cmp) (const struct dirent **,
308 const struct dirent **)),
309 scandirat64) __nonnull ((2, 3));
310 # else
311 # define scandirat scandirat64
312 # endif
313 # endif
314
315 /* This function is like `scandir' but it uses the 64bit dirent structure.
316 Please note that the CMP function must now work with struct dirent64 **. */
317 extern int scandirat64 (int __dfd, const char *__restrict __dir,
318 struct dirent64 ***__restrict __namelist,
319 int (*__selector) (const struct dirent64 *),
320 int (*__cmp) (const struct dirent64 **,
321 const struct dirent64 **))
322 __nonnull ((2, 3));
323 # endif
324
325 /* Function to compare two `struct dirent's alphabetically. */
326 # ifndef __USE_FILE_OFFSET64
327 extern int alphasort (const struct dirent **__e1,
328 const struct dirent **__e2)
329 __THROW __attribute_pure__ __nonnull ((1, 2));
330 # else
331 # ifdef __REDIRECT
332 extern int __REDIRECT_NTH (alphasort,
333 (const struct dirent **__e1,
334 const struct dirent **__e2),
335 alphasort64) __attribute_pure__ __nonnull ((1, 2));
336 # else
337 # define alphasort alphasort64
338 # endif
339 # endif
340
341 # if defined __USE_GNU && defined __USE_LARGEFILE64
342 extern int alphasort64 (const struct dirent64 **__e1,
343 const struct dirent64 **__e2)
344 __THROW __attribute_pure__ __nonnull ((1, 2));
345 # endif
346 #endif /* Use XPG7. */
347
348
349 #ifdef __USE_MISC
350 /* Read directory entries from FD into BUF, reading at most NBYTES.
351 Reading starts at offset *BASEP, and *BASEP is updated with the new
352 position after reading. Returns the number of bytes read; zero when at
353 end of directory; or -1 for errors. */
354 # ifndef __USE_FILE_OFFSET64
355 extern __ssize_t getdirentries (int __fd, char *__restrict __buf,
356 size_t __nbytes,
357 __off_t *__restrict __basep)
358 __THROW __nonnull ((2, 4));
359 # else
360 # ifdef __REDIRECT
361 extern __ssize_t __REDIRECT_NTH (getdirentries,
362 (int __fd, char *__restrict __buf,
363 size_t __nbytes,
364 __off64_t *__restrict __basep),
365 getdirentries64) __nonnull ((2, 4));
366 # else
367 # define getdirentries getdirentries64
368 # endif
369 # endif
370
371 # ifdef __USE_LARGEFILE64
372 extern __ssize_t getdirentries64 (int __fd, char *__restrict __buf,
373 size_t __nbytes,
374 __off64_t *__restrict __basep)
375 __THROW __nonnull ((2, 4));
376 # endif
377 #endif /* Use misc. */
378
379 #ifdef __USE_GNU
380 /* Function to compare two `struct dirent's by name & version. */
381 # ifndef __USE_FILE_OFFSET64
382 extern int versionsort (const struct dirent **__e1,
383 const struct dirent **__e2)
384 __THROW __attribute_pure__ __nonnull ((1, 2));
385 # else
386 # ifdef __REDIRECT
387 extern int __REDIRECT_NTH (versionsort,
388 (const struct dirent **__e1,
389 const struct dirent **__e2),
390 versionsort64)
391 __attribute_pure__ __nonnull ((1, 2));
392 # else
393 # define versionsort versionsort64
394 # endif
395 # endif
396
397 # ifdef __USE_LARGEFILE64
398 extern int versionsort64 (const struct dirent64 **__e1,
399 const struct dirent64 **__e2)
400 __THROW __attribute_pure__ __nonnull ((1, 2));
401 # endif
402 #endif /* Use GNU. */
403
404 __END_DECLS
405
406 #include <bits/dirent_ext.h>
407
408 #endif /* dirent.h */
Browse
Usage
Versions