compat/fuse_opt.h

   1 /*
   2     FUSE: Filesystem in Userspace
   3     Copyright (C) 2001-2006  Miklos Szeredi <miklos@szeredi.hu>
   4
   5     This file is borrowed from sshfs-fuse. It provides an implementation
   6     of the FUSE command line parsing functions which only appear in
   7     later version of FUSE but are used in afuse.
   8
   9     This file can be distributed under the terms of the GNU LGPL.
  10     See the file COPYING.LIB
  11 */
  12
  13 #ifndef _FUSE_OPT_H_
  14 #define _FUSE_OPT_H_
  15
  16 /* This file defines the option parsing interface of FUSE */
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 /**
  23  * Option description
  24  *
  25  * This structure describes a single option, and and action associated
  26  * with it, in case it matches.
  27  *
  28  * More than one such match may occur, in which case the action for
  29  * each match is executed.
  30  *
  31  * There are three possible actions in case of a match:
  32  *
  33  * i) An integer (int or unsigned) variable determined by 'offset' is
  34  *    set to 'value'
  35  *
  36  * ii) The processing function is called, with 'value' as the key
  37  *
  38  * iii) An integer (any) or string (char *) variable determined by
  39  *    'offset' is set to the value of an option parameter
  40  *
  41  * 'offset' should normally be either set to
  42  *
  43  *  - 'offsetof(struct foo, member)'  actions i) and iii)
  44  *
  45  *  - -1                              action ii)
  46  *
  47  * The 'offsetof()' macro is defined in the <stddef.h> header.
  48  *
  49  * The template determines which options match, and also have an
  50  * effect on the action.  Normally the action is either i) or ii), but
  51  * if a format is present in the template, then action iii) is
  52  * performed.
  53  *
  54  * The types of templates are:
  55  *
  56  * 1) "-x", "-foo", "--foo", "--foo-bar", etc.  These match only
  57  *   themselves.  Invalid values are "--" and anything beginning
  58  *   with "-o"
  59  *
  60  * 2) "foo", "foo-bar", etc.  These match "-ofoo", "-ofoo-bar" or
  61  *    the relevant option in a comma separated option list
  62  *
  63  * 3) "bar=", "--foo=", etc.  These are variations of 1) and 2)
  64  *    which have a parameter
  65  *
  66  * 4) "bar=%s", "--foo=%lu", etc.  Same matching as above but perform
  67  *    action iii).
  68  *
  69  * 5) "-x ", etc.  Matches either "-xparam" or "-x param" as
  70  *    two separate arguments
  71  *
  72  * 6) "-x %s", etc.  Combination of 4) and 5)
  73  *
  74  * If the format is "%s", memory is allocated for the string unlike
  75  * with scanf().
  76  */
  77 struct fuse_opt {
  78     /** Matching template and optional parameter formatting */
  79     const char *template;
  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 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(template, key) { template, -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 { .template = NULL }
 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 templated
 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 charater other than
 135  * '-' or all arguments after the special '--' option
 136  */
 137 #define FUSE_OPT_KEY_NONOPT  -2
 138
 139 /**
 140  * Processing function
 141  *
 142  * This function is called if
 143  *    - option did not match any 'struct fuse_opt'
 144  *    - argument is a non-option
 145  *    - option did match and offset was set to -1
 146  *
 147  * The 'arg' parameter will always contain the whole argument or
 148  * option including the parameter if exists.  A two-argument option
 149  * ("-x foo") is always converted to single arguemnt option of the
 150  * form "-xfoo" before this function is called.
 151  *
 152  * Options of the form '-ofoo' are passed to this function without the
 153  * '-o' prefix.
 154  *
 155  * The return value of this function determines whether this argument
 156  * is to be inserted into the output argument vector, or discarded.
 157  *
 158  * @param data is the user data passed to the fuse_opt_parse() function
 159  * @param arg is the whole argument or option
 160  * @param key determines why the processing function was called
 161  * @param outargs the current output argument list
 162  * @return -1 on error, 0 if arg is to be discarded, 1 if arg should be kept
 163  */
 164 typedef int (*fuse_opt_proc_t)(void *data, const char *arg, int key,
 165                                struct fuse_args *outargs);
 166
 167 /**
 168  * Option parsing function
 169  *
 170  * If 'args' was returned from a previous call to fuse_opt_parse() or
 171  * it was constructed from
 172  *
 173  * A NULL 'args' is equivalent to an empty argument vector
 174  *
 175  * A NULL 'opts' is equivalent to an 'opts' array containing a single
 176  * end marker
 177  *
 178  * A NULL 'proc' is equivalent to a processing function always
 179  * returning '1'
 180  *
 181  * @param args is the input and output argument list
 182  * @param data is the user data
 183  * @param opts is the option description array
 184  * @param proc is the processing function
 185  * @return -1 on error, 0 on success
 186  */
 187 int fuse_opt_parse(struct fuse_args *args, void *data,
 188                    const struct fuse_opt opts[], fuse_opt_proc_t proc);
 189
 190 /**
 191  * Add an option to a comma separated option list
 192  *
 193  * @param opts is a pointer to an option list, may point to a NULL value
 194  * @param opt is the option to add
 195  * @return -1 on allocation error, 0 on success
 196  */
 197 int fuse_opt_add_opt(char **opts, const char *opt);
 198
 199 /**
 200  * Add an argument to a NULL terminated argument vector
 201  *
 202  * @param args is the structure containing the current argument list
 203  * @param arg is the new argument to add
 204  * @return -1 on allocation error, 0 on success
 205  */
 206 int fuse_opt_add_arg(struct fuse_args *args, const char *arg);
 207
 208 /**
 209  * Free the contents of argument list
 210  *
 211  * The structure itself is not freed
 212  *
 213  * @param args is the structure containing the argument list
 214  */
 215 void fuse_opt_free_args(struct fuse_args *args);
 216
 217
 218 /**
 219  * Check if an option matches
 220  *
 221  * @param opts is the option description array
 222  * @param opt is the option to match
 223  * @return 1 if a match is found, 0 if not
 224  */
 225 int fuse_opt_match(const struct fuse_opt opts[], const char *opt);
 226
 227 #ifdef __cplusplus
 228 }
 229 #endif
 230
 231 #endif /* _FUSE_OPT_H_ */