1 /* 2 * Copyright (C) 2008 The Android Open Source Project 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * * Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * * Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in 12 * the documentation and/or other materials provided with the 13 * distribution. 14 * 15 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 16 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 17 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 18 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 19 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 20 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 21 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 22 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 23 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 24 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 25 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26 * SUCH DAMAGE. 27 */ 28 29 #pragma once 30 31 /** 32 * @file dirent.h 33 * @brief Directory entry iteration. 34 */ 35 36 #include <stdint.h> 37 #include <sys/cdefs.h> 38 #include <sys/types.h> 39 40 __BEGIN_DECLS 41 42 /** d_type value when the type is not known. */ 43 #define DT_UNKNOWN 0 44 /** d_type value for a FIFO. */ 45 #define DT_FIFO 1 46 /** d_type value for a character device. */ 47 #define DT_CHR 2 48 /** d_type value for a directory. */ 49 #define DT_DIR 4 50 /** d_type value for a block device. */ 51 #define DT_BLK 6 52 /** d_type value for a regular file. */ 53 #define DT_REG 8 54 /** d_type value for a symbolic link. */ 55 #define DT_LNK 10 56 /** d_type value for a socket. */ 57 #define DT_SOCK 12 58 #define DT_WHT 14 59 60 #if defined(__LP64__) 61 #define __DIRENT64_INO_T ino_t 62 #else 63 #define __DIRENT64_INO_T uint64_t /* Historical accident. */ 64 #endif 65 66 #define __DIRENT64_BODY \ 67 __DIRENT64_INO_T d_ino; \ 68 off64_t d_off; \ 69 unsigned short d_reclen; \ 70 unsigned char d_type; \ 71 char d_name[256]; \ 72 73 /** The structure returned by readdir(). Identical to dirent64 on Android. */ 74 struct dirent { __DIRENT64_BODY }; 75 /** The structure returned by readdir64(). Identical to dirent on Android. */ 76 struct dirent64 { __DIRENT64_BODY }; 77 78 #undef __DIRENT64_BODY 79 #undef __DIRENT64_INO_T 80 81 /* glibc compatibility. */ 82 #undef _DIRENT_HAVE_D_NAMLEN /* Linux doesn't have a d_namlen field. */ 83 #define _DIRENT_HAVE_D_RECLEN 84 #define _DIRENT_HAVE_D_OFF 85 #define _DIRENT_HAVE_D_TYPE 86 87 #define d_fileno d_ino 88 89 /** The structure returned by opendir()/fopendir(). */ 90 typedef struct DIR DIR; 91 92 /** 93 * [opendir(3)](http://man7.org/linux/man-pages/man3/opendir.3.html) 94 * opens a directory stream for the directory at `__path`. 95 * 96 * Returns null and sets `errno` on failure. 97 */ 98 DIR* opendir(const char* __path); 99 100 /** 101 * [fopendir(3)](http://man7.org/linux/man-pages/man3/opendir.3.html) 102 * opens a directory stream for the directory at `__dir_fd`. 103 * 104 * Returns null and sets `errno` on failure. 105 */ 106 DIR* fdopendir(int __dir_fd); 107 108 /** 109 * [readdir(3)](http://man7.org/linux/man-pages/man3/readdir.3.html) 110 * returns the next directory entry in the given directory. 111 * 112 * Returns a pointer to a directory entry on success, 113 * or returns null and leaves `errno` unchanged at the end of the directory, 114 * or returns null and sets `errno` on failure. 115 */ 116 struct dirent* readdir(DIR* __dir); 117 118 /** 119 * [readdir64(3)](http://man7.org/linux/man-pages/man3/readdir.3.html) 120 * returns the next directory entry in the given directory. 121 * 122 * Returns a pointer to a directory entry on success, 123 * or returns null and leaves `errno` unchanged at the end of the directory, 124 * or returns null and sets `errno` on failure. 125 */ 126 127 #if __ANDROID_API__ >= 21 128 struct dirent64* readdir64(DIR* __dir) __INTRODUCED_IN(21); 129 #endif /* __ANDROID_API__ >= 21 */ 130 131 132 int readdir_r(DIR* __dir, struct dirent* __entry, struct dirent** __buffer) __attribute__((__deprecated__("readdir_r is deprecated; use readdir instead"))); 133 134 #if __ANDROID_API__ >= 21 135 int readdir64_r(DIR* __dir, struct dirent64* __entry, struct dirent64** __buffer) __INTRODUCED_IN(21) __attribute__((__deprecated__("readdir64_r is deprecated; use readdir64 instead"))); 136 #endif /* __ANDROID_API__ >= 21 */ 137 138 139 /** 140 * [closedir(3)](http://man7.org/linux/man-pages/man3/closedir.3.html) 141 * closes a directory stream. 142 * 143 * Returns 0 on success and returns -1 and sets `errno` on failure. 144 */ 145 int closedir(DIR* __dir); 146 147 /** 148 * [rewinddir(3)](http://man7.org/linux/man-pages/man3/rewinddir.3.html) 149 * rewinds a directory stream to the first entry. 150 */ 151 void rewinddir(DIR* __dir); 152 153 /** 154 * [seekdir(3)](http://man7.org/linux/man-pages/man3/seekdir.3.html) 155 * seeks a directory stream to the given entry, which must be a value returned 156 * by telldir(). 157 * 158 * Available since API level 23. 159 */ 160 161 #if __ANDROID_API__ >= 23 162 void seekdir(DIR* __dir, long __location) __INTRODUCED_IN(23); 163 164 /** 165 * [telldir(3)](http://man7.org/linux/man-pages/man3/telldir.3.html) 166 * returns a value representing the current position in the directory 167 * for use with seekdir(). 168 * 169 * Returns the current position on success and returns -1 and sets `errno` on failure. 170 * 171 * Available since API level 23. 172 */ 173 long telldir(DIR* __dir) __INTRODUCED_IN(23); 174 #endif /* __ANDROID_API__ >= 23 */ 175 176 177 /** 178 * [dirfd(3)](http://man7.org/linux/man-pages/man3/dirfd.3.html) 179 * returns the file descriptor backing the given directory stream. 180 * 181 * Returns a file descriptor on success and returns -1 and sets `errno` on failure. 182 */ 183 int dirfd(DIR* __dir); 184 185 /** 186 * [alphasort](http://man7.org/linux/man-pages/man3/alphasort.3.html) is a 187 * comparator for use with scandir() that uses strcoll(). 188 */ 189 int alphasort(const struct dirent** __lhs, const struct dirent** __rhs); 190 191 /** 192 * [alphasort64](http://man7.org/linux/man-pages/man3/alphasort.3.html) is a 193 * comparator for use with scandir64() that uses strcmp(). 194 * 195 * Available since API level 21. 196 */ 197 198 #if __ANDROID_API__ >= 21 199 int alphasort64(const struct dirent64** __lhs, const struct dirent64** __rhs) __INTRODUCED_IN(21); 200 #endif /* __ANDROID_API__ >= 21 */ 201 202 203 /** 204 * [scandir(3)](http://man7.org/linux/man-pages/man3/scandir.3.html) 205 * scans all the directory `__path`, filtering entries with `__filter` and 206 * sorting them with qsort() using the given `__comparator`, and storing them 207 * into `__name_list`. Passing NULL as the filter accepts all entries. 208 * 209 * Returns the number of entries returned in the list on success, 210 * and returns -1 and sets `errno` on failure. 211 */ 212 int scandir(const char* __path, struct dirent*** __name_list, int (*__filter)(const struct dirent*), int (*__comparator)(const struct dirent**, const struct dirent**)); 213 214 /** 215 * [scandir64(3)](http://man7.org/linux/man-pages/man3/scandir.3.html) 216 * scans all the directory `__path`, filtering entries with `__filter` and 217 * sorting them with qsort() using the given `__comparator`, and storing them 218 * into `__name_list`. Passing NULL as the filter accepts all entries. 219 * 220 * Returns the number of entries returned in the list on success, 221 * and returns -1 and sets `errno` on failure. 222 * 223 * Available since API level 21. 224 */ 225 226 #if __ANDROID_API__ >= 21 227 int scandir64(const char* __path, struct dirent64*** __name_list, int (*__filter)(const struct dirent64*), int (*__comparator)(const struct dirent64**, const struct dirent64**)) __INTRODUCED_IN(21); 228 #endif /* __ANDROID_API__ >= 21 */ 229 230 231 #if defined(__USE_GNU) 232 233 /** 234 * [scandirat64(3)](http://man7.org/linux/man-pages/man3/scandirat.3.html) 235 * scans all the directory referenced by the pair of `__dir_fd` and `__path`, 236 * filtering entries with `__filter` and sorting them with qsort() using the 237 * given `__comparator`, and storing them into `__name_list`. Passing NULL as 238 * the filter accepts all entries. 239 * 240 * Returns the number of entries returned in the list on success, 241 * and returns -1 and sets `errno` on failure. 242 * 243 * Available since API level 24. 244 */ 245 246 #if __ANDROID_API__ >= 24 247 int scandirat64(int __dir_fd, const char* __path, struct dirent64*** __name_list, int (*__filter)(const struct dirent64*), int (*__comparator)(const struct dirent64**, const struct dirent64**)) __INTRODUCED_IN(24); 248 249 /** 250 * [scandirat(3)](http://man7.org/linux/man-pages/man3/scandirat.3.html) 251 * scans all the directory referenced by the pair of `__dir_fd` and `__path`, 252 * filtering entries with `__filter` and sorting them with qsort() using the 253 * given `__comparator`, and storing them into `__name_list`. Passing NULL as 254 * the filter accepts all entries. 255 * 256 * Returns the number of entries returned in the list on success, 257 * and returns -1 and sets `errno` on failure. 258 * 259 * Available since API level 24. 260 */ 261 int scandirat(int __dir_fd, const char* __path, struct dirent*** __name_list, int (*__filter)(const struct dirent*), int (*__comparator)(const struct dirent**, const struct dirent**)) __INTRODUCED_IN(24); 262 #endif /* __ANDROID_API__ >= 24 */ 263 264 265 #endif 266 267 __END_DECLS 268