dirent/dirent.h

   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
  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_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
 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 || defined __USE_XOPEN2K8
 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 # 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
 255 extern 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
 263 extern 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 **.  */
 278 extern 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
 293 extern 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
 301 extern 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 **.  */
 315 extern 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
 325 extern int alphasort (const struct dirent **__e1,
 326                       const struct dirent **__e2)
 327      __THROW __attribute_pure__ __nonnull ((1, 2));
 328 # else
 329 #  ifdef __REDIRECT
 330 extern 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
 340 extern 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
 353 extern __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
 359 extern __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
 370 extern __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
 380 extern int versionsort (const struct dirent **__e1,
 381                         const struct dirent **__e2)
 382      __THROW __attribute_pure__ __nonnull ((1, 2));
 383 # else
 384 #  ifdef __REDIRECT
 385 extern 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
 396 extern 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  */