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