dirent/dirent.h

   1 /* Copyright (C) 1991-2015 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_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_MISC
  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
 136 #ifdef __USE_XOPEN2K8
 137 /* Same as opendir, but open the stream on the file descriptor FD.
 138
 139    This function is a possible cancellation point and therefore not
 140    marked with __THROW.  */
 141 extern DIR *fdopendir (int __fd);
 142 #endif
 143
 144 /* Close the directory stream DIRP.
 145    Return 0 if successful, -1 if not.
 146
 147    This function is a possible cancellation point and therefore not
 148    marked with __THROW.  */
 149 extern int closedir (DIR *__dirp) __nonnull ((1));
 150
 151 /* Read a directory entry from DIRP.  Return a pointer to a `struct
 152    dirent' describing the entry, or NULL for EOF or error.  The
 153    storage returned may be overwritten by a later readdir call on the
 154    same DIR stream.
 155
 156    If the Large File Support API is selected we have to use the
 157    appropriate interface.
 158
 159    This function is a possible cancellation point and therefore not
 160    marked with __THROW.  */
 161 #ifndef __USE_FILE_OFFSET64
 162 extern struct dirent *readdir (DIR *__dirp) __nonnull ((1));
 163 #else
 164 # ifdef __REDIRECT
 165 extern struct dirent *__REDIRECT (readdir, (DIR *__dirp), readdir64)
 166      __nonnull ((1));
 167 # else
 168 #  define readdir readdir64
 169 # endif
 170 #endif
 171
 172 #ifdef __USE_LARGEFILE64
 173 extern struct dirent64 *readdir64 (DIR *__dirp) __nonnull ((1));
 174 #endif
 175
 176 #ifdef __USE_POSIX
 177 /* Reentrant version of `readdir'.  Return in RESULT a pointer to the
 178    next entry.
 179
 180    This function is a possible cancellation point and therefore not
 181    marked with __THROW.  */
 182 # ifndef __USE_FILE_OFFSET64
 183 extern int readdir_r (DIR *__restrict __dirp,
 184                       struct dirent *__restrict __entry,
 185                       struct dirent **__restrict __result)
 186      __nonnull ((1, 2, 3));
 187 # else
 188 #  ifdef __REDIRECT
 189 extern int __REDIRECT (readdir_r,
 190                        (DIR *__restrict __dirp,
 191                         struct dirent *__restrict __entry,
 192                         struct dirent **__restrict __result),
 193                        readdir64_r) __nonnull ((1, 2, 3));
 194 #  else
 195 #   define readdir_r readdir64_r
 196 #  endif
 197 # endif
 198
 199 # ifdef __USE_LARGEFILE64
 200 extern int readdir64_r (DIR *__restrict __dirp,
 201                         struct dirent64 *__restrict __entry,
 202                         struct dirent64 **__restrict __result)
 203      __nonnull ((1, 2, 3));
 204 # endif
 205 #endif  /* POSIX or misc */
 206
 207 /* Rewind DIRP to the beginning of the directory.  */
 208 extern void rewinddir (DIR *__dirp) __THROW __nonnull ((1));
 209
 210 #if defined __USE_MISC || defined __USE_XOPEN
 211 # include <bits/types.h>
 212
 213 /* Seek to position POS on DIRP.  */
 214 extern void seekdir (DIR *__dirp, long int __pos) __THROW __nonnull ((1));
 215
 216 /* Return the current position of DIRP.  */
 217 extern long int telldir (DIR *__dirp) __THROW __nonnull ((1));
 218 #endif
 219
 220 #ifdef __USE_XOPEN2K8
 221
 222 /* Return the file descriptor used by DIRP.  */
 223 extern int dirfd (DIR *__dirp) __THROW __nonnull ((1));
 224
 225 # if defined __OPTIMIZE__ && defined _DIR_dirfd
 226 #  define dirfd(dirp)   _DIR_dirfd (dirp)
 227 # endif
 228
 229 # ifdef __USE_MISC
 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 # endif
 242
 243 # define __need_size_t
 244 # include <stddef.h>
 245
 246 /* Scan the directory DIR, calling SELECTOR on each directory entry.
 247    Entries for which SELECT returns nonzero are individually malloc'd,
 248    sorted using qsort with CMP, and collected in a malloc'd array in
 249    *NAMELIST.  Returns the number of entries selected, or -1 on error.
 250
 251    This function is a cancellation point and therefore not marked with
 252    __THROW.  */
 253 # ifndef __USE_FILE_OFFSET64
 254 extern int scandir (const char *__restrict __dir,
 255                     struct dirent ***__restrict __namelist,
 256                     int (*__selector) (const struct dirent *),
 257                     int (*__cmp) (const struct dirent **,
 258                                   const struct dirent **))
 259      __nonnull ((1, 2));
 260 # else
 261 #  ifdef __REDIRECT
 262 extern int __REDIRECT (scandir,
 263                        (const char *__restrict __dir,
 264                         struct dirent ***__restrict __namelist,
 265                         int (*__selector) (const struct dirent *),
 266                         int (*__cmp) (const struct dirent **,
 267                                       const struct dirent **)),
 268                        scandir64) __nonnull ((1, 2));
 269 #  else
 270 #   define scandir scandir64
 271 #  endif
 272 # endif
 273
 274 # if defined __USE_GNU && defined __USE_LARGEFILE64
 275 /* This function is like `scandir' but it uses the 64bit dirent structure.
 276    Please note that the CMP function must now work with struct dirent64 **.  */
 277 extern int scandir64 (const char *__restrict __dir,
 278                       struct dirent64 ***__restrict __namelist,
 279                       int (*__selector) (const struct dirent64 *),
 280                       int (*__cmp) (const struct dirent64 **,
 281                                     const struct dirent64 **))
 282      __nonnull ((1, 2));
 283 # endif
 284
 285 # ifdef __USE_GNU
 286 /* Similar to `scandir' but a relative DIR name is interpreted relative
 287    to the directory for which DFD is a descriptor.
 288
 289    This function is a cancellation point and therefore not marked with
 290    __THROW.  */
 291 #  ifndef __USE_FILE_OFFSET64
 292 extern int scandirat (int __dfd, const char *__restrict __dir,
 293                       struct dirent ***__restrict __namelist,
 294                       int (*__selector) (const struct dirent *),
 295                       int (*__cmp) (const struct dirent **,
 296                                     const struct dirent **))
 297      __nonnull ((2, 3));
 298 #  else
 299 #   ifdef __REDIRECT
 300 extern int __REDIRECT (scandirat,
 301                        (int __dfd, const char *__restrict __dir,
 302                         struct dirent ***__restrict __namelist,
 303                         int (*__selector) (const struct dirent *),
 304                         int (*__cmp) (const struct dirent **,
 305                                       const struct dirent **)),
 306                        scandirat64) __nonnull ((2, 3));
 307 #   else
 308 #    define scandirat scandirat64
 309 #   endif
 310 #  endif
 311
 312 /* This function is like `scandir' but it uses the 64bit dirent structure.
 313    Please note that the CMP function must now work with struct dirent64 **.  */
 314 extern int scandirat64 (int __dfd, const char *__restrict __dir,
 315                         struct dirent64 ***__restrict __namelist,
 316                         int (*__selector) (const struct dirent64 *),
 317                         int (*__cmp) (const struct dirent64 **,
 318                                       const struct dirent64 **))
 319      __nonnull ((2, 3));
 320 # endif
 321
 322 /* Function to compare two `struct dirent's alphabetically.  */
 323 # ifndef __USE_FILE_OFFSET64
 324 extern int alphasort (const struct dirent **__e1,
 325                       const struct dirent **__e2)
 326      __THROW __attribute_pure__ __nonnull ((1, 2));
 327 # else
 328 #  ifdef __REDIRECT
 329 extern int __REDIRECT_NTH (alphasort,
 330                            (const struct dirent **__e1,
 331                             const struct dirent **__e2),
 332                            alphasort64) __attribute_pure__ __nonnull ((1, 2));
 333 #  else
 334 #   define alphasort alphasort64
 335 #  endif
 336 # endif
 337
 338 # if defined __USE_GNU && defined __USE_LARGEFILE64
 339 extern int alphasort64 (const struct dirent64 **__e1,
 340                         const struct dirent64 **__e2)
 341      __THROW __attribute_pure__ __nonnull ((1, 2));
 342 # endif
 343 #endif /* Use XPG7.  */
 344
 345
 346 #ifdef __USE_MISC
 347 /* Read directory entries from FD into BUF, reading at most NBYTES.
 348    Reading starts at offset *BASEP, and *BASEP is updated with the new
 349    position after reading.  Returns the number of bytes read; zero when at
 350    end of directory; or -1 for errors.  */
 351 # ifndef __USE_FILE_OFFSET64
 352 extern __ssize_t getdirentries (int __fd, char *__restrict __buf,
 353                                 size_t __nbytes,
 354                                 __off_t *__restrict __basep)
 355      __THROW __nonnull ((2, 4));
 356 # else
 357 #  ifdef __REDIRECT
 358 extern __ssize_t __REDIRECT_NTH (getdirentries,
 359                                  (int __fd, char *__restrict __buf,
 360                                   size_t __nbytes,
 361                                   __off64_t *__restrict __basep),
 362                                  getdirentries64) __nonnull ((2, 4));
 363 #  else
 364 #   define getdirentries getdirentries64
 365 #  endif
 366 # endif
 367
 368 # ifdef __USE_LARGEFILE64
 369 extern __ssize_t getdirentries64 (int __fd, char *__restrict __buf,
 370                                   size_t __nbytes,
 371                                   __off64_t *__restrict __basep)
 372      __THROW __nonnull ((2, 4));
 373 # endif
 374 #endif /* Use misc.  */
 375
 376 #ifdef __USE_GNU
 377 /* Function to compare two `struct dirent's by name & version.  */
 378 # ifndef __USE_FILE_OFFSET64
 379 extern int versionsort (const struct dirent **__e1,
 380                         const struct dirent **__e2)
 381      __THROW __attribute_pure__ __nonnull ((1, 2));
 382 # else
 383 #  ifdef __REDIRECT
 384 extern int __REDIRECT_NTH (versionsort,
 385                            (const struct dirent **__e1,
 386                             const struct dirent **__e2),
 387                            versionsort64)
 388      __attribute_pure__ __nonnull ((1, 2));
 389 #  else
 390 #   define versionsort versionsort64
 391 #  endif
 392 # endif
 393
 394 # ifdef __USE_LARGEFILE64
 395 extern int versionsort64 (const struct dirent64 **__e1,
 396                           const struct dirent64 **__e2)
 397      __THROW __attribute_pure__ __nonnull ((1, 2));
 398 # endif
 399 #endif /* Use GNU.  */
 400
 401 __END_DECLS
 402
 403 #endif /* dirent.h  */