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 <sys/cdefs.h> 37 38 #include <stdint.h> 39 #include <sys/types.h> 40 41 __BEGIN_DECLS 42 43 /** d_type value when the type is not known. */ 44 #define DT_UNKNOWN 0 45 /** d_type value for a FIFO. */ 46 #define DT_FIFO 1 47 /** d_type value for a character device. */ 48 #define DT_CHR 2 49 /** d_type value for a directory. */ 50 #define DT_DIR 4 51 /** d_type value for a block device. */ 52 #define DT_BLK 6 53 /** d_type value for a regular file. */ 54 #define DT_REG 8 55 /** d_type value for a symbolic link. */ 56 #define DT_LNK 10 57 /** d_type value for a socket. */ 58 #define DT_SOCK 12 59 #define DT_WHT 14 60 61 #if defined(__LP64__) 62 #define __DIRENT64_INO_T ino_t 63 #else 64 #define __DIRENT64_INO_T uint64_t /* Historical accident. */ 65 #endif 66 67 #define __DIRENT64_BODY \ 68 __DIRENT64_INO_T d_ino; \ 69 off64_t d_off; \ 70 unsigned short d_reclen; \ 71 unsigned char d_type; \ 72 char d_name[256]; \ 73 74 /** The structure returned by readdir(). Identical to dirent64 on Android. */ 75 struct dirent { __DIRENT64_BODY }; 76 /** The structure returned by readdir64(). Identical to dirent on Android. */ 77 struct dirent64 { __DIRENT64_BODY }; 78 79 #undef __DIRENT64_BODY 80 #undef __DIRENT64_INO_T 81 82 /* glibc compatibility. */ 83 #undef _DIRENT_HAVE_D_NAMLEN /* Linux doesn't have a d_namlen field. */ 84 #define _DIRENT_HAVE_D_RECLEN 85 #define _DIRENT_HAVE_D_OFF 86 #define _DIRENT_HAVE_D_TYPE 87 88 #define d_fileno d_ino 89 90 /** The structure returned by opendir()/fopendir(). */ 91 typedef struct DIR DIR; 92 93 /** 94 * [opendir(3)](https://man7.org/linux/man-pages/man3/opendir.3.html) 95 * opens a directory stream for the directory at `__path`. 96 * 97 * Returns null and sets `errno` on failure. 98 */ 99 DIR* _Nullable opendir(const char* _Nonnull __path); 100 101 /** 102 * [fopendir(3)](https://man7.org/linux/man-pages/man3/opendir.3.html) 103 * opens a directory stream for the directory at `__dir_fd`. 104 * 105 * Returns null and sets `errno` on failure. 106 */ 107 DIR* _Nullable fdopendir(int __dir_fd); 108 109 /** 110 * [readdir(3)](https://man7.org/linux/man-pages/man3/readdir.3.html) 111 * returns the next directory entry in the given directory. 112 * 113 * Returns a pointer to a directory entry on success, 114 * or returns null and leaves `errno` unchanged at the end of the directory, 115 * or returns null and sets `errno` on failure. 116 */ 117 struct dirent* _Nullable readdir(DIR* _Nonnull __dir); 118 119 /** 120 * [readdir64(3)](https://man7.org/linux/man-pages/man3/readdir.3.html) 121 * returns the next directory entry in the given directory. 122 * 123 * Returns a pointer to a directory entry on success, 124 * or returns null and leaves `errno` unchanged at the end of the directory, 125 * or returns null and sets `errno` on failure. 126 */ 127 struct dirent64* _Nullable readdir64(DIR* _Nonnull __dir); 128 129 int readdir_r(DIR* _Nonnull __dir, struct dirent* _Nonnull __entry, struct dirent* _Nullable * _Nonnull __buffer) __attribute__((__deprecated__("readdir_r is deprecated; use readdir instead"))); 130 int readdir64_r(DIR* _Nonnull __dir, struct dirent64* _Nonnull __entry, struct dirent64* _Nullable * _Nonnull __buffer) __attribute__((__deprecated__("readdir64_r is deprecated; use readdir64 instead"))); 131 132 /** 133 * [closedir(3)](https://man7.org/linux/man-pages/man3/closedir.3.html) 134 * closes a directory stream. 135 * 136 * Returns 0 on success and returns -1 and sets `errno` on failure. 137 */ 138 int closedir(DIR* _Nonnull __dir); 139 140 /** 141 * [rewinddir(3)](https://man7.org/linux/man-pages/man3/rewinddir.3.html) 142 * rewinds a directory stream to the first entry. 143 */ 144 void rewinddir(DIR* _Nonnull __dir); 145 146 /** 147 * [seekdir(3)](https://man7.org/linux/man-pages/man3/seekdir.3.html) 148 * seeks a directory stream to the given entry, which must be a value returned 149 * by telldir(). 150 * 151 * Available since API level 23. 152 */ 153 154 #if __BIONIC_AVAILABILITY_GUARD(23) 155 void seekdir(DIR* _Nonnull __dir, long __location) __INTRODUCED_IN(23); 156 157 /** 158 * [telldir(3)](https://man7.org/linux/man-pages/man3/telldir.3.html) 159 * returns a value representing the current position in the directory 160 * for use with seekdir(). 161 * 162 * Returns the current position on success and returns -1 and sets `errno` on failure. 163 * 164 * Available since API level 23. 165 */ 166 long telldir(DIR* _Nonnull __dir) __INTRODUCED_IN(23); 167 #endif /* __BIONIC_AVAILABILITY_GUARD(23) */ 168 169 170 /** 171 * [dirfd(3)](https://man7.org/linux/man-pages/man3/dirfd.3.html) 172 * returns the file descriptor backing the given directory stream. 173 * 174 * Returns a file descriptor on success and returns -1 and sets `errno` on failure. 175 */ 176 int dirfd(DIR* _Nonnull __dir); 177 178 /** 179 * [alphasort](https://man7.org/linux/man-pages/man3/alphasort.3.html) is a 180 * comparator for use with scandir() that uses strcoll(). 181 */ 182 int alphasort(const struct dirent* _Nonnull * _Nonnull __lhs, const struct dirent* _Nonnull * _Nonnull __rhs); 183 184 /** 185 * [alphasort64](https://man7.org/linux/man-pages/man3/alphasort.3.html) is a 186 * comparator for use with scandir64() that uses strcmp(). 187 */ 188 int alphasort64(const struct dirent64* _Nonnull * _Nonnull __lhs, const struct dirent64* _Nonnull * _Nonnull __rhs); 189 190 /** 191 * [scandir(3)](https://man7.org/linux/man-pages/man3/scandir.3.html) 192 * scans all the directory `__path`, filtering entries with `__filter` and 193 * sorting them with qsort() using the given `__comparator`, and storing them 194 * into `__name_list`. Passing NULL as the filter accepts all entries. 195 * Passing NULL as the comparator skips sorting. 196 * 197 * Returns the number of entries returned in the list on success, 198 * and returns -1 and sets `errno` on failure. 199 */ 200 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)); 201 202 /** 203 * [scandir64(3)](https://man7.org/linux/man-pages/man3/scandir.3.html) 204 * scans all the directory `__path`, filtering entries with `__filter` and 205 * sorting them with qsort() using the given `__comparator`, and storing them 206 * into `__name_list`. Passing NULL as the filter accepts all entries. 207 * Passing NULL as the comparator skips sorting. 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 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)); 213 214 #if defined(__USE_GNU) 215 216 /** 217 * [scandirat64(3)](https://man7.org/linux/man-pages/man3/scandirat.3.html) 218 * scans all the directory referenced by the pair of `__dir_fd` and `__path`, 219 * filtering entries with `__filter` and sorting them with qsort() using the 220 * given `__comparator`, and storing them into `__name_list`. Passing NULL as 221 * the filter accepts all entries. 222 * Passing NULL as the comparator skips sorting. 223 * 224 * Returns the number of entries returned in the list on success, 225 * and returns -1 and sets `errno` on failure. 226 * 227 * Available since API level 24. 228 */ 229 230 #if __BIONIC_AVAILABILITY_GUARD(24) 231 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); 232 233 /** 234 * [scandirat(3)](https://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 * Passing NULL as the comparator skips sorting. 240 * 241 * Returns the number of entries returned in the list on success, 242 * and returns -1 and sets `errno` on failure. 243 * 244 * Available since API level 24. 245 */ 246 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); 247 #endif /* __BIONIC_AVAILABILITY_GUARD(24) */ 248 249 250 #endif 251 252 __END_DECLS 253