include/dirent.h

   1 /* Copyright (C) 1991-2000, 2003, 2004 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, write to the Free
  16    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  17    02111-1307 USA.  */
  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 libc_hidden_proto(opendir)
 137
 138 /* Close the directory stream DIRP.
 139    Return 0 if successful, -1 if not.
 140
 141    This function is a possible cancellation point and therefore not
 142    marked with __THROW.  */
 143 extern int closedir (DIR *__dirp) __nonnull ((1));
 144 libc_hidden_proto(closedir)
 145
 146 /* Read a directory entry from DIRP.  Return a pointer to a `struct
 147    dirent' describing the entry, or NULL for EOF or error.  The
 148    storage returned may be overwritten by a later readdir call on the
 149    same DIR stream.
 150
 151    If the Large File Support API is selected we have to use the
 152    appropriate interface.
 153
 154    This function is a possible cancellation point and therefore not
 155    marked with __THROW.  */
 156 #ifndef __USE_FILE_OFFSET64
 157 extern struct dirent *readdir (DIR *__dirp) __nonnull ((1));
 158 libc_hidden_proto(readdir)
 159 #else
 160 # ifdef __REDIRECT
 161 extern struct dirent *__REDIRECT (readdir, (DIR *__dirp), readdir64)
 162      __nonnull ((1));
 163 # else
 164 #  define readdir readdir64
 165 # endif
 166 #endif
 167
 168 #ifdef __USE_LARGEFILE64
 169 extern struct dirent64 *readdir64 (DIR *__dirp) __nonnull ((1));
 170 libc_hidden_proto(readdir64)
 171 #endif
 172
 173 #if defined __USE_POSIX || defined __USE_MISC
 174 /* Reentrant version of `readdir'.  Return in RESULT a pointer to the
 175    next entry.
 176
 177    This function is a possible cancellation point and therefore not
 178    marked with __THROW.  */
 179 # ifndef __USE_FILE_OFFSET64
 180 extern int readdir_r (DIR *__restrict __dirp,
 181                       struct dirent *__restrict __entry,
 182                       struct dirent **__restrict __result)
 183      __nonnull ((1, 2, 3));
 184 libc_hidden_proto(readdir_r)
 185 # else
 186 #  ifdef __REDIRECT
 187 extern int __REDIRECT (readdir_r,
 188                        (DIR *__restrict __dirp,
 189                         struct dirent *__restrict __entry,
 190                         struct dirent **__restrict __result),
 191                        readdir64_r) __nonnull ((1, 2, 3));
 192 #  else
 193 #   define readdir_r readdir64_r
 194 #  endif
 195 # endif
 196
 197 # ifdef __USE_LARGEFILE64
 198 extern int readdir64_r (DIR *__restrict __dirp,
 199                         struct dirent64 *__restrict __entry,
 200                         struct dirent64 **__restrict __result)
 201      __nonnull ((1, 2, 3));
 202 libc_hidden_proto(readdir64_r)
 203 # endif
 204 #endif  /* POSIX or misc */
 205
 206 /* Rewind DIRP to the beginning of the directory.  */
 207 extern void rewinddir (DIR *__dirp) __THROW __nonnull ((1));
 208
 209 #if defined __USE_BSD || defined __USE_MISC || defined __USE_XOPEN
 210 # include <bits/types.h>
 211
 212 /* Seek to position POS on DIRP.  */
 213 extern void seekdir (DIR *__dirp, long int __pos) __THROW __nonnull ((1));
 214
 215 /* Return the current position of DIRP.  */
 216 extern long int telldir (DIR *__dirp) __THROW __nonnull ((1));
 217 #endif
 218
 219 #if defined __USE_BSD || defined __USE_MISC
 220
 221 /* Return the file descriptor used by DIRP.  */
 222 extern int dirfd (DIR *__dirp) __THROW __nonnull ((1));
 223 libc_hidden_proto(dirfd)
 224
 225 # if 0 /* defined __OPTIMIZE__ && defined _DIR_dirfd */
 226 #  define dirfd(dirp)   _DIR_dirfd (dirp)
 227 # endif
 228
 229 # ifndef MAXNAMLEN
 230 /* Get the definitions of the POSIX.1 limits.  */
 231 #  include <bits/posix1_lim.h>
 232
 233 /* `MAXNAMLEN' is the BSD name for what POSIX calls `NAME_MAX'.  */
 234 #  ifdef NAME_MAX
 235 #   define MAXNAMLEN    NAME_MAX
 236 #  else
 237 #   define MAXNAMLEN    255
 238 #  endif
 239 # endif
 240
 241 # define __need_size_t
 242 # include <stddef.h>
 243
 244 /* Scan the directory DIR, calling SELECTOR on each directory entry.
 245    Entries for which SELECT returns nonzero are individually malloc'd,
 246    sorted using qsort with CMP, and collected in a malloc'd array in
 247    *NAMELIST.  Returns the number of entries selected, or -1 on error.  */
 248 # ifndef __USE_FILE_OFFSET64
 249 extern int scandir (__const char *__restrict __dir,
 250                     struct dirent ***__restrict __namelist,
 251                     int (*__selector) (__const struct dirent *),
 252                     int (*__cmp) (__const void *, __const void *))
 253      __nonnull ((1, 2));
 254 # else
 255 #  ifdef __REDIRECT
 256 extern int __REDIRECT (scandir,
 257                        (__const char *__restrict __dir,
 258                         struct dirent ***__restrict __namelist,
 259                         int (*__selector) (__const struct dirent *),
 260                         int (*__cmp) (__const void *, __const void *)),
 261                        scandir64) __nonnull ((1, 2));
 262 #  else
 263 #   define scandir scandir64
 264 #  endif
 265 # endif
 266
 267 # if defined __USE_GNU && defined __USE_LARGEFILE64
 268 /* This function is like `scandir' but it uses the 64bit dirent structure.
 269    Please note that the CMP function must now work with struct dirent64 **.  */
 270 extern int scandir64 (__const char *__restrict __dir,
 271                       struct dirent64 ***__restrict __namelist,
 272                       int (*__selector) (__const struct dirent64 *),
 273                       int (*__cmp) (__const void *, __const void *))
 274      __nonnull ((1, 2));
 275 # endif
 276
 277 /* Function to compare two `struct dirent's alphabetically.  */
 278 # ifndef __USE_FILE_OFFSET64
 279 extern int alphasort (__const void *__e1, __const void *__e2)
 280      __THROW __attribute_pure__ __nonnull ((1, 2));
 281 # else
 282 #  ifdef __REDIRECT
 283 extern int __REDIRECT (alphasort,
 284                            (__const void *__e1, __const void *__e2),
 285                            alphasort64) __attribute_pure__ __nonnull ((1, 2));
 286 #  else
 287 #   define alphasort alphasort64
 288 #  endif
 289 # endif
 290
 291 # if defined __USE_GNU && defined __USE_LARGEFILE64
 292 extern int alphasort64 (__const void *__e1, __const void *__e2)
 293      __THROW __attribute_pure__ __nonnull ((1, 2));
 294 # endif
 295
 296 /* Function to compare two `struct dirent's alphabetically.  */
 297 # ifndef __USE_FILE_OFFSET64
 298 extern int versionsort (__const void *__e1, __const void *__e2)
 299      __THROW __attribute_pure__ __nonnull ((1, 2));
 300 # else
 301 #  ifdef __REDIRECT
 302 extern int __REDIRECT (versionsort,
 303                            (__const void *__e1, __const void *__e2),
 304                            versionsort64) __attribute_pure__ __nonnull ((1, 2));
 305 #  else
 306 #   define versionsort versionsort64
 307 #  endif
 308 # endif
 309
 310 # if defined __USE_GNU && defined __USE_LARGEFILE64
 311 extern int versionsort64 (__const void *__e1, __const void *__e2)
 312      __THROW __attribute_pure__ __nonnull ((1, 2));
 313 # endif
 314
 315 #endif /* Use BSD or misc.  */
 316
 317 __END_DECLS
 318
 319 #endif /* dirent.h  */