capstone: Update to upstream "next" branch
[qemu.git] / tools / virtiofsd / fuse_opt.h
1 /*
2 * FUSE: Filesystem in Userspace
3 * Copyright (C) 2001-2007 Miklos Szeredi <miklos@szeredi.hu>
4 *
5 * This program can be distributed under the terms of the GNU LGPLv2.
6 * See the file COPYING.LIB.
7 */
8
9 #ifndef FUSE_OPT_H_
10 #define FUSE_OPT_H_
11
12 /** @file
13 *
14 * This file defines the option parsing interface of FUSE
15 */
16
17 /**
18 * Option description
19 *
20 * This structure describes a single option, and action associated
21 * with it, in case it matches.
22 *
23 * More than one such match may occur, in which case the action for
24 * each match is executed.
25 *
26 * There are three possible actions in case of a match:
27 *
28 * i) An integer (int or unsigned) variable determined by 'offset' is
29 * set to 'value'
30 *
31 * ii) The processing function is called, with 'value' as the key
32 *
33 * iii) An integer (any) or string (char *) variable determined by
34 * 'offset' is set to the value of an option parameter
35 *
36 * 'offset' should normally be either set to
37 *
38 * - 'offsetof(struct foo, member)' actions i) and iii)
39 *
40 * - -1 action ii)
41 *
42 * The 'offsetof()' macro is defined in the <stddef.h> header.
43 *
44 * The template determines which options match, and also have an
45 * effect on the action. Normally the action is either i) or ii), but
46 * if a format is present in the template, then action iii) is
47 * performed.
48 *
49 * The types of templates are:
50 *
51 * 1) "-x", "-foo", "--foo", "--foo-bar", etc. These match only
52 * themselves. Invalid values are "--" and anything beginning
53 * with "-o"
54 *
55 * 2) "foo", "foo-bar", etc. These match "-ofoo", "-ofoo-bar" or
56 * the relevant option in a comma separated option list
57 *
58 * 3) "bar=", "--foo=", etc. These are variations of 1) and 2)
59 * which have a parameter
60 *
61 * 4) "bar=%s", "--foo=%lu", etc. Same matching as above but perform
62 * action iii).
63 *
64 * 5) "-x ", etc. Matches either "-xparam" or "-x param" as
65 * two separate arguments
66 *
67 * 6) "-x %s", etc. Combination of 4) and 5)
68 *
69 * If the format is "%s", memory is allocated for the string unlike with
70 * scanf(). The previous value (if non-NULL) stored at the this location is
71 * freed.
72 */
73 struct fuse_opt {
74 /** Matching template and optional parameter formatting */
75 const char *templ;
76
77 /**
78 * Offset of variable within 'data' parameter of fuse_opt_parse()
79 * or -1
80 */
81 unsigned long offset;
82
83 /**
84 * Value to set the variable to, or to be passed as 'key' to the
85 * processing function. Ignored if template has a format
86 */
87 int value;
88 };
89
90 /**
91 * Key option. In case of a match, the processing function will be
92 * called with the specified key.
93 */
94 #define FUSE_OPT_KEY(templ, key) \
95 { \
96 templ, -1U, key \
97 }
98
99 /**
100 * Last option. An array of 'struct fuse_opt' must end with a NULL
101 * template value
102 */
103 #define FUSE_OPT_END \
104 { \
105 NULL, 0, 0 \
106 }
107
108 /**
109 * Argument list
110 */
111 struct fuse_args {
112 /** Argument count */
113 int argc;
114
115 /** Argument vector. NULL terminated */
116 char **argv;
117
118 /** Is 'argv' allocated? */
119 int allocated;
120 };
121
122 /**
123 * Initializer for 'struct fuse_args'
124 */
125 #define FUSE_ARGS_INIT(argc, argv) \
126 { \
127 argc, argv, 0 \
128 }
129
130 /**
131 * Key value passed to the processing function if an option did not
132 * match any template
133 */
134 #define FUSE_OPT_KEY_OPT -1
135
136 /**
137 * Key value passed to the processing function for all non-options
138 *
139 * Non-options are the arguments beginning with a character other than
140 * '-' or all arguments after the special '--' option
141 */
142 #define FUSE_OPT_KEY_NONOPT -2
143
144 /**
145 * Special key value for options to keep
146 *
147 * Argument is not passed to processing function, but behave as if the
148 * processing function returned 1
149 */
150 #define FUSE_OPT_KEY_KEEP -3
151
152 /**
153 * Special key value for options to discard
154 *
155 * Argument is not passed to processing function, but behave as if the
156 * processing function returned zero
157 */
158 #define FUSE_OPT_KEY_DISCARD -4
159
160 /**
161 * Processing function
162 *
163 * This function is called if
164 * - option did not match any 'struct fuse_opt'
165 * - argument is a non-option
166 * - option did match and offset was set to -1
167 *
168 * The 'arg' parameter will always contain the whole argument or
169 * option including the parameter if exists. A two-argument option
170 * ("-x foo") is always converted to single argument option of the
171 * form "-xfoo" before this function is called.
172 *
173 * Options of the form '-ofoo' are passed to this function without the
174 * '-o' prefix.
175 *
176 * The return value of this function determines whether this argument
177 * is to be inserted into the output argument vector, or discarded.
178 *
179 * @param data is the user data passed to the fuse_opt_parse() function
180 * @param arg is the whole argument or option
181 * @param key determines why the processing function was called
182 * @param outargs the current output argument list
183 * @return -1 on error, 0 if arg is to be discarded, 1 if arg should be kept
184 */
185 typedef int (*fuse_opt_proc_t)(void *data, const char *arg, int key,
186 struct fuse_args *outargs);
187
188 /**
189 * Option parsing function
190 *
191 * If 'args' was returned from a previous call to fuse_opt_parse() or
192 * it was constructed from
193 *
194 * A NULL 'args' is equivalent to an empty argument vector
195 *
196 * A NULL 'opts' is equivalent to an 'opts' array containing a single
197 * end marker
198 *
199 * A NULL 'proc' is equivalent to a processing function always
200 * returning '1'
201 *
202 * @param args is the input and output argument list
203 * @param data is the user data
204 * @param opts is the option description array
205 * @param proc is the processing function
206 * @return -1 on error, 0 on success
207 */
208 int fuse_opt_parse(struct fuse_args *args, void *data,
209 const struct fuse_opt opts[], fuse_opt_proc_t proc);
210
211 /**
212 * Add an option to a comma separated option list
213 *
214 * @param opts is a pointer to an option list, may point to a NULL value
215 * @param opt is the option to add
216 * @return -1 on allocation error, 0 on success
217 */
218 int fuse_opt_add_opt(char **opts, const char *opt);
219
220 /**
221 * Add an option, escaping commas, to a comma separated option list
222 *
223 * @param opts is a pointer to an option list, may point to a NULL value
224 * @param opt is the option to add
225 * @return -1 on allocation error, 0 on success
226 */
227 int fuse_opt_add_opt_escaped(char **opts, const char *opt);
228
229 /**
230 * Add an argument to a NULL terminated argument vector
231 *
232 * @param args is the structure containing the current argument list
233 * @param arg is the new argument to add
234 * @return -1 on allocation error, 0 on success
235 */
236 int fuse_opt_add_arg(struct fuse_args *args, const char *arg);
237
238 /**
239 * Add an argument at the specified position in a NULL terminated
240 * argument vector
241 *
242 * Adds the argument to the N-th position. This is useful for adding
243 * options at the beginning of the array which must not come after the
244 * special '--' option.
245 *
246 * @param args is the structure containing the current argument list
247 * @param pos is the position at which to add the argument
248 * @param arg is the new argument to add
249 * @return -1 on allocation error, 0 on success
250 */
251 int fuse_opt_insert_arg(struct fuse_args *args, int pos, const char *arg);
252
253 /**
254 * Free the contents of argument list
255 *
256 * The structure itself is not freed
257 *
258 * @param args is the structure containing the argument list
259 */
260 void fuse_opt_free_args(struct fuse_args *args);
261
262
263 /**
264 * Check if an option matches
265 *
266 * @param opts is the option description array
267 * @param opt is the option to match
268 * @return 1 if a match is found, 0 if not
269 */
270 int fuse_opt_match(const struct fuse_opt opts[], const char *opt);
271
272 #endif /* FUSE_OPT_H_ */