1/* Copyright (C) 1991-2016 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 <http://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
34typedef __ino_t ino_t;
35# else
36typedef __ino64_t ino_t;
37# endif
38# define __ino_t_defined
39# endif
40# if defined __USE_LARGEFILE64 && !defined __ino64_t_defined
41typedef __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'. */
97enum
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. */
127typedef struct __dirstream DIR;
128
129/* Open a directory stream on NAME.
130 Return a DIR stream on the directory, or NULL if it could not be opened.
131
132 This function is a possible cancellation point and therefore not
133 marked with __THROW. */
134extern DIR *opendir (const char *__name) __nonnull ((1));
135
136#ifdef __USE_XOPEN2K8
137/* Same as opendir, but open the stream on the file descriptor FD.
138
139 This function is a possible cancellation point and therefore not
140 marked with __THROW. */
141extern DIR *fdopendir (int __fd);
142#endif
143
144/* Close the directory stream DIRP.
145 Return 0 if successful, -1 if not.
146
147 This function is a possible cancellation point and therefore not
148 marked with __THROW. */
149extern int closedir (DIR *__dirp) __nonnull ((1));
150
151/* Read a directory entry from DIRP. Return a pointer to a `struct
152 dirent' describing the entry, or NULL for EOF or error. The
153 storage returned may be overwritten by a later readdir call on the
154 same DIR stream.
155
156 If the Large File Support API is selected we have to use the
157 appropriate interface.
158
159 This function is a possible cancellation point and therefore not
160 marked with __THROW. */
161#ifndef __USE_FILE_OFFSET64
162extern struct dirent *readdir (DIR *__dirp) __nonnull ((1));
163#else
164# ifdef __REDIRECT
165extern struct dirent *__REDIRECT (readdir, (DIR *__dirp), readdir64)
166 __nonnull ((1));
167# else
168# define readdir readdir64
169# endif
170#endif
171
172#ifdef __USE_LARGEFILE64
173extern struct dirent64 *readdir64 (DIR *__dirp) __nonnull ((1));
174#endif
175
176#ifdef __USE_POSIX
177/* Reentrant version of `readdir'. Return in RESULT a pointer to the
178 next entry.
179
180 This function is a possible cancellation point and therefore not
181 marked with __THROW. */
182# ifndef __USE_FILE_OFFSET64
183extern int readdir_r (DIR *__restrict __dirp,
184 struct dirent *__restrict __entry,
185 struct dirent **__restrict __result)
186 __nonnull ((1, 2, 3));
187# else
188# ifdef __REDIRECT
189extern int __REDIRECT (readdir_r,
190 (DIR *__restrict __dirp,
191 struct dirent *__restrict __entry,
192 struct dirent **__restrict __result),
193 readdir64_r) __nonnull ((1, 2, 3));
194# else
195# define readdir_r readdir64_r
196# endif
197# endif
198
199# ifdef __USE_LARGEFILE64
200extern int readdir64_r (DIR *__restrict __dirp,
201 struct dirent64 *__restrict __entry,
202 struct dirent64 **__restrict __result)
203 __nonnull ((1, 2, 3));
204# endif
205#endif /* POSIX or misc */
206
207/* Rewind DIRP to the beginning of the directory. */
208extern void rewinddir (DIR *__dirp) __THROW __nonnull ((1));
209
210#if defined __USE_MISC || defined __USE_XOPEN
211# include <bits/types.h>
212
213/* Seek to position POS on DIRP. */
214extern void seekdir (DIR *__dirp, long int __pos) __THROW __nonnull ((1));
215
216/* Return the current position of DIRP. */
217extern long int telldir (DIR *__dirp) __THROW __nonnull ((1));
218#endif
219
220#ifdef __USE_XOPEN2K8
221
222/* Return the file descriptor used by DIRP. */
223extern int dirfd (DIR *__dirp) __THROW __nonnull ((1));
224
225# if defined __OPTIMIZE__ && defined _DIR_dirfd
226# define dirfd(dirp) _DIR_dirfd (dirp)
227# endif
228
229# ifdef __USE_MISC
230# ifndef MAXNAMLEN
231/* Get the definitions of the POSIX.1 limits. */
232# include <bits/posix1_lim.h>
233
234/* `MAXNAMLEN' is the BSD name for what POSIX calls `NAME_MAX'. */
235# ifdef NAME_MAX
236# define MAXNAMLEN NAME_MAX
237# else
238# define MAXNAMLEN 255
239# endif
240# endif
241# endif
242
243# define __need_size_t
244# include <stddef.h>
245
246/* Scan the directory DIR, calling SELECTOR on each directory entry.
247 Entries for which SELECT returns nonzero are individually malloc'd,
248 sorted using qsort with CMP, and collected in a malloc'd array in
249 *NAMELIST. Returns the number of entries selected, or -1 on error.
250
251 This function is a cancellation point and therefore not marked with
252 __THROW. */
253# ifndef __USE_FILE_OFFSET64
254extern int scandir (const char *__restrict __dir,
255 struct dirent ***__restrict __namelist,
256 int (*__selector) (const struct dirent *),
257 int (*__cmp) (const struct dirent **,
258 const struct dirent **))
259 __nonnull ((1, 2));
260# else
261# ifdef __REDIRECT
262extern int __REDIRECT (scandir,
263 (const char *__restrict __dir,
264 struct dirent ***__restrict __namelist,
265 int (*__selector) (const struct dirent *),
266 int (*__cmp) (const struct dirent **,
267 const struct dirent **)),
268 scandir64) __nonnull ((1, 2));
269# else
270# define scandir scandir64
271# endif
272# endif
273
274# if defined __USE_GNU && defined __USE_LARGEFILE64
275/* This function is like `scandir' but it uses the 64bit dirent structure.
276 Please note that the CMP function must now work with struct dirent64 **. */
277extern int scandir64 (const char *__restrict __dir,
278 struct dirent64 ***__restrict __namelist,
279 int (*__selector) (const struct dirent64 *),
280 int (*__cmp) (const struct dirent64 **,
281 const struct dirent64 **))
282 __nonnull ((1, 2));
283# endif
284
285# ifdef __USE_GNU
286/* Similar to `scandir' but a relative DIR name is interpreted relative
287 to the directory for which DFD is a descriptor.
288
289 This function is a cancellation point and therefore not marked with
290 __THROW. */
291# ifndef __USE_FILE_OFFSET64
292extern int scandirat (int __dfd, const char *__restrict __dir,
293 struct dirent ***__restrict __namelist,
294 int (*__selector) (const struct dirent *),
295 int (*__cmp) (const struct dirent **,
296 const struct dirent **))
297 __nonnull ((2, 3));
298# else
299# ifdef __REDIRECT
300extern int __REDIRECT (scandirat,
301 (int __dfd, const char *__restrict __dir,
302 struct dirent ***__restrict __namelist,
303 int (*__selector) (const struct dirent *),
304 int (*__cmp) (const struct dirent **,
305 const struct dirent **)),
306 scandirat64) __nonnull ((2, 3));
307# else
308# define scandirat scandirat64
309# endif
310# endif
311
312/* This function is like `scandir' but it uses the 64bit dirent structure.
313 Please note that the CMP function must now work with struct dirent64 **. */
314extern int scandirat64 (int __dfd, const char *__restrict __dir,
315 struct dirent64 ***__restrict __namelist,
316 int (*__selector) (const struct dirent64 *),
317 int (*__cmp) (const struct dirent64 **,
318 const struct dirent64 **))
319 __nonnull ((2, 3));
320# endif
321
322/* Function to compare two `struct dirent's alphabetically. */
323# ifndef __USE_FILE_OFFSET64
324extern int alphasort (const struct dirent **__e1,
325 const struct dirent **__e2)
326 __THROW __attribute_pure__ __nonnull ((1, 2));
327# else
328# ifdef __REDIRECT
329extern int __REDIRECT_NTH (alphasort,
330 (const struct dirent **__e1,
331 const struct dirent **__e2),
332 alphasort64) __attribute_pure__ __nonnull ((1, 2));
333# else
334# define alphasort alphasort64
335# endif
336# endif
337
338# if defined __USE_GNU && defined __USE_LARGEFILE64
339extern int alphasort64 (const struct dirent64 **__e1,
340 const struct dirent64 **__e2)
341 __THROW __attribute_pure__ __nonnull ((1, 2));
342# endif
343#endif /* Use XPG7. */
344
345
346#ifdef __USE_MISC
347/* Read directory entries from FD into BUF, reading at most NBYTES.
348 Reading starts at offset *BASEP, and *BASEP is updated with the new
349 position after reading. Returns the number of bytes read; zero when at
350 end of directory; or -1 for errors. */
351# ifndef __USE_FILE_OFFSET64
352extern __ssize_t getdirentries (int __fd, char *__restrict __buf,
353 size_t __nbytes,
354 __off_t *__restrict __basep)
355 __THROW __nonnull ((2, 4));
356# else
357# ifdef __REDIRECT
358extern __ssize_t __REDIRECT_NTH (getdirentries,
359 (int __fd, char *__restrict __buf,
360 size_t __nbytes,
361 __off64_t *__restrict __basep),
362 getdirentries64) __nonnull ((2, 4));
363# else
364# define getdirentries getdirentries64
365# endif
366# endif
367
368# ifdef __USE_LARGEFILE64
369extern __ssize_t getdirentries64 (int __fd, char *__restrict __buf,
370 size_t __nbytes,
371 __off64_t *__restrict __basep)
372 __THROW __nonnull ((2, 4));
373# endif
374#endif /* Use misc. */
375
376#ifdef __USE_GNU
377/* Function to compare two `struct dirent's by name & version. */
378# ifndef __USE_FILE_OFFSET64
379extern int versionsort (const struct dirent **__e1,
380 const struct dirent **__e2)
381 __THROW __attribute_pure__ __nonnull ((1, 2));
382# else
383# ifdef __REDIRECT
384extern int __REDIRECT_NTH (versionsort,
385 (const struct dirent **__e1,
386 const struct dirent **__e2),
387 versionsort64)
388 __attribute_pure__ __nonnull ((1, 2));
389# else
390# define versionsort versionsort64
391# endif
392# endif
393
394# ifdef __USE_LARGEFILE64
395extern int versionsort64 (const struct dirent64 **__e1,
396 const struct dirent64 **__e2)
397 __THROW __attribute_pure__ __nonnull ((1, 2));
398# endif
399#endif /* Use GNU. */
400
401__END_DECLS
402
403#endif /* dirent.h */
404