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, write to the Free
  17    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  18    02111-1307 USA.  */
  19
  20 /*
  21  *      POSIX Standard: 5.1.2 Directory Operations      <dirent.h>
  22  */
  23
  24 #ifndef _DIRENT_H
  25 #define _DIRENT_H       1
  26
  27 #include <features.h>
  28
  29 __BEGIN_DECLS
  30
  31 #include <bits/types.h>
  32
  33 #ifdef __USE_XOPEN
  34 # ifndef __ino_t_defined
  35 #  ifndef __USE_FILE_OFFSET64
  36 typedef __ino_t ino_t;
  37 #  else
  38 typedef __ino64_t ino_t;
  39 #  endif
  40 #  define __ino_t_defined
  41 # endif
  42 # if defined __USE_LARGEFILE64 && !defined __ino64_t_defined
  43 typedef __ino64_t ino64_t;
  44 #  define __ino64_t_defined
  45 # endif
  46 #endif
  47
  48 /* This file defines `struct dirent'.
  49
  50    It defines the macro `_DIRENT_HAVE_D_NAMLEN' iff there is a `d_namlen'
  51    member that gives the length of `d_name'.
  52
  53    It defines the macro `_DIRENT_HAVE_D_RECLEN' iff there is a `d_reclen'
  54    member that gives the size of the entire directory entry.
  55
  56    It defines the macro `_DIRENT_HAVE_D_OFF' iff there is a `d_off'
  57    member that gives the file offset of the next directory entry.
  58
  59    It defines the macro `_DIRENT_HAVE_D_TYPE' iff there is a `d_type'
  60    member that gives the type of the file.
  61  */
  62
  63 #include <bits/dirent.h>
  64
  65 #if (defined __USE_BSD || defined __USE_MISC) && !defined d_fileno
  66 # define d_ino  d_fileno                 /* Backward compatibility.  */
  67 #endif
  68
  69 /* These macros extract size information from a `struct dirent *'.
  70    They may evaluate their argument multiple times, so it must not
  71    have side effects.  Each of these may involve a relatively costly
  72    call to `strlen' on some systems, so these values should be cached.
  73
  74    _D_EXACT_NAMLEN (DP) returns the length of DP->d_name, not including
  75    its terminating null character.
  76
  77    _D_ALLOC_NAMLEN (DP) returns a size at least (_D_EXACT_NAMLEN (DP) + 1);
  78    that is, the allocation size needed to hold the DP->d_name string.
  79    Use this macro when you don't need the exact length, just an upper bound.
  80    This macro is less likely to require calling `strlen' than _D_EXACT_NAMLEN.
  81    */
  82
  83 #ifdef _DIRENT_HAVE_D_NAMLEN
  84 # define _D_EXACT_NAMLEN(d) ((d)->d_namlen)
  85 # define _D_ALLOC_NAMLEN(d) (_D_EXACT_NAMLEN (d) + 1)
  86 #else
  87 # define _D_EXACT_NAMLEN(d) (strlen ((d)->d_name))
  88 # ifdef _DIRENT_HAVE_D_RECLEN
  89 #  define _D_ALLOC_NAMLEN(d) (((char *) (d) + (d)->d_reclen) - &(d)->d_name[0])
  90 # else
  91 #  define _D_ALLOC_NAMLEN(d) (sizeof (d)->d_name > 1 ? sizeof (d)->d_name : \
  92                               _D_EXACT_NAMLEN (d) + 1)
  93 # endif
  94 #endif
  95
  96
  97 #ifdef __USE_BSD
  98 /* File types for `d_type'.  */
  99 enum
 100   {
 101     DT_UNKNOWN = 0,
 102 # define DT_UNKNOWN     DT_UNKNOWN
 103     DT_FIFO = 1,
 104 # define DT_FIFO        DT_FIFO
 105     DT_CHR = 2,
 106 # define DT_CHR         DT_CHR
 107     DT_DIR = 4,
 108 # define DT_DIR         DT_DIR
 109     DT_BLK = 6,
 110 # define DT_BLK         DT_BLK
 111     DT_REG = 8,
 112 # define DT_REG         DT_REG
 113     DT_LNK = 10,
 114 # define DT_LNK         DT_LNK
 115     DT_SOCK = 12,
 116 # define DT_SOCK        DT_SOCK
 117     DT_WHT = 14
 118 # define DT_WHT         DT_WHT
 119   };
 120
 121 /* Convert between stat structure types and directory types.  */
 122 # define IFTODT(mode)   (((mode) & 0170000) >> 12)
 123 # define DTTOIF(dirtype)        ((dirtype) << 12)
 124 #endif
 125
 126
 127 /* This is the data type of directory stream objects.
 128    The actual structure is opaque to users.  */
 129 typedef struct __dirstream DIR;
 130
 131 /* Open a directory stream on NAME.
 132    Return a DIR stream on the directory, or NULL if it could not be opened.
 133
 134    This function is a possible cancellation point and therefore not
 135    marked with __THROW.  */
 136 extern DIR *opendir (const char *__name) __nonnull ((1));
 137
 138 #ifdef __USE_XOPEN2K8
 139 /* Same as opendir, but open the stream on the file descriptor FD.
 140
 141    This function is a possible cancellation point and therefore not
 142    marked with __THROW.  */
 143 extern DIR *fdopendir (int __fd);
 144 #endif
 145
 146 /* Close the directory stream DIRP.
 147    Return 0 if successful, -1 if not.
 148
 149    This function is a possible cancellation point and therefore not
 150    marked with __THROW.  */
 151 extern int closedir (DIR *__dirp) __nonnull ((1));
 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 #else
 166 # ifdef __REDIRECT
 167 extern struct dirent *__REDIRECT (readdir, (DIR *__dirp), readdir64)
 168      __nonnull ((1));
 169 # else
 170 #  define readdir readdir64
 171 # endif
 172 #endif
 173
 174 #ifdef __USE_LARGEFILE64
 175 extern struct dirent64 *readdir64 (DIR *__dirp) __nonnull ((1));
 176 #endif
 177
 178 #if defined __USE_POSIX || defined __USE_MISC
 179 /* Reentrant version of `readdir'.  Return in RESULT a pointer to the
 180    next entry.
 181
 182    This function is a possible cancellation point and therefore not
 183    marked with __THROW.  */
 184 # ifndef __USE_FILE_OFFSET64
 185 extern int readdir_r (DIR *__restrict __dirp,
 186                       struct dirent *__restrict __entry,
 187                       struct dirent **__restrict __result)
 188      __nonnull ((1, 2, 3));
 189 # else
 190 #  ifdef __REDIRECT
 191 extern int __REDIRECT (readdir_r,
 192                        (DIR *__restrict __dirp,
 193                         struct dirent *__restrict __entry,
 194                         struct dirent **__restrict __result),
 195                        readdir64_r) __nonnull ((1, 2, 3));
 196 #  else
 197 #   define readdir_r readdir64_r
 198 #  endif
 199 # endif
 200
 201 # ifdef __USE_LARGEFILE64
 202 extern int readdir64_r (DIR *__restrict __dirp,
 203                         struct dirent64 *__restrict __entry,
 204                         struct dirent64 **__restrict __result)
 205      __nonnull ((1, 2, 3));
 206 # endif
 207 #endif  /* POSIX or misc */
 208
 209 /* Rewind DIRP to the beginning of the directory.  */
 210 extern void rewinddir (DIR *__dirp) __THROW __nonnull ((1));
 211
 212 #if defined __USE_BSD || defined __USE_MISC || defined __USE_XOPEN
 213 # include <bits/types.h>
 214
 215 /* Seek to position POS on DIRP.  */
 216 extern void seekdir (DIR *__dirp, long int __pos) __THROW __nonnull ((1));
 217
 218 /* Return the current position of DIRP.  */
 219 extern long int telldir (DIR *__dirp) __THROW __nonnull ((1));
 220 #endif
 221
 222 #if defined __USE_BSD || defined __USE_MISC || defined __USE_XOPEN2K8
 223
 224 /* Return the file descriptor used by DIRP.  */
 225 extern int dirfd (DIR *__dirp) __THROW __nonnull ((1));
 226
 227 # if defined __OPTIMIZE__ && defined _DIR_dirfd
 228 #  define dirfd(dirp)   _DIR_dirfd (dirp)
 229 # endif
 230
 231 # if defined __USE_BSD || defined __USE_MISC
 232 #  ifndef MAXNAMLEN
 233 /* Get the definitions of the POSIX.1 limits.  */
 234 #  include <bits/posix1_lim.h>
 235
 236 /* `MAXNAMLEN' is the BSD name for what POSIX calls `NAME_MAX'.  */
 237 #   ifdef NAME_MAX
 238 #    define MAXNAMLEN   NAME_MAX
 239 #   else
 240 #    define MAXNAMLEN   255
 241 #   endif
 242 #  endif
 243 # endif
 244
 245 # define __need_size_t
 246 # include <stddef.h>
 247
 248 /* Scan the directory DIR, calling SELECTOR on each directory entry.
 249    Entries for which SELECT returns nonzero are individually malloc'd,
 250    sorted using qsort with CMP, and collected in a malloc'd array in
 251    *NAMELIST.  Returns the number of entries selected, or -1 on error.
 252
 253    This function is a cancellation point and therefore not marked with
 254    __THROW.  */
 255 # ifndef __USE_FILE_OFFSET64
 256 extern int scandir (const char *__restrict __dir,
 257                     struct dirent ***__restrict __namelist,
 258                     int (*__selector) (const struct dirent *),
 259                     int (*__cmp) (const struct dirent **,
 260                                   const struct dirent **))
 261      __nonnull ((1, 2));
 262 # else
 263 #  ifdef __REDIRECT
 264 extern int __REDIRECT (scandir,
 265                        (const char *__restrict __dir,
 266                         struct dirent ***__restrict __namelist,
 267                         int (*__selector) (const struct dirent *),
 268                         int (*__cmp) (const struct dirent **,
 269                                       const struct dirent **)),
 270                        scandir64) __nonnull ((1, 2));
 271 #  else
 272 #   define scandir scandir64
 273 #  endif
 274 # endif
 275
 276 # if defined __USE_GNU && defined __USE_LARGEFILE64
 277 /* This function is like `scandir' but it uses the 64bit dirent structure.
 278    Please note that the CMP function must now work with struct dirent64 **.  */
 279 extern int scandir64 (const char *__restrict __dir,
 280                       struct dirent64 ***__restrict __namelist,
 281                       int (*__selector) (const struct dirent64 *),
 282                       int (*__cmp) (const struct dirent64 **,
 283                                     const struct dirent64 **))
 284      __nonnull ((1, 2));
 285 # endif
 286
 287 # ifdef __USE_GNU
 288 /* Similar to `scandir' but a relative DIR name is interpreted relative
 289    to the directory for which DFD is a descriptor.
 290
 291    This function is a cancellation point and therefore not marked with
 292    __THROW.  */
 293 #  ifndef __USE_FILE_OFFSET64
 294 extern int scandirat (int __dfd, const char *__restrict __dir,
 295                       struct dirent ***__restrict __namelist,
 296                       int (*__selector) (const struct dirent *),
 297                       int (*__cmp) (const struct dirent **,
 298                                     const struct dirent **))
 299      __nonnull ((2, 3));
 300 #  else
 301 #   ifdef __REDIRECT
 302 extern int __REDIRECT (scandirat,
 303                        (int __dfd, const char *__restrict __dir,
 304                         struct dirent ***__restrict __namelist,
 305                         int (*__selector) (const struct dirent *),
 306                         int (*__cmp) (const struct dirent **,
 307                                       const struct dirent **)),
 308                        scandirat64) __nonnull ((2, 3));
 309 #   else
 310 #    define scandirat scandirat64
 311 #   endif
 312 #  endif
 313
 314 /* This function is like `scandir' but it uses the 64bit dirent structure.
 315    Please note that the CMP function must now work with struct dirent64 **.  */
 316 extern int scandirat64 (int __dfd, const char *__restrict __dir,
 317                         struct dirent64 ***__restrict __namelist,
 318                         int (*__selector) (const struct dirent64 *),
 319                         int (*__cmp) (const struct dirent64 **,
 320                                       const struct dirent64 **))
 321      __nonnull ((2, 3));
 322 # endif
 323
 324 /* Function to compare two `struct dirent's alphabetically.  */
 325 # ifndef __USE_FILE_OFFSET64
 326 extern int alphasort (const struct dirent **__e1,
 327                       const struct dirent **__e2)
 328      __THROW __attribute_pure__ __nonnull ((1, 2));
 329 # else
 330 #  ifdef __REDIRECT
 331 extern int __REDIRECT_NTH (alphasort,
 332                            (const struct dirent **__e1,
 333                             const struct dirent **__e2),
 334                            alphasort64) __attribute_pure__ __nonnull ((1, 2));
 335 #  else
 336 #   define alphasort alphasort64
 337 #  endif
 338 # endif
 339
 340 # if defined __USE_GNU && defined __USE_LARGEFILE64
 341 extern int alphasort64 (const struct dirent64 **__e1,
 342                         const struct dirent64 **__e2)
 343      __THROW __attribute_pure__ __nonnull ((1, 2));
 344 # endif
 345 #endif /* Use BSD or misc or XPG7.  */
 346
 347
 348 #if defined __USE_BSD || defined __USE_MISC
 349 /* Read directory entries from FD into BUF, reading at most NBYTES.
 350    Reading starts at offset *BASEP, and *BASEP is updated with the new
 351    position after reading.  Returns the number of bytes read; zero when at
 352    end of directory; or -1 for errors.  */
 353 # ifndef __USE_FILE_OFFSET64
 354 extern __ssize_t getdirentries (int __fd, char *__restrict __buf,
 355                                 size_t __nbytes,
 356                                 __off_t *__restrict __basep)
 357      __THROW __nonnull ((2, 4));
 358 # else
 359 #  ifdef __REDIRECT
 360 extern __ssize_t __REDIRECT_NTH (getdirentries,
 361                                  (int __fd, char *__restrict __buf,
 362                                   size_t __nbytes,
 363                                   __off64_t *__restrict __basep),
 364                                  getdirentries64) __nonnull ((2, 4));
 365 #  else
 366 #   define getdirentries getdirentries64
 367 #  endif
 368 # endif
 369
 370 # ifdef __USE_LARGEFILE64
 371 extern __ssize_t getdirentries64 (int __fd, char *__restrict __buf,
 372                                   size_t __nbytes,
 373                                   __off64_t *__restrict __basep)
 374      __THROW __nonnull ((2, 4));
 375 # endif
 376 #endif /* Use BSD or misc.  */
 377
 378 #ifdef __USE_GNU
 379 /* Function to compare two `struct dirent's by name & version.  */
 380 # ifndef __USE_FILE_OFFSET64
 381 extern int versionsort (const struct dirent **__e1,
 382                         const struct dirent **__e2)
 383      __THROW __attribute_pure__ __nonnull ((1, 2));
 384 # else
 385 #  ifdef __REDIRECT
 386 extern int __REDIRECT_NTH (versionsort,
 387                            (const struct dirent **__e1,
 388                             const struct dirent **__e2),
 389                            versionsort64)
 390      __attribute_pure__ __nonnull ((1, 2));
 391 #  else
 392 #   define versionsort versionsort64
 393 #  endif
 394 # endif
 395
 396 # ifdef __USE_LARGEFILE64
 397 extern int versionsort64 (const struct dirent64 **__e1,
 398                           const struct dirent64 **__e2)
 399      __THROW __attribute_pure__ __nonnull ((1, 2));
 400 # endif
 401 #endif /* Use GNU.  */
 402
 403 __END_DECLS
 404
 405 #endif /* dirent.h  */