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