include/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 #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_ */