1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
|
/****************************************************************************
* bfs *
* Copyright (C) 2015-2021 Tavian Barnes <tavianator@tavianator.com> *
* *
* Permission to use, copy, modify, and/or distribute this software for any *
* purpose with or without fee is hereby granted. *
* *
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES *
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF *
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR *
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES *
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN *
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF *
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. *
****************************************************************************/
/**
* A file-walking API based on nftw().
*/
#ifndef BFS_BFTW_H
#define BFS_BFTW_H
#include "dir.h"
#include "stat.h"
#include <stddef.h>
/**
* Possible visit occurrences.
*/
enum bftw_visit {
/** Pre-order visit. */
BFTW_PRE,
/** Post-order visit. */
BFTW_POST,
};
/**
* Cached bfs_stat() info for a file.
*/
struct bftw_stat {
/** A pointer to the bfs_stat() buffer, if available. */
const struct bfs_stat *buf;
/** Storage for the bfs_stat() buffer, if needed. */
struct bfs_stat storage;
/** The cached error code, if any. */
int error;
};
/**
* Data about the current file for the bftw() callback.
*/
struct BFTW {
/** The path to the file. */
const char *path;
/** The string offset of the filename. */
size_t nameoff;
/** The root path passed to bftw(). */
const char *root;
/** The depth of this file in the traversal. */
size_t depth;
/** Which visit this is. */
enum bftw_visit visit;
/** The file type. */
enum bfs_type type;
/** The errno that occurred, if type == BFTW_ERROR. */
int error;
/** A parent file descriptor for the *at() family of calls. */
int at_fd;
/** The path relative to at_fd for the *at() family of calls. */
const char *at_path;
/** Flags for bfs_stat(). */
enum bfs_stat_flags stat_flags;
/** Cached bfs_stat() info for BFS_STAT_NOFOLLOW. */
struct bftw_stat lstat_cache;
/** Cached bfs_stat() info for BFS_STAT_FOLLOW. */
struct bftw_stat stat_cache;
};
/**
* Get bfs_stat() info for a file encountered during bftw(), caching the result
* whenever possible.
*
* @param ftwbuf
* bftw() data for the file to stat.
* @param flags
* flags for bfs_stat(). Pass ftwbuf->stat_flags for the default flags.
* @return
* A pointer to a bfs_stat() buffer, or NULL if the call failed.
*/
const struct bfs_stat *bftw_stat(const struct BFTW *ftwbuf, enum bfs_stat_flags flags);
/**
* Get bfs_stat() info for a file encountered during bftw(), if it has already
* been cached.
*
* @param ftwbuf
* bftw() data for the file to stat.
* @param flags
* flags for bfs_stat(). Pass ftwbuf->stat_flags for the default flags.
* @return
* A pointer to a bfs_stat() buffer, or NULL if no stat info is cached.
*/
const struct bfs_stat *bftw_cached_stat(const struct BFTW *ftwbuf, enum bfs_stat_flags flags);
/**
* Get the type of a file encountered during bftw(), with flags controlling
* whether to follow links. This function will avoid calling bfs_stat() if
* possible.
*
* @param ftwbuf
* bftw() data for the file to check.
* @param flags
* flags for bfs_stat(). Pass ftwbuf->stat_flags for the default flags.
* @return
* The type of the file, or BFTW_ERROR if an error occurred.
*/
enum bfs_type bftw_type(const struct BFTW *ftwbuf, enum bfs_stat_flags flags);
/**
* Walk actions returned by the bftw() callback.
*/
enum bftw_action {
/** Keep walking. */
BFTW_CONTINUE,
/** Skip this path's children. */
BFTW_PRUNE,
/** Stop walking. */
BFTW_STOP,
};
/**
* Callback function type for bftw().
*
* @param ftwbuf
* Data about the current file.
* @param ptr
* The pointer passed to bftw().
* @return
* An action value.
*/
typedef enum bftw_action bftw_callback(const struct BFTW *ftwbuf, void *ptr);
/**
* Flags that control bftw() behavior.
*/
enum bftw_flags {
/** stat() each encountered file. */
BFTW_STAT = 1 << 0,
/** Attempt to recover from encountered errors. */
BFTW_RECOVER = 1 << 1,
/** Visit directories in post-order as well as pre-order. */
BFTW_POST_ORDER = 1 << 2,
/** If the initial path is a symbolic link, follow it. */
BFTW_FOLLOW_ROOTS = 1 << 3,
/** Follow all symbolic links. */
BFTW_FOLLOW_ALL = 1 << 4,
/** Detect directory cycles. */
BFTW_DETECT_CYCLES = 1 << 5,
/** Skip mount points and their descendents. */
BFTW_SKIP_MOUNTS = 1 << 6,
/** Skip the descendents of mount points. */
BFTW_PRUNE_MOUNTS = 1 << 7,
/** Sort directory entries before processing them. */
BFTW_SORT = 1 << 8,
/** Read each directory into memory before processing its children. */
BFTW_BUFFER = 1 << 9,
};
/**
* Tree search strategies for bftw().
*/
enum bftw_strategy {
/** Breadth-first search. */
BFTW_BFS,
/** Depth-first search. */
BFTW_DFS,
/** Iterative deepening search. */
BFTW_IDS,
/** Exponential deepening search. */
BFTW_EDS,
};
/**
* Structure for holding the arguments passed to bftw().
*/
struct bftw_args {
/** The path(s) to start from. */
const char **paths;
/** The number of starting paths. */
size_t npaths;
/** The callback to invoke. */
bftw_callback *callback;
/** A pointer which is passed to the callback. */
void *ptr;
/** The maximum number of file descriptors to keep open. */
int nopenfd;
/** Flags that control bftw() behaviour. */
enum bftw_flags flags;
/** The search strategy to use. */
enum bftw_strategy strategy;
/** The parsed mount table, if available. */
const struct bfs_mtab *mtab;
};
/**
* Breadth First Tree Walk (or Better File Tree Walk).
*
* Like ftw(3) and nftw(3), this function walks a directory tree recursively,
* and invokes a callback for each path it encounters.
*
* @param args
* The arguments that control the walk.
* @return
* 0 on success, or -1 on failure.
*/
int bftw(const struct bftw_args *args);
#endif // BFS_BFTW_H
|
