include/dirent.h

   1 /* Copyright (C) 1991-2000,2003-2005,2009,2010 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
  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_BSD || 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_BSD
  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 /* 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.  */
 134 extern DIR *opendir (const char *__name) __nonnull ((1));
 135 libc_hidden_proto(opendir)
 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.  */
 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 libc_hidden_proto(closedir)
 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 libc_hidden_proto(readdir)
 166 #else
 167 # ifdef __REDIRECT
 168 extern struct dirent *__REDIRECT (readdir, (DIR *__dirp), readdir64)
 169      __nonnull ((1));
 170 # else
 171 #  define readdir readdir64
 172 # endif
 173 #endif
 174
 175 #ifdef __USE_LARGEFILE64
 176 extern struct dirent64 *readdir64 (DIR *__dirp) __nonnull ((1));
 177 libc_hidden_proto(readdir64)
 178 #endif
 179
 180 #if defined __USE_POSIX || defined __USE_MISC
 181 /* Reentrant version of `readdir'.  Return in RESULT a pointer to the
 182    next entry.
 183
 184    This function is a possible cancellation point and therefore not
 185    marked with __THROW.  */
 186 # ifndef __USE_FILE_OFFSET64
 187 extern int readdir_r (DIR *__restrict __dirp,
 188                       struct dirent *__restrict __entry,
 189                       struct dirent **__restrict __result)
 190      __nonnull ((1, 2, 3));
 191 libc_hidden_proto(readdir_r)
 192 # else
 193 #  ifdef __REDIRECT
 194 extern int __REDIRECT (readdir_r,
 195                        (DIR *__restrict __dirp,
 196                         struct dirent *__restrict __entry,
 197                         struct dirent **__restrict __result),
 198                        readdir64_r) __nonnull ((1, 2, 3));
 199 #  else
 200 #   define readdir_r readdir64_r
 201 #  endif
 202 # endif
 203
 204 # ifdef __USE_LARGEFILE64
 205 extern int readdir64_r (DIR *__restrict __dirp,
 206                         struct dirent64 *__restrict __entry,
 207                         struct dirent64 **__restrict __result)
 208      __nonnull ((1, 2, 3));
 209 libc_hidden_proto(readdir64_r)
 210 # endif
 211 #endif  /* POSIX or misc */
 212
 213 /* Rewind DIRP to the beginning of the directory.  */
 214 extern void rewinddir (DIR *__dirp) __THROW __nonnull ((1));
 215
 216 #if defined __USE_BSD || defined __USE_MISC || defined __USE_XOPEN
 217 # include <bits/types.h>
 218
 219 /* Seek to position POS on DIRP.  */
 220 extern void seekdir (DIR *__dirp, long int __pos) __THROW __nonnull ((1));
 221
 222 /* Return the current position of DIRP.  */
 223 extern long int telldir (DIR *__dirp) __THROW __nonnull ((1));
 224 #endif
 225
 226 #if defined __USE_BSD || defined __USE_MISC || defined __USE_XOPEN2K8
 227
 228 /* Return the file descriptor used by DIRP.  */
 229 extern int dirfd (DIR *__dirp) __THROW __nonnull ((1));
 230 libc_hidden_proto(dirfd)
 231
 232 # if 0 /* defined __OPTIMIZE__ && defined _DIR_dirfd */
 233 #  define dirfd(dirp)   _DIR_dirfd (dirp)
 234 # endif
 235
 236 # if defined __USE_BSD || defined __USE_MISC
 237 #  ifndef MAXNAMLEN
 238 /* Get the definitions of the POSIX.1 limits.  */
 239 #  include <bits/posix1_lim.h>
 240
 241 /* `MAXNAMLEN' is the BSD name for what POSIX calls `NAME_MAX'.  */
 242 #   ifdef NAME_MAX
 243 #    define MAXNAMLEN   NAME_MAX
 244 #   else
 245 #    define MAXNAMLEN   255
 246 #   endif
 247 #  endif
 248 # endif
 249
 250 # define __need_size_t
 251 # include <stddef.h>
 252
 253 /* Scan the directory DIR, calling SELECTOR on each directory entry.
 254    Entries for which SELECT returns nonzero are individually malloc'd,
 255    sorted using qsort with CMP, and collected in a malloc'd array in
 256    *NAMELIST.  Returns the number of entries selected, or -1 on error.  */
 257 # ifndef __USE_FILE_OFFSET64
 258 extern int scandir (const char *__restrict __dir,
 259                     struct dirent ***__restrict __namelist,
 260                     int (*__selector) (const struct dirent *),
 261                     int (*__cmp) (const struct dirent **,
 262                                   const struct dirent **))
 263      __nonnull ((1, 2));
 264 # else
 265 #  ifdef __REDIRECT
 266 extern int __REDIRECT (scandir,
 267                        (const char *__restrict __dir,
 268                         struct dirent ***__restrict __namelist,
 269                         int (*__selector) (const struct dirent *),
 270                         int (*__cmp) (const struct dirent **,
 271                                       const struct dirent **)),
 272                        scandir64) __nonnull ((1, 2));
 273 #  else
 274 #   define scandir scandir64
 275 #  endif
 276 # endif
 277
 278 # if defined __USE_GNU && defined __USE_LARGEFILE64
 279 /* This function is like `scandir' but it uses the 64bit dirent structure.
 280    Please note that the CMP function must now work with struct dirent64 **.  */
 281 extern int scandir64 (const char *__restrict __dir,
 282                       struct dirent64 ***__restrict __namelist,
 283                       int (*__selector) (const struct dirent64 *),
 284                       int (*__cmp) (const struct dirent64 **,
 285                                     const struct dirent64 **))
 286      __nonnull ((1, 2));
 287 # endif
 288
 289 /* Function to compare two `struct dirent's alphabetically.  */
 290 # ifndef __USE_FILE_OFFSET64
 291 extern int alphasort (const struct dirent **__e1,
 292                       const struct dirent **__e2)
 293      __THROW __attribute_pure__ __nonnull ((1, 2));
 294 # else
 295 #  ifdef __REDIRECT
 296 extern int __REDIRECT_NTH (alphasort,
 297                            (const struct dirent **__e1,
 298                             const struct dirent **__e2),
 299                            alphasort64) __attribute_pure__ __nonnull ((1, 2));
 300 #  else
 301 #   define alphasort alphasort64
 302 #  endif
 303 # endif
 304
 305 # if defined __USE_GNU && defined __USE_LARGEFILE64
 306 extern int alphasort64 (const struct dirent64 **__e1,
 307                         const struct dirent64 **__e2)
 308      __THROW __attribute_pure__ __nonnull ((1, 2));
 309 # endif
 310 #endif /* Use BSD or misc or XPG7.  */
 311
 312
 313 #if 0 /* defined __USE_BSD || defined __USE_MISC */
 314 /* Read directory entries from FD into BUF, reading at most NBYTES.
 315    Reading starts at offset *BASEP, and *BASEP is updated with the new
 316    position after reading.  Returns the number of bytes read; zero when at
 317    end of directory; or -1 for errors.  */
 318 # ifndef __USE_FILE_OFFSET64
 319 extern __ssize_t getdirentries (int __fd, char *__restrict __buf,
 320                                 size_t __nbytes,
 321                                 __off_t *__restrict __basep)
 322      __THROW __nonnull ((2, 4));
 323 # else
 324 #  ifdef __REDIRECT
 325 extern __ssize_t __REDIRECT_NTH (getdirentries,
 326                                  (int __fd, char *__restrict __buf,
 327                                   size_t __nbytes,
 328                                   __off64_t *__restrict __basep),
 329                                  getdirentries64) __nonnull ((2, 4));
 330 #  else
 331 #   define getdirentries getdirentries64
 332 #  endif
 333 # endif
 334
 335 # ifdef __USE_LARGEFILE64
 336 extern __ssize_t getdirentries64 (int __fd, char *__restrict __buf,
 337                                   size_t __nbytes,
 338                                   __off64_t *__restrict __basep)
 339      __THROW __nonnull ((2, 4));
 340 # endif
 341 #endif /* Use BSD or misc.  */
 342
 343 #ifdef __USE_GNU
 344 /* Function to compare two `struct dirent's by name & version.  */
 345 # ifndef __USE_FILE_OFFSET64
 346 extern int versionsort (const struct dirent **__e1,
 347                         const struct dirent **__e2)
 348      __THROW __attribute_pure__ __nonnull ((1, 2));
 349 # else
 350 #  ifdef __REDIRECT
 351 extern int __REDIRECT_NTH (versionsort,
 352                            (const struct dirent **__e1,
 353                             const struct dirent **__e2),
 354                            versionsort64)
 355      __attribute_pure__ __nonnull ((1, 2));
 356 #  else
 357 #   define versionsort versionsort64
 358 #  endif
 359 # endif
 360
 361 # ifdef __USE_LARGEFILE64
 362 extern int versionsort64 (const struct dirent64 **__e1,
 363                           const struct dirent64 **__e2)
 364      __THROW __attribute_pure__ __nonnull ((1, 2));
 365 # endif
 366 #endif /* Use GNU.  */
 367
 368 __END_DECLS
 369
 370 #ifdef _LIBC
 371 extern __ssize_t __getdents(int fd, char *buf, size_t count) attribute_hidden;
 372 extern __ssize_t __getdents64 (int fd, char *buf, size_t count) attribute_hidden;
 373 #endif
 374
 375 #endif /* dirent.h  */