dirent/dirent.h

   1 /* Copyright (C) 1991-2024 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    <https://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 /* Close the directory stream DIRP.
 130    Return 0 if successful, -1 if not.
 131
 132    This function is a possible cancellation point and therefore not
 133    marked with __THROW.  */
 134 extern int closedir (DIR *__dirp) __nonnull ((1));
 135
 136 /* Open a directory stream on NAME.
 137    Return a DIR stream on the directory, or NULL if it could not be opened.
 138
 139    This function is a possible cancellation point and therefore not
 140    marked with __THROW.  */
 141 extern DIR *opendir (const char *__name) __nonnull ((1))
 142         __attribute_malloc__ __attr_dealloc (closedir, 1);
 143
 144 #ifdef __USE_XOPEN2K8
 145 /* Same as opendir, but open the stream on the file descriptor FD.
 146
 147    This function is a possible cancellation point and therefore not
 148    marked with __THROW.  */
 149 extern DIR *fdopendir (int __fd)
 150         __attribute_malloc__ __attr_dealloc (closedir, 1);
 151 #endif
 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 #ifdef __USE_POSIX
 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)) __attribute_deprecated__;
 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)
 196   __nonnull ((1, 2, 3)) __attribute_deprecated__;
 197 #  else
 198 #   define readdir_r readdir64_r
 199 #  endif
 200 # endif
 201
 202 # ifdef __USE_LARGEFILE64
 203 extern int readdir64_r (DIR *__restrict __dirp,
 204                         struct dirent64 *__restrict __entry,
 205                         struct dirent64 **__restrict __result)
 206   __nonnull ((1, 2, 3)) __attribute_deprecated__;
 207 # endif
 208 #endif  /* POSIX or misc */
 209
 210 /* Rewind DIRP to the beginning of the directory.  */
 211 extern void rewinddir (DIR *__dirp) __THROW __nonnull ((1));
 212
 213 #if defined __USE_MISC || defined __USE_XOPEN
 214 # include <bits/types.h>
 215
 216 /* Seek to position POS on DIRP.  */
 217 extern void seekdir (DIR *__dirp, long int __pos) __THROW __nonnull ((1));
 218
 219 /* Return the current position of DIRP.  */
 220 extern long int telldir (DIR *__dirp) __THROW __nonnull ((1));
 221 #endif
 222
 223 #ifdef __USE_XOPEN2K8
 224
 225 /* Return the file descriptor used by DIRP.  */
 226 extern int dirfd (DIR *__dirp) __THROW __nonnull ((1));
 227
 228 # if defined __OPTIMIZE__ && defined _DIR_dirfd
 229 #  define dirfd(dirp)   _DIR_dirfd (dirp)
 230 # endif
 231
 232 # ifdef __USE_MISC
 233 #  ifndef MAXNAMLEN
 234 /* Get the definitions of the POSIX.1 limits.  */
 235 #  include <bits/posix1_lim.h>
 236
 237 /* `MAXNAMLEN' is the BSD name for what POSIX calls `NAME_MAX'.  */
 238 #   ifdef NAME_MAX
 239 #    define MAXNAMLEN   NAME_MAX
 240 #   else
 241 #    define MAXNAMLEN   255
 242 #   endif
 243 #  endif
 244 # endif
 245
 246 # define __need_size_t
 247 # include <stddef.h>
 248
 249 /* Scan the directory DIR, calling SELECTOR on each directory entry.
 250    Entries for which SELECT returns nonzero are individually malloc'd,
 251    sorted using qsort with CMP, and collected in a malloc'd array in
 252    *NAMELIST.  Returns the number of entries selected, or -1 on error.
 253
 254    This function is a cancellation point and therefore not marked with
 255    __THROW.  */
 256 # ifndef __USE_FILE_OFFSET64
 257 extern int scandir (const char *__restrict __dir,
 258                     struct dirent ***__restrict __namelist,
 259                     int (*__selector) (const struct dirent *),
 260                     int (*__cmp) (const struct dirent **,
 261                                   const struct dirent **))
 262      __nonnull ((1, 2));
 263 # else
 264 #  ifdef __REDIRECT
 265 extern int __REDIRECT (scandir,
 266                        (const char *__restrict __dir,
 267                         struct dirent ***__restrict __namelist,
 268                         int (*__selector) (const struct dirent *),
 269                         int (*__cmp) (const struct dirent **,
 270                                       const struct dirent **)),
 271                        scandir64) __nonnull ((1, 2));
 272 #  else
 273 #   define scandir scandir64
 274 #  endif
 275 # endif
 276
 277 # if defined __USE_GNU && defined __USE_LARGEFILE64
 278 /* This function is like `scandir' but it uses the 64bit dirent structure.
 279    Please note that the CMP function must now work with struct dirent64 **.  */
 280 extern int scandir64 (const char *__restrict __dir,
 281                       struct dirent64 ***__restrict __namelist,
 282                       int (*__selector) (const struct dirent64 *),
 283                       int (*__cmp) (const struct dirent64 **,
 284                                     const struct dirent64 **))
 285      __nonnull ((1, 2));
 286 # endif
 287
 288 # ifdef __USE_GNU
 289 /* Similar to `scandir' but a relative DIR name is interpreted relative
 290    to the directory for which DFD is a descriptor.
 291
 292    This function is a cancellation point and therefore not marked with
 293    __THROW.  */
 294 #  ifndef __USE_FILE_OFFSET64
 295 extern int scandirat (int __dfd, const char *__restrict __dir,
 296                       struct dirent ***__restrict __namelist,
 297                       int (*__selector) (const struct dirent *),
 298                       int (*__cmp) (const struct dirent **,
 299                                     const struct dirent **))
 300      __nonnull ((2, 3));
 301 #  else
 302 #   ifdef __REDIRECT
 303 extern int __REDIRECT (scandirat,
 304                        (int __dfd, const char *__restrict __dir,
 305                         struct dirent ***__restrict __namelist,
 306                         int (*__selector) (const struct dirent *),
 307                         int (*__cmp) (const struct dirent **,
 308                                       const struct dirent **)),
 309                        scandirat64) __nonnull ((2, 3));
 310 #   else
 311 #    define scandirat scandirat64
 312 #   endif
 313 #  endif
 314
 315 /* This function is like `scandir' but it uses the 64bit dirent structure.
 316    Please note that the CMP function must now work with struct dirent64 **.  */
 317 extern int scandirat64 (int __dfd, const char *__restrict __dir,
 318                         struct dirent64 ***__restrict __namelist,
 319                         int (*__selector) (const struct dirent64 *),
 320                         int (*__cmp) (const struct dirent64 **,
 321                                       const struct dirent64 **))
 322      __nonnull ((2, 3));
 323 # endif
 324
 325 /* Function to compare two `struct dirent's alphabetically.  */
 326 # ifndef __USE_FILE_OFFSET64
 327 extern int alphasort (const struct dirent **__e1,
 328                       const struct dirent **__e2)
 329      __THROW __attribute_pure__ __nonnull ((1, 2));
 330 # else
 331 #  ifdef __REDIRECT
 332 extern int __REDIRECT_NTH (alphasort,
 333                            (const struct dirent **__e1,
 334                             const struct dirent **__e2),
 335                            alphasort64) __attribute_pure__ __nonnull ((1, 2));
 336 #  else
 337 #   define alphasort alphasort64
 338 #  endif
 339 # endif
 340
 341 # if defined __USE_GNU && defined __USE_LARGEFILE64
 342 extern int alphasort64 (const struct dirent64 **__e1,
 343                         const struct dirent64 **__e2)
 344      __THROW __attribute_pure__ __nonnull ((1, 2));
 345 # endif
 346 #endif /* Use XPG7.  */
 347
 348
 349 #ifdef __USE_MISC
 350 /* Read directory entries from FD into BUF, reading at most NBYTES.
 351    Reading starts at offset *BASEP, and *BASEP is updated with the new
 352    position after reading.  Returns the number of bytes read; zero when at
 353    end of directory; or -1 for errors.  */
 354 # ifndef __USE_FILE_OFFSET64
 355 extern __ssize_t getdirentries (int __fd, char *__restrict __buf,
 356                                 size_t __nbytes,
 357                                 __off_t *__restrict __basep)
 358      __THROW __nonnull ((2, 4));
 359 # else
 360 #  ifdef __REDIRECT
 361 extern __ssize_t __REDIRECT_NTH (getdirentries,
 362                                  (int __fd, char *__restrict __buf,
 363                                   size_t __nbytes,
 364                                   __off64_t *__restrict __basep),
 365                                  getdirentries64) __nonnull ((2, 4));
 366 #  else
 367 #   define getdirentries getdirentries64
 368 #  endif
 369 # endif
 370
 371 # ifdef __USE_LARGEFILE64
 372 extern __ssize_t getdirentries64 (int __fd, char *__restrict __buf,
 373                                   size_t __nbytes,
 374                                   __off64_t *__restrict __basep)
 375      __THROW __nonnull ((2, 4));
 376 # endif
 377 #endif /* Use misc.  */
 378
 379 #ifdef __USE_GNU
 380 /* Function to compare two `struct dirent's by name & version.  */
 381 # ifndef __USE_FILE_OFFSET64
 382 extern int versionsort (const struct dirent **__e1,
 383                         const struct dirent **__e2)
 384      __THROW __attribute_pure__ __nonnull ((1, 2));
 385 # else
 386 #  ifdef __REDIRECT
 387 extern int __REDIRECT_NTH (versionsort,
 388                            (const struct dirent **__e1,
 389                             const struct dirent **__e2),
 390                            versionsort64)
 391      __attribute_pure__ __nonnull ((1, 2));
 392 #  else
 393 #   define versionsort versionsort64
 394 #  endif
 395 # endif
 396
 397 # ifdef __USE_LARGEFILE64
 398 extern int versionsort64 (const struct dirent64 **__e1,
 399                           const struct dirent64 **__e2)
 400      __THROW __attribute_pure__ __nonnull ((1, 2));
 401 # endif
 402 #endif /* Use GNU.  */
 403
 404 __END_DECLS
 405
 406 #include <bits/dirent_ext.h>
 407
 408 #endif /* dirent.h  */