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* _Nullable opendir(const char* _Nonnull __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* _Nullable 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* _Nullable readdir(DIR* _Nonnull __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* _Nullable readdir64(DIR* _Nonnull __dir) __INTRODUCED_IN(21); 129 #endif /* __ANDROID_API__ >= 21 */ 130 131 132 int readdir_r(DIR* _Nonnull __dir, struct dirent* _Nonnull __entry, struct dirent* _Nullable * _Nonnull __buffer) __attribute__((__deprecated__("readdir_r is deprecated; use readdir instead"))); 133 134 #if __ANDROID_API__ >= 21 135 int readdir64_r(DIR* _Nonnull __dir, struct dirent64* _Nonnull __entry, struct dirent64* _Nullable * _Nonnull __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* _Nonnull __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* _Nonnull __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* _Nonnull __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* _Nonnull __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* _Nonnull __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* _Nonnull * _Nonnull __lhs, const struct dirent* _Nonnull * _Nonnull __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* _Nonnull * _Nonnull __lhs, const struct dirent64* _Nonnull * _Nonnull __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 * Passing NULL as the comparator skips sorting. 209 * 210 * Returns the number of entries returned in the list on success, 211 * and returns -1 and sets `errno` on failure. 212 */ 213 int scandir(const char* _Nonnull __path, struct dirent* _Nonnull * _Nonnull * _Nonnull __name_list, int (* _Nullable __filter)(const struct dirent* _Nonnull), int (* _Nullable __comparator)(const struct dirent* _Nonnull * _Nonnull, const struct dirent* _Nonnull * _Nonnull)); 214 215 /** 216 * [scandir64(3)](http://man7.org/linux/man-pages/man3/scandir.3.html) 217 * scans all the directory `__path`, filtering entries with `__filter` and 218 * sorting them with qsort() using the given `__comparator`, and storing them 219 * into `__name_list`. Passing NULL as the filter accepts all entries. 220 * Passing NULL as the comparator skips sorting. 221 * 222 * Returns the number of entries returned in the list on success, 223 * and returns -1 and sets `errno` on failure. 224 * 225 * Available since API level 21. 226 */ 227 228 #if __ANDROID_API__ >= 21 229 int scandir64(const char* _Nonnull __path, struct dirent64* _Nonnull * _Nonnull * _Nonnull __name_list, int (* _Nullable __filter)(const struct dirent64* _Nonnull), int (* _Nullable __comparator)(const struct dirent64* _Nonnull * _Nonnull, const struct dirent64* _Nonnull * _Nonnull)) __INTRODUCED_IN(21); 230 #endif /* __ANDROID_API__ >= 21 */ 231 232 233 #if defined(__USE_GNU) 234 235 /** 236 * [scandirat64(3)](http://man7.org/linux/man-pages/man3/scandirat.3.html) 237 * scans all the directory referenced by the pair of `__dir_fd` and `__path`, 238 * filtering entries with `__filter` and sorting them with qsort() using the 239 * given `__comparator`, and storing them into `__name_list`. Passing NULL as 240 * the filter accepts all entries. 241 * Passing NULL as the comparator skips sorting. 242 * 243 * Returns the number of entries returned in the list on success, 244 * and returns -1 and sets `errno` on failure. 245 * 246 * Available since API level 24. 247 */ 248 249 #if __ANDROID_API__ >= 24 250 int scandirat64(int __dir_fd, const char* _Nonnull __path, struct dirent64* _Nonnull * _Nonnull * _Nonnull __name_list, int (* _Nullable __filter)(const struct dirent64* _Nonnull), int (* _Nullable __comparator)(const struct dirent64* _Nonnull * _Nonnull, const struct dirent64* _Nonnull * _Nonnull)) __INTRODUCED_IN(24); 251 252 /** 253 * [scandirat(3)](http://man7.org/linux/man-pages/man3/scandirat.3.html) 254 * scans all the directory referenced by the pair of `__dir_fd` and `__path`, 255 * filtering entries with `__filter` and sorting them with qsort() using the 256 * given `__comparator`, and storing them into `__name_list`. Passing NULL as 257 * the filter accepts all entries. 258 * Passing NULL as the comparator skips sorting. 259 * 260 * Returns the number of entries returned in the list on success, 261 * and returns -1 and sets `errno` on failure. 262 * 263 * Available since API level 24. 264 */ 265 int scandirat(int __dir_fd, const char* _Nonnull __path, struct dirent* _Nonnull * _Nonnull * _Nonnull __name_list, int (* _Nullable __filter)(const struct dirent* _Nonnull), int (* _Nullable __comparator)(const struct dirent* _Nonnull * _Nonnull, const struct dirent* _Nonnull * _Nonnull)) __INTRODUCED_IN(24); 266 #endif /* __ANDROID_API__ >= 24 */ 267 268 269 #endif 270 271 __END_DECLS 272