ed4147dbcaacb0c7a7ba250889ecb600d67c3487
[kopensolaris-gnu/glibc.git] / dirent / dirent.h
1 /* Copyright (C) 1991-2000, 2003, 2004, 2005 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, write to the Free
16    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
17    02111-1307 USA.  */
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
35 typedef __ino_t ino_t;
36 #  else
37 typedef __ino64_t ino_t;
38 #  endif
39 #  define __ino_t_defined
40 # endif
41 # if defined __USE_LARGEFILE64 && !defined __ino64_t_defined
42 typedef __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'.  */
98 enum
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.  */
128 typedef 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.  */
135 extern DIR *opendir (__const char *__name) __nonnull ((1));
136
137 #ifdef __USE_GNU
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.  */
142 extern 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.  */
150 extern 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
163 extern struct dirent *readdir (DIR *__dirp) __nonnull ((1));
164 #else
165 # ifdef __REDIRECT
166 extern 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
174 extern 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
184 extern 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
190 extern 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
201 extern 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.  */
209 extern 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.  */
215 extern void seekdir (DIR *__dirp, long int __pos) __THROW __nonnull ((1));
216
217 /* Return the current position of DIRP.  */
218 extern long int telldir (DIR *__dirp) __THROW __nonnull ((1));
219 #endif
220
221 #if defined __USE_BSD || defined __USE_MISC
222
223 /* Return the file descriptor used by DIRP.  */
224 extern 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 # 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
242 # define __need_size_t
243 # include <stddef.h>
244
245 /* Scan the directory DIR, calling SELECTOR on each directory entry.
246    Entries for which SELECT returns nonzero are individually malloc'd,
247    sorted using qsort with CMP, and collected in a malloc'd array in
248    *NAMELIST.  Returns the number of entries selected, or -1 on error.  */
249 # ifndef __USE_FILE_OFFSET64
250 extern int scandir (__const char *__restrict __dir,
251                     struct dirent ***__restrict __namelist,
252                     int (*__selector) (__const struct dirent *),
253                     int (*__cmp) (__const void *, __const void *))
254      __nonnull ((1, 2));
255 # else
256 #  ifdef __REDIRECT
257 extern int __REDIRECT (scandir,
258                        (__const char *__restrict __dir,
259                         struct dirent ***__restrict __namelist,
260                         int (*__selector) (__const struct dirent *),
261                         int (*__cmp) (__const void *, __const void *)),
262                        scandir64) __nonnull ((1, 2));
263 #  else
264 #   define scandir scandir64
265 #  endif
266 # endif
267
268 # if defined __USE_GNU && defined __USE_LARGEFILE64
269 /* This function is like `scandir' but it uses the 64bit dirent structure.
270    Please note that the CMP function must now work with struct dirent64 **.  */
271 extern int scandir64 (__const char *__restrict __dir,
272                       struct dirent64 ***__restrict __namelist,
273                       int (*__selector) (__const struct dirent64 *),
274                       int (*__cmp) (__const void *, __const void *))
275      __nonnull ((1, 2));
276 # endif
277
278 /* Function to compare two `struct dirent's alphabetically.  */
279 # ifndef __USE_FILE_OFFSET64
280 extern int alphasort (__const void *__e1, __const void *__e2)
281      __THROW __attribute_pure__ __nonnull ((1, 2));
282 # else
283 #  ifdef __REDIRECT
284 extern int __REDIRECT_NTH (alphasort,
285                            (__const void *__e1, __const void *__e2),
286                            alphasort64) __attribute_pure__ __nonnull ((1, 2));
287 #  else
288 #   define alphasort alphasort64
289 #  endif
290 # endif
291
292 # if defined __USE_GNU && defined __USE_LARGEFILE64
293 extern int alphasort64 (__const void *__e1, __const void *__e2)
294      __THROW __attribute_pure__ __nonnull ((1, 2));
295 # endif
296
297 # ifdef __USE_GNU
298 /* Function to compare two `struct dirent's by name & version.  */
299 #  ifndef __USE_FILE_OFFSET64
300 extern int versionsort (__const void *__e1, __const void *__e2)
301      __THROW __attribute_pure__ __nonnull ((1, 2));
302 #  else
303 #   ifdef __REDIRECT
304 extern int __REDIRECT_NTH (versionsort,
305                            (__const void *__e1, __const void *__e2),
306                            versionsort64)
307      __attribute_pure__ __nonnull ((1, 2));
308 #   else
309 #    define versionsort versionsort64
310 #   endif
311 #  endif
312
313 #  ifdef __USE_LARGEFILE64
314 extern int versionsort64 (__const void *__e1, __const void *__e2)
315      __THROW __attribute_pure__ __nonnull ((1, 2));
316 #  endif
317 # endif
318
319 /* Read directory entries from FD into BUF, reading at most NBYTES.
320    Reading starts at offset *BASEP, and *BASEP is updated with the new
321    position after reading.  Returns the number of bytes read; zero when at
322    end of directory; or -1 for errors.  */
323 # ifndef __USE_FILE_OFFSET64
324 extern __ssize_t getdirentries (int __fd, char *__restrict __buf,
325                                 size_t __nbytes,
326                                 __off_t *__restrict __basep)
327      __THROW __nonnull ((2, 4));
328 # else
329 #  ifdef __REDIRECT
330 extern __ssize_t __REDIRECT_NTH (getdirentries,
331                                  (int __fd, char *__restrict __buf,
332                                   size_t __nbytes,
333                                   __off64_t *__restrict __basep),
334                                  getdirentries64) __nonnull ((2, 4));
335 #  else
336 #   define getdirentries getdirentries64
337 #  endif
338 # endif
339
340 # ifdef __USE_LARGEFILE64
341 extern __ssize_t getdirentries64 (int __fd, char *__restrict __buf,
342                                   size_t __nbytes,
343                                   __off64_t *__restrict __basep)
344      __THROW __nonnull ((2, 4));
345 # endif
346
347 #endif /* Use BSD or misc.  */
348
349 __END_DECLS
350
351 #endif /* dirent.h  */