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
|
/****************************************************************************
* bfs *
* Copyright (C) 2015-2019 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 "stat.h"
#include <stddef.h>
/**
* Possible file types.
*/
enum bftw_typeflag {
/** Unknown type. */
BFTW_UNKNOWN = 0,
/** Block device. */
BFTW_BLK = 1 << 0,
/** Character device. */
BFTW_CHR = 1 << 1,
/** Directory. */
BFTW_DIR = 1 << 2,
/** Solaris door. */
BFTW_DOOR = 1 << 3,
/** Pipe. */
BFTW_FIFO = 1 << 4,
/** Symbolic link. */
BFTW_LNK = 1 << 5,
/** Solaris event port. */
BFTW_PORT = 1 << 6,
/** Regular file. */
BFTW_REG = 1 << 7,
/** Socket. */
BFTW_SOCK = 1 << 8,
/** BSD whiteout. */
BFTW_WHT = 1 << 9,
/** An error occurred for this file. */
BFTW_ERROR = 1 << 10,
};
/**
* Convert a bfs_stat() mode to a bftw() typeflag.
*/
enum bftw_typeflag bftw_mode_typeflag(mode_t mode);
/**
* Possible visit occurrences.
*/
enum bftw_visit {
/** Pre-order visit. */
BFTW_PRE,
/** Post-order visit. */
BFTW_POST,
};
/**
* 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 bftw_typeflag typeflag;
/** The errno that occurred, if typeflag == BFTW_ERROR. */
int error;
/** A bfs_stat() buffer; may be NULL if no stat() call was needed. */
const struct bfs_stat *statbuf;
/** A parent file descriptor for the *at() family of calls. */
int at_fd;
/** The path relative to atfd for the *at() family of calls. */
const char *at_path;
/** Appropriate flags (such as AT_SYMLINK_NOFOLLOW) for the *at() family of calls. */
int at_flags;
};
/**
* Walk actions returned by the bftw() callback.
*/
enum bftw_action {
/** Keep walking. */
BFTW_CONTINUE,
/** Skip this path's siblings. */
BFTW_SKIP_SIBLINGS,
/** Skip this path's children. */
BFTW_SKIP_SUBTREE,
/** 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(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_DEPTH = 1 << 2,
/** If the initial path is a symbolic link, follow it. */
BFTW_COMFOLLOW = 1 << 3,
/** Follow all symbolic links. */
BFTW_LOGICAL = 1 << 4,
/** Detect directory cycles. */
BFTW_DETECT_CYCLES = 1 << 5,
/** Stay on the same filesystem. */
BFTW_XDEV = 1 << 6,
};
/**
* Structure for holding the arguments passed to bftw().
*/
struct bftw_args {
/** 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;
};
/**
* 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. However, bftw() operates
* breadth-first.
*
* @param path
* The starting path.
* @param args
* The arguments that control the walk.
* @return
* 0 on success, or -1 on failure.
*/
int bftw(const char *path, const struct bftw_args *args);
#endif // BFS_BFTW_H
|
