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 struct dirent64* _Nullable readdir64(DIR* _Nonnull __dir); 127 128 int readdir_r(DIR* _Nonnull __dir, struct dirent* _Nonnull __entry, struct dirent* _Nullable * _Nonnull __buffer) __attribute__((__deprecated__("readdir_r is deprecated; use readdir instead"))); 129 int readdir64_r(DIR* _Nonnull __dir, struct dirent64* _Nonnull __entry, struct dirent64* _Nullable * _Nonnull __buffer) __attribute__((__deprecated__("readdir64_r is deprecated; use readdir64 instead"))); 130 131 /** 132 * [closedir(3)](http://man7.org/linux/man-pages/man3/closedir.3.html) 133 * closes a directory stream. 134 * 135 * Returns 0 on success and returns -1 and sets `errno` on failure. 136 */ 137 int closedir(DIR* _Nonnull __dir); 138 139 /** 140 * [rewinddir(3)](http://man7.org/linux/man-pages/man3/rewinddir.3.html) 141 * rewinds a directory stream to the first entry. 142 */ 143 void rewinddir(DIR* _Nonnull __dir); 144 145 /** 146 * [seekdir(3)](http://man7.org/linux/man-pages/man3/seekdir.3.html) 147 * seeks a directory stream to the given entry, which must be a value returned 148 * by telldir(). 149 * 150 * Available since API level 23. 151 */ 152 void seekdir(DIR* _Nonnull __dir, long __location) __INTRODUCED_IN(23); 153 154 /** 155 * [telldir(3)](http://man7.org/linux/man-pages/man3/telldir.3.html) 156 * returns a value representing the current position in the directory 157 * for use with seekdir(). 158 * 159 * Returns the current position on success and returns -1 and sets `errno` on failure. 160 * 161 * Available since API level 23. 162 */ 163 long telldir(DIR* _Nonnull __dir) __INTRODUCED_IN(23); 164 165 /** 166 * [dirfd(3)](http://man7.org/linux/man-pages/man3/dirfd.3.html) 167 * returns the file descriptor backing the given directory stream. 168 * 169 * Returns a file descriptor on success and returns -1 and sets `errno` on failure. 170 */ 171 int dirfd(DIR* _Nonnull __dir); 172 173 /** 174 * [alphasort](http://man7.org/linux/man-pages/man3/alphasort.3.html) is a 175 * comparator for use with scandir() that uses strcoll(). 176 */ 177 int alphasort(const struct dirent* _Nonnull * _Nonnull __lhs, const struct dirent* _Nonnull * _Nonnull __rhs); 178 179 /** 180 * [alphasort64](http://man7.org/linux/man-pages/man3/alphasort.3.html) is a 181 * comparator for use with scandir64() that uses strcmp(). 182 */ 183 int alphasort64(const struct dirent64* _Nonnull * _Nonnull __lhs, const struct dirent64* _Nonnull * _Nonnull __rhs); 184 185 /** 186 * [scandir(3)](http://man7.org/linux/man-pages/man3/scandir.3.html) 187 * scans all the directory `__path`, filtering entries with `__filter` and 188 * sorting them with qsort() using the given `__comparator`, and storing them 189 * into `__name_list`. Passing NULL as the filter accepts all entries. 190 * Passing NULL as the comparator skips sorting. 191 * 192 * Returns the number of entries returned in the list on success, 193 * and returns -1 and sets `errno` on failure. 194 */ 195 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)); 196 197 /** 198 * [scandir64(3)](http://man7.org/linux/man-pages/man3/scandir.3.html) 199 * scans all the directory `__path`, filtering entries with `__filter` and 200 * sorting them with qsort() using the given `__comparator`, and storing them 201 * into `__name_list`. Passing NULL as the filter accepts all entries. 202 * Passing NULL as the comparator skips sorting. 203 * 204 * Returns the number of entries returned in the list on success, 205 * and returns -1 and sets `errno` on failure. 206 */ 207 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)); 208 209 #if defined(__USE_GNU) 210 211 /** 212 * [scandirat64(3)](http://man7.org/linux/man-pages/man3/scandirat.3.html) 213 * scans all the directory referenced by the pair of `__dir_fd` and `__path`, 214 * filtering entries with `__filter` and sorting them with qsort() using the 215 * given `__comparator`, and storing them into `__name_list`. Passing NULL as 216 * the filter accepts all entries. 217 * Passing NULL as the comparator skips sorting. 218 * 219 * Returns the number of entries returned in the list on success, 220 * and returns -1 and sets `errno` on failure. 221 * 222 * Available since API level 24. 223 */ 224 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); 225 226 /** 227 * [scandirat(3)](http://man7.org/linux/man-pages/man3/scandirat.3.html) 228 * scans all the directory referenced by the pair of `__dir_fd` and `__path`, 229 * filtering entries with `__filter` and sorting them with qsort() using the 230 * given `__comparator`, and storing them into `__name_list`. Passing NULL as 231 * the filter accepts all entries. 232 * Passing NULL as the comparator skips sorting. 233 * 234 * Returns the number of entries returned in the list on success, 235 * and returns -1 and sets `errno` on failure. 236 * 237 * Available since API level 24. 238 */ 239 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); 240 241 #endif 242 243 __END_DECLS 244