src/dir.h

   1 // Copyright © Tavian Barnes <tavianator@tavianator.com>
   2 // SPDX-License-Identifier: 0BSD
   3
   4 /**
   5  * Directories and their contents.
   6  */
   7
   8 #ifndef BFS_DIR_H
   9 #define BFS_DIR_H
  10
  11 #include "alloc.h"
  12 #include "config.h"
  13 #include <sys/types.h>
  14
  15 /**
  16  * Whether the implementation uses the getdents() syscall directly, rather than
  17  * libc's readdir().
  18  */
  19 #ifndef BFS_USE_GETDENTS
  20 #  define BFS_USE_GETDENTS (__linux__ || __FreeBSD__)
  21 #endif
  22
  23 /**
  24  * A directory.
  25  */
  26 struct bfs_dir;
  27
  28 /**
  29  * File types.
  30  */
  31 enum bfs_type {
  32         /** An error occurred for this file. */
  33         BFS_ERROR = -1,
  34         /** Unknown type. */
  35         BFS_UNKNOWN,
  36         /** Block device. */
  37         BFS_BLK,
  38         /** Character device. */
  39         BFS_CHR,
  40         /** Directory. */
  41         BFS_DIR,
  42         /** Solaris door. */
  43         BFS_DOOR,
  44         /** Pipe. */
  45         BFS_FIFO,
  46         /** Symbolic link. */
  47         BFS_LNK,
  48         /** Solaris event port. */
  49         BFS_PORT,
  50         /** Regular file. */
  51         BFS_REG,
  52         /** Socket. */
  53         BFS_SOCK,
  54         /** BSD whiteout. */
  55         BFS_WHT,
  56 };
  57
  58 /**
  59  * Convert a bfs_stat() mode to a bfs_type.
  60  */
  61 enum bfs_type bfs_mode_to_type(mode_t mode);
  62
  63 /**
  64  * A directory entry.
  65  */
  66 struct bfs_dirent {
  67         /** The type of this file (possibly unknown). */
  68         enum bfs_type type;
  69         /** The name of this file. */
  70         const char *name;
  71 };
  72
  73 /**
  74  * Allocate space for a directory.
  75  *
  76  * @return
  77  *         An allocated, unopen directory, or NULL on failure.
  78  */
  79 struct bfs_dir *bfs_allocdir(void);
  80
  81 /**
  82  * Initialize an arena for directories.
  83  *
  84  * @param arena
  85  *         The arena to initialize.
  86  */
  87 void bfs_dir_arena(struct arena *arena);
  88
  89 /**
  90  * bfs_opendir() flags.
  91  */
  92 enum bfs_dir_flags {
  93         /** Include whiteouts in the results. */
  94         BFS_DIR_WHITEOUTS = 1 << 0,
  95         /** @internal Start of private flags. */
  96         BFS_DIR_PRIVATE   = 1 << 1,
  97 };
  98
  99 /**
 100  * Open a directory.
 101  *
 102  * @param dir
 103  *         The allocated directory.
 104  * @param at_fd
 105  *         The base directory for path resolution.
 106  * @param at_path
 107  *         The path of the directory to open, relative to at_fd.  Pass NULL to
 108  *         open at_fd itself.
 109  * @param flags
 110  *         Flags that control which directory entries are listed.
 111  * @return
 112  *         0 on success, or -1 on failure.
 113  */
 114 int bfs_opendir(struct bfs_dir *dir, int at_fd, const char *at_path, enum bfs_dir_flags flags);
 115
 116 /**
 117  * Get the file descriptor for a directory.
 118  */
 119 int bfs_dirfd(const struct bfs_dir *dir);
 120
 121 /**
 122  * Performs any I/O necessary for the next bfs_readdir() call.
 123  *
 124  * @param dir
 125  *         The directory to poll.
 126  * @return
 127  *         1 on success, 0 on EOF, or -1 on failure.
 128  */
 129 int bfs_polldir(struct bfs_dir *dir);
 130
 131 /**
 132  * Read a directory entry.
 133  *
 134  * @param dir
 135  *         The directory to read.
 136  * @param[out] dirent
 137  *         The directory entry to populate.
 138  * @return
 139  *         1 on success, 0 on EOF, or -1 on failure.
 140  */
 141 int bfs_readdir(struct bfs_dir *dir, struct bfs_dirent *de);
 142
 143 /**
 144  * Close a directory.
 145  *
 146  * @return
 147  *         0 on success, -1 on failure.
 148  */
 149 int bfs_closedir(struct bfs_dir *dir);
 150
 151 /**
 152  * Whether the bfs_unwrapdir() function is supported.
 153  */
 154 #ifndef BFS_USE_UNWRAPDIR
 155 #  define BFS_USE_UNWRAPDIR (BFS_USE_GETDENTS || __FreeBSD__)
 156 #endif
 157
 158 #if BFS_USE_UNWRAPDIR
 159 /**
 160  * Detach the file descriptor from an open directory.
 161  *
 162  * @param dir
 163  *         The directory to detach.
 164  * @return
 165  *         The file descriptor of the directory.
 166  */
 167 int bfs_unwrapdir(struct bfs_dir *dir);
 168 #endif
 169
 170 #endif // BFS_DIR_H