"Fossies" - the Fresh Open Source Software Archive

Member "fuse-3.2.1/include/fuse_opt.h" (14 Nov 2017, 7549 Bytes) of package /linux/misc/fuse-3.2.1.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "fuse_opt.h" see the Fossies "Dox" file reference documentation.

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