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