Home | History | Annotate | Download | only in include
      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  */
    352