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