Back to index

glibc  2.9
dirent.h
Go to the documentation of this file.
00001 /* Copyright (C) 1991-2000, 2003, 2004, 2005 Free Software Foundation, Inc.
00002    This file is part of the GNU C Library.
00003 
00004    The GNU C Library is free software; you can redistribute it and/or
00005    modify it under the terms of the GNU Lesser General Public
00006    License as published by the Free Software Foundation; either
00007    version 2.1 of the License, or (at your option) any later version.
00008 
00009    The GNU C Library is distributed in the hope that it will be useful,
00010    but WITHOUT ANY WARRANTY; without even the implied warranty of
00011    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00012    Lesser General Public License for more details.
00013 
00014    You should have received a copy of the GNU Lesser General Public
00015    License along with the GNU C Library; if not, write to the Free
00016    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
00017    02111-1307 USA.  */
00018 
00019 /*
00020  *     POSIX Standard: 5.1.2 Directory Operations       <dirent.h>
00021  */
00022 
00023 #ifndef       _DIRENT_H
00024 #define       _DIRENT_H     1
00025 
00026 #include <features.h>
00027 
00028 __BEGIN_DECLS
00029 
00030 #include <bits/types.h>
00031 
00032 #ifdef __USE_XOPEN
00033 # ifndef __ino_t_defined
00034 #  ifndef __USE_FILE_OFFSET64
00035 typedef __ino_t ino_t;
00036 #  else
00037 typedef __ino64_t ino_t;
00038 #  endif
00039 #  define __ino_t_defined
00040 # endif
00041 # if defined __USE_LARGEFILE64 && !defined __ino64_t_defined
00042 typedef __ino64_t ino64_t;
00043 #  define __ino64_t_defined
00044 # endif
00045 #endif
00046 
00047 /* This file defines `struct dirent'.
00048 
00049    It defines the macro `_DIRENT_HAVE_D_NAMLEN' iff there is a `d_namlen'
00050    member that gives the length of `d_name'.
00051 
00052    It defines the macro `_DIRENT_HAVE_D_RECLEN' iff there is a `d_reclen'
00053    member that gives the size of the entire directory entry.
00054 
00055    It defines the macro `_DIRENT_HAVE_D_OFF' iff there is a `d_off'
00056    member that gives the file offset of the next directory entry.
00057 
00058    It defines the macro `_DIRENT_HAVE_D_TYPE' iff there is a `d_type'
00059    member that gives the type of the file.
00060  */
00061 
00062 #include <bits/dirent.h>
00063 
00064 #if (defined __USE_BSD || defined __USE_MISC) && !defined d_fileno
00065 # define d_ino       d_fileno              /* Backward compatibility.  */
00066 #endif
00067 
00068 /* These macros extract size information from a `struct dirent *'.
00069    They may evaluate their argument multiple times, so it must not
00070    have side effects.  Each of these may involve a relatively costly
00071    call to `strlen' on some systems, so these values should be cached.
00072 
00073    _D_EXACT_NAMLEN (DP)     returns the length of DP->d_name, not including
00074    its terminating null character.
00075 
00076    _D_ALLOC_NAMLEN (DP)     returns a size at least (_D_EXACT_NAMLEN (DP) + 1);
00077    that is, the allocation size needed to hold the DP->d_name string.
00078    Use this macro when you don't need the exact length, just an upper bound.
00079    This macro is less likely to require calling `strlen' than _D_EXACT_NAMLEN.
00080    */
00081 
00082 #ifdef _DIRENT_HAVE_D_NAMLEN
00083 # define _D_EXACT_NAMLEN(d) ((d)->d_namlen)
00084 # define _D_ALLOC_NAMLEN(d) (_D_EXACT_NAMLEN (d) + 1)
00085 #else
00086 # define _D_EXACT_NAMLEN(d) (strlen ((d)->d_name))
00087 # ifdef _DIRENT_HAVE_D_RECLEN
00088 #  define _D_ALLOC_NAMLEN(d) (((char *) (d) + (d)->d_reclen) - &(d)->d_name[0])
00089 # else
00090 #  define _D_ALLOC_NAMLEN(d) (sizeof (d)->d_name > 1 ? sizeof (d)->d_name : \
00091                            _D_EXACT_NAMLEN (d) + 1)
00092 # endif
00093 #endif
00094 
00095 
00096 #ifdef __USE_BSD
00097 /* File types for `d_type'.  */
00098 enum
00099   {
00100     DT_UNKNOWN = 0,
00101 # define DT_UNKNOWN  DT_UNKNOWN
00102     DT_FIFO = 1,
00103 # define DT_FIFO     DT_FIFO
00104     DT_CHR = 2,
00105 # define DT_CHR             DT_CHR
00106     DT_DIR = 4,
00107 # define DT_DIR             DT_DIR
00108     DT_BLK = 6,
00109 # define DT_BLK             DT_BLK
00110     DT_REG = 8,
00111 # define DT_REG             DT_REG
00112     DT_LNK = 10,
00113 # define DT_LNK             DT_LNK
00114     DT_SOCK = 12,
00115 # define DT_SOCK     DT_SOCK
00116     DT_WHT = 14
00117 # define DT_WHT             DT_WHT
00118   };
00119 
00120 /* Convert between stat structure types and directory types.  */
00121 # define IFTODT(mode)       (((mode) & 0170000) >> 12)
00122 # define DTTOIF(dirtype)    ((dirtype) << 12)
00123 #endif
00124 
00125 
00126 /* This is the data type of directory stream objects.
00127    The actual structure is opaque to users.  */
00128 typedef struct __dirstream DIR;
00129 
00130 /* Open a directory stream on NAME.
00131    Return a DIR stream on the directory, or NULL if it could not be opened.
00132 
00133    This function is a possible cancellation point and therefore not
00134    marked with __THROW.  */
00135 extern DIR *opendir (__const char *__name) __nonnull ((1));
00136 
00137 #ifdef __USE_GNU
00138 /* Same as opendir, but open the stream on the file descriptor FD.
00139 
00140    This function is a possible cancellation point and therefore not
00141    marked with __THROW.  */
00142 extern DIR *fdopendir (int __fd);
00143 #endif
00144 
00145 /* Close the directory stream DIRP.
00146    Return 0 if successful, -1 if not.
00147 
00148    This function is a possible cancellation point and therefore not
00149    marked with __THROW.  */
00150 extern int closedir (DIR *__dirp) __nonnull ((1));
00151 
00152 /* Read a directory entry from DIRP.  Return a pointer to a `struct
00153    dirent' describing the entry, or NULL for EOF or error.  The
00154    storage returned may be overwritten by a later readdir call on the
00155    same DIR stream.
00156 
00157    If the Large File Support API is selected we have to use the
00158    appropriate interface.
00159 
00160    This function is a possible cancellation point and therefore not
00161    marked with __THROW.  */
00162 #ifndef __USE_FILE_OFFSET64
00163 extern struct dirent *readdir (DIR *__dirp) __nonnull ((1));
00164 #else
00165 # ifdef __REDIRECT
00166 extern struct dirent *__REDIRECT (readdir, (DIR *__dirp), readdir64)
00167      __nonnull ((1));
00168 # else
00169 #  define readdir readdir64
00170 # endif
00171 #endif
00172 
00173 #ifdef __USE_LARGEFILE64
00174 extern struct dirent64 *readdir64 (DIR *__dirp) __nonnull ((1));
00175 #endif
00176 
00177 #if defined __USE_POSIX || defined __USE_MISC
00178 /* Reentrant version of `readdir'.  Return in RESULT a pointer to the
00179    next entry.
00180 
00181    This function is a possible cancellation point and therefore not
00182    marked with __THROW.  */
00183 # ifndef __USE_FILE_OFFSET64
00184 extern int readdir_r (DIR *__restrict __dirp,
00185                     struct dirent *__restrict __entry,
00186                     struct dirent **__restrict __result)
00187      __nonnull ((1, 2, 3));
00188 # else
00189 #  ifdef __REDIRECT
00190 extern int __REDIRECT (readdir_r,
00191                      (DIR *__restrict __dirp,
00192                      struct dirent *__restrict __entry,
00193                      struct dirent **__restrict __result),
00194                      readdir64_r) __nonnull ((1, 2, 3));
00195 #  else
00196 #   define readdir_r readdir64_r
00197 #  endif
00198 # endif
00199 
00200 # ifdef __USE_LARGEFILE64
00201 extern int readdir64_r (DIR *__restrict __dirp,
00202                      struct dirent64 *__restrict __entry,
00203                      struct dirent64 **__restrict __result)
00204      __nonnull ((1, 2, 3));
00205 # endif
00206 #endif /* POSIX or misc */
00207 
00208 /* Rewind DIRP to the beginning of the directory.  */
00209 extern void rewinddir (DIR *__dirp) __THROW __nonnull ((1));
00210 
00211 #if defined __USE_BSD || defined __USE_MISC || defined __USE_XOPEN
00212 # include <bits/types.h>
00213 
00214 /* Seek to position POS on DIRP.  */
00215 extern void seekdir (DIR *__dirp, long int __pos) __THROW __nonnull ((1));
00216 
00217 /* Return the current position of DIRP.  */
00218 extern long int telldir (DIR *__dirp) __THROW __nonnull ((1));
00219 #endif
00220 
00221 #if defined __USE_BSD || defined __USE_MISC
00222 
00223 /* Return the file descriptor used by DIRP.  */
00224 extern int dirfd (DIR *__dirp) __THROW __nonnull ((1));
00225 
00226 # if defined __OPTIMIZE__ && defined _DIR_dirfd
00227 #  define dirfd(dirp)       _DIR_dirfd (dirp)
00228 # endif
00229 
00230 # ifndef MAXNAMLEN
00231 /* Get the definitions of the POSIX.1 limits.  */
00232 #  include <bits/posix1_lim.h>
00233 
00234 /* `MAXNAMLEN' is the BSD name for what POSIX calls `NAME_MAX'.  */
00235 #  ifdef NAME_MAX
00236 #   define MAXNAMLEN NAME_MAX
00237 #  else
00238 #   define MAXNAMLEN 255
00239 #  endif
00240 # endif
00241 
00242 # define __need_size_t
00243 # include <stddef.h>
00244 
00245 /* Scan the directory DIR, calling SELECTOR on each directory entry.
00246    Entries for which SELECT returns nonzero are individually malloc'd,
00247    sorted using qsort with CMP, and collected in a malloc'd array in
00248    *NAMELIST.  Returns the number of entries selected, or -1 on error.  */
00249 # ifndef __USE_FILE_OFFSET64
00250 extern int scandir (__const char *__restrict __dir,
00251                   struct dirent ***__restrict __namelist,
00252                   int (*__selector) (__const struct dirent *),
00253                   int (*__cmp) (__const void *, __const void *))
00254      __nonnull ((1, 2));
00255 # else
00256 #  ifdef __REDIRECT
00257 extern int __REDIRECT (scandir,
00258                      (__const char *__restrict __dir,
00259                      struct dirent ***__restrict __namelist,
00260                      int (*__selector) (__const struct dirent *),
00261                      int (*__cmp) (__const void *, __const void *)),
00262                      scandir64) __nonnull ((1, 2));
00263 #  else
00264 #   define scandir scandir64
00265 #  endif
00266 # endif
00267 
00268 # if defined __USE_GNU && defined __USE_LARGEFILE64
00269 /* This function is like `scandir' but it uses the 64bit dirent structure.
00270    Please note that the CMP function must now work with struct dirent64 **.  */
00271 extern int scandir64 (__const char *__restrict __dir,
00272                     struct dirent64 ***__restrict __namelist,
00273                     int (*__selector) (__const struct dirent64 *),
00274                     int (*__cmp) (__const void *, __const void *))
00275      __nonnull ((1, 2));
00276 # endif
00277 
00278 /* Function to compare two `struct dirent's alphabetically.  */
00279 # ifndef __USE_FILE_OFFSET64
00280 extern int alphasort (__const void *__e1, __const void *__e2)
00281      __THROW __attribute_pure__ __nonnull ((1, 2));
00282 # else
00283 #  ifdef __REDIRECT
00284 extern int __REDIRECT_NTH (alphasort,
00285                         (__const void *__e1, __const void *__e2),
00286                         alphasort64) __attribute_pure__ __nonnull ((1, 2));
00287 #  else
00288 #   define alphasort alphasort64
00289 #  endif
00290 # endif
00291 
00292 # if defined __USE_GNU && defined __USE_LARGEFILE64
00293 extern int alphasort64 (__const void *__e1, __const void *__e2)
00294      __THROW __attribute_pure__ __nonnull ((1, 2));
00295 # endif
00296 
00297 # ifdef __USE_GNU
00298 /* Function to compare two `struct dirent's by name & version.  */
00299 #  ifndef __USE_FILE_OFFSET64
00300 extern int versionsort (__const void *__e1, __const void *__e2)
00301      __THROW __attribute_pure__ __nonnull ((1, 2));
00302 #  else
00303 #   ifdef __REDIRECT
00304 extern int __REDIRECT_NTH (versionsort,
00305                         (__const void *__e1, __const void *__e2),
00306                         versionsort64)
00307      __attribute_pure__ __nonnull ((1, 2));
00308 #   else
00309 #    define versionsort versionsort64
00310 #   endif
00311 #  endif
00312 
00313 #  ifdef __USE_LARGEFILE64
00314 extern int versionsort64 (__const void *__e1, __const void *__e2)
00315      __THROW __attribute_pure__ __nonnull ((1, 2));
00316 #  endif
00317 # endif
00318 
00319 /* Read directory entries from FD into BUF, reading at most NBYTES.
00320    Reading starts at offset *BASEP, and *BASEP is updated with the new
00321    position after reading.  Returns the number of bytes read; zero when at
00322    end of directory; or -1 for errors.  */
00323 # ifndef __USE_FILE_OFFSET64
00324 extern __ssize_t getdirentries (int __fd, char *__restrict __buf,
00325                             size_t __nbytes,
00326                             __off_t *__restrict __basep)
00327      __THROW __nonnull ((2, 4));
00328 # else
00329 #  ifdef __REDIRECT
00330 extern __ssize_t __REDIRECT_NTH (getdirentries,
00331                              (int __fd, char *__restrict __buf,
00332                               size_t __nbytes,
00333                               __off64_t *__restrict __basep),
00334                              getdirentries64) __nonnull ((2, 4));
00335 #  else
00336 #   define getdirentries getdirentries64
00337 #  endif
00338 # endif
00339 
00340 # ifdef __USE_LARGEFILE64
00341 extern __ssize_t getdirentries64 (int __fd, char *__restrict __buf,
00342                               size_t __nbytes,
00343                               __off64_t *__restrict __basep)
00344      __THROW __nonnull ((2, 4));
00345 # endif
00346 
00347 #endif /* Use BSD or misc.  */
00348 
00349 __END_DECLS
00350 
00351 #endif /* dirent.h  */