Debian Codegraph @

src/basic/recurse-dir.h

raw
1 /* SPDX-License-Identifier: LGPL-2.1-or-later */
2 #pragma once
3
4 #include <dirent.h>
5
6 #include "basic-forward.h"
7
8 typedef enum RecurseDirFlags {
9 /* Interpreted by readdir_all() */
10 RECURSE_DIR_SORT = 1 << 0, /* sort file directory entries before processing them */
11 RECURSE_DIR_IGNORE_DOT = 1 << 1, /* ignore all dot files ("." and ".." are always ignored) */
12 RECURSE_DIR_ENSURE_TYPE = 1 << 2, /* guarantees that 'd_type' field of 'de' is not DT_UNKNOWN */
13
14 /* Interpreted by recurse_dir() */
15 RECURSE_DIR_SAME_MOUNT = 1 << 3, /* skips over subdirectories that are submounts */
16 RECURSE_DIR_INODE_FD = 1 << 4, /* passes an opened inode fd (O_DIRECTORY fd in case of dirs, O_PATH otherwise) */
17 RECURSE_DIR_TOPLEVEL = 1 << 5, /* call RECURSE_DIR_ENTER/RECURSE_DIR_LEAVE once for top-level dir, too, with dir_fd=-1 and NULL dirent */
18 } RecurseDirFlags;
19
20 typedef struct DirectoryEntries {
21 size_t n_entries;
22 struct dirent **entries;
23 size_t buffer_size;
24 struct dirent buffer[];
25 } DirectoryEntries;
26
27 int readdir_all(int dir_fd, RecurseDirFlags flags, DirectoryEntries **ret);
28 int readdir_all_at(int fd, const char *path, RecurseDirFlags flags, DirectoryEntries **ret);
29
30 typedef enum RecurseDirEvent {
31 RECURSE_DIR_ENTER, /* only for dir inodes */
32 RECURSE_DIR_LEAVE, /* only for dir inodes */
33 RECURSE_DIR_ENTRY, /* only for non-dir inodes */
34 RECURSE_DIR_SKIP_MOUNT, /* only for dir inodes: when we don't descent into submounts */
35 RECURSE_DIR_SKIP_DEPTH, /* only for dir inodes: when we reached the max depth */
36
37 /* If we hit an error opening/stating an entry, then we'll fire a
38 * 'RECURSE_DIR_SKIP_{OPEN_DIR|OPEN_INODE|STAT_INODE}_ERROR_BASE + errno' event. In this case 'de'
39 * will be valid, but the statx data NULL and the inode fd -1. */
40 RECURSE_DIR_SKIP_OPEN_DIR_ERROR_BASE,
41 RECURSE_DIR_SKIP_OPEN_DIR_ERROR_MAX = RECURSE_DIR_SKIP_OPEN_DIR_ERROR_BASE + ERRNO_MAX,
42
43 RECURSE_DIR_SKIP_OPEN_INODE_ERROR_BASE,
44 RECURSE_DIR_SKIP_OPEN_INODE_ERROR_MAX = RECURSE_DIR_SKIP_OPEN_INODE_ERROR_BASE + ERRNO_MAX,
45
46 RECURSE_DIR_SKIP_STAT_INODE_ERROR_BASE,
47 RECURSE_DIR_SKIP_STAT_INODE_ERROR_MAX = RECURSE_DIR_SKIP_STAT_INODE_ERROR_BASE + ERRNO_MAX,
48
49 _RECURSE_DIR_EVENT_MAX,
50 _RECURSE_DIR_EVENT_INVALID = -EINVAL,
51 } RecurseDirEvent;
52
53 #define RECURSE_DIR_CONTINUE 0
54 #define RECURSE_DIR_LEAVE_DIRECTORY INT_MIN
55 #define RECURSE_DIR_SKIP_ENTRY (INT_MIN+1)
56 #define RECURSE_DIR_UNLINK (INT_MIN+2)
57 #define RECURSE_DIR_UNLINK_GRACEFUL (INT_MIN+3)
58
59 /* Make sure that the negative errno range and these two special returns don't overlap */
60 assert_cc(RECURSE_DIR_LEAVE_DIRECTORY < -ERRNO_MAX);
61 assert_cc(RECURSE_DIR_SKIP_ENTRY < -ERRNO_MAX);
62
63 /* Prototype for the callback function that is called whenever we enter or leave a dir inode, or find another dir entry. Return values are:
64 *
65 * RECURSE_DIR_CONTINUE (i.e. 0) → continue with next entry
66 * RECURSE_DIR_LEAVE_DIRECTORY → leave current directory immediately, don't process further siblings
67 * RECURSE_DIR_SKIP_ENTRY → skip this entry otherwise (only makes sense on RECURSE_DIR_ENTER)
68 * others → terminate iteration entirely, return the specified value (idea is that
69 * < 0 indicates errors and > 0 indicates various forms of success)
70 */
71 typedef int (*recurse_dir_func_t)(
72 RecurseDirEvent event,
73 const char *path, /* Full non-normalized path, i.e. the path specified during recurise_dir() with what we found appended */
74 int dir_fd, /* fd of the current dir */
75 int inode_fd, /* fd of the current entry in the current dir (O_DIRECTORY if directory, and O_PATH otherwise, but only if RECURSE_DIR_INODE_FD was set) */
76 const struct dirent *de, /* directory entry (always valid) */
77 const struct statx *sx, /* statx data (only if statx_mask was non-zero) */
78 void *userdata);
79
80 int recurse_dir(int dir_fd, const char *path, unsigned statx_mask, unsigned n_depth_max, RecurseDirFlags flags, recurse_dir_func_t func, void *userdata);
81 int recurse_dir_at(int atfd, const char *path, unsigned statx_mask, unsigned n_depth_max, RecurseDirFlags flags, recurse_dir_func_t func, void *userdata);