FUSE_OPT(3)

NAME
FUSE_ARGS_INIT, FUSE_OPT_IS_OPT_KEY, FUSE_OPT_KEY, FUSE_OPT_END, fuse_opt_add_arg, fuse_opt_insert_arg, fuse_opt_add_opt, fuse_opt_add_opt_escaped, fuse_opt_free_args, fuse_opt_match, fuse_opt_parse - FUSE argument and option parser

SYNOPSIS
libfuse
#include <fuse_opt.h>
struct fuse_args
FUSE_ARGS_INIT(int argc, char argv**);
int
FUSE_OPT_IS_OPT_KEY(fuse_opt *t);
struct fuse_opt
FUSE_OPT_KEY(const char *templ, int key);
struct fuse_opt
FUSE_OPT_END();
int
fuse_opt_add_arg(struct fuse_args *args, const char *arg);
int
fuse_opt_insert_arg(struct fuse_args *args, int pos, const char *opt);
int
fuse_opt_add_opt(char **opts, const char *opt);
int
fuse_opt_add_opt_escaped(char **opts, const char *opt);
void
fuse_opt_free_args(struct fuse_args *args);
int
fuse_opt_match(const struct fuse_opt *opts, const char *opt);
int
fuse_opt_parse(struct fuse_args *args, void *data, const struct fuse_opt *opts, fuse_opt_proc_t proc);
typedef int
(*fuse_opt_proc_t)(void *data, const char *arg, int key, struct fuse_args *outargs);

DESCRIPTION
These FUSE library functions and macros provide support for complex argument and option parsing. These are typically entered on the command line but may also be passed by file systems to the fuse_mount(3) and fuse_new(3) functions. struct fuse_args holds string options in an array:

    struct fuse_args {
            int argc;	/* argument count */
            char **argv;	/* NULL-terminated array of arguments */
            int allocated;	/* argv was allocated and must be freed */
    };

FUSE_ARGS_INIT()
    initializes a struct fuse_args with argc and argv, which are usually obtained from main(). argv is NULL-terminated, and is suitable for use with execvp(3). argv is used directly and allocated is set to 0.

fuse_opt_add_arg()
    adds a single option to the end of args. If args->allocated is 0, args->argv is copied to the heap and args->allocated is set to a non-zero value.

fuse_opt_insert_arg()
    inserts a single argument at position pos into args, shifting args->argv as needed.

fuse_opt_free_args()
    If args is allocated, free args->argv and zero all members of args. Otherwise, do nothing.

FUSE_OPT_KEY(templ, key)
    Return a struct fuse_opt template that matches an argument or option templ with option key key. This macro is used as an element in struct fuse_opt arrays to create a template that is processed by a fuse_opt_proc_t. The special constants FUSE_OPT_KEY_KEEP and FUSE_OPT_KEY_DISCARD can be specified for val if proc does not need to handle this option or argument; proc is not called in this case.

        struct fuse_opt {
                const char *templ;	/* template for option */
                unsigned long off;	/* data offset */
                int val;		/* key value */
        };

    The following special key values can be used for val:

        FUSE_OPT_KEY_OPT	/* no match */
        FUSE_OPT_KEY_NONOPT	/* non-option */
        FUSE_OPT_KEY_KEEP	/* don't process; return 1 */
        FUSE_OPT_KEY_DISCARD	/* don't process; return 0 */

FUSE_OPT_END()
    The last element of each struct fuse_opt *opts array passed to any function must be FUSE_OPT_END.

FUSE_OPT_IS_OPT_KEY(templ)
    Check whether templ is an option key.

fuse_opt_add_opt()
    adds an option opt to a comma-separated string of options opts. *opts can be NULL, which is typically used when adding the first option.

fuse_opt_add_opt_escaped()
    escapes any ‘’, and ‘\’ characters in opt before adding it to opts.

fuse_opt_match()
    tests if the argument or option opt appears in the list of templates opts. If opt is an option then it must not include the -o prefix.

fuse_opt_parse()
    parses options, setting any members of data automatically depending on the format of the template. If proc is not NULL, then this is called for any argument that matches a template that has offset = FUSE_OPT_KEY_OPT. opts is an array of struct fuse_opt, each of which describes actions for each option:

    The following templates are supported as options and must be preceded by -o in the list of arguments, with or without a space between -o and the option. If multiple options are specified they can be comma separated or specified individually with -o each time. For example, these are all valid:

        -o foo
        -obar
        -ofoo,bar

    foo matches exactly

    foo= matches exactly

    foo=bar matches the option exactly (treated the same as if it didn't have an =).

    foo=%u %u can be any format that can be parsed by sscanf(3). If this is %s then a copy of the string is allocated.

    Arguments

    -b or --bar matches the argument and sets the value of the struct at offset to key.

    "-b " or "--bar " (trailing space) argument expects a value, the whole argument, including -b, is passed to proc

    "-b %u" or "--bar %u" is treated the same as foo=%u above

    Each argument or option is matched against every template. This allows more than one member of data to be set by a single argument or option (see example for gid below).

fuse_opt_proc_t()
    The fuse_opt_proc_t function takes the following arguments.

    data
        data argument passed to fuse_opt_parse()

    arg the whole argument or option

    key is the key defined with the option or one of the special keys.

    outargs
        The current list of arguments

RETURN VALUES
fuse_opt_add_arg(), fuse_opt_insert_arg(), fuse_opt_add_opt(), fuse_opt_add_opt_escaped(), and fuse_opt_parse() return 0 on success or -1 on error.

fuse_opt_match() returns 1 on match or 0 if no match.

The fuse_opt_proc_t() callback shall return 1 to retain the option in the output argument vector, or 0 to discard it. This permits options to be preserved for subsequent processing. A return value of -1 indicates an error condition and causes fuse_opt_parse() to terminate with failure.

EXAMPLES

    #include <err.h>
    #include <fuse.h>
    #include <stddef.h>
    #include <stdio.h>
    #include <string.h>
    enum {
    	KEY_FOO
    };
    struct foo_config {
    	char *foo;
    	int bar;
    	gid_t gid;
    	int set_gid;
    	int toggle;
    };
    #define FOO_OPT(t, m) {t, offsetof(struct foo_config, m), 1}
    struct fuse_opt opts[] = {
    	FUSE_OPT_KEY("--foo ", KEY_FOO),/* passed to foo_opt_proc() */
    	FOO_OPT("-b", bar),		/* set to 1 if present */
    	FOO_OPT("toggle", toggle),	/* set to 1 if present */
    	FOO_OPT("gid=", set_gid),	/* set to 1 if present */
    	FOO_OPT("gid=%u", gid),		/* set to parsed value of %u */
    	FUSE_OPT_END
    };
    int
    foo_opt_proc(void *data, const char *val, int key, struct fuse_args *args)
    {
    	struct foo_config *conf = data;
    	switch(key)
    	{
    	case KEY_FOO:
    		conf->foo = strdup(val);
    		return (0); /* discard */
    	}
    	/* didn't process, so keep the option */
    	return (1);
    }
    int
    main(int argc, char *argv[])
    {
    	struct fuse_args args = FUSE_ARGS_INIT(argc, argv);
    	struct foo_config config;
    	memset(&config, 0, sizeof(config));
    	if (fuse_opt_parse(&args, &config, opts, foo_opt_proc) == -1)
    		err(1, "Usage: prog [foo=value] [-b] "
    		    "[-o [gid=value],[toggle]]");
    	printf("foo=%s\n", config.foo);
    	printf("toggle=%d\n", config.toggle);
    	printf("bar=%d\n", config.bar);
    	printf("set_gid=%d\n", config.set_gid);
    	printf("gid=%u\n", config.gid);
    }

ERRORS
fuse_opt_add_arg(), fuse_opt_insert_arg(), fuse_opt_add_opt(), and fuse_opt_add_opt_escaped() can run out of memory and set errno.

SEE ALSO
fuse_main(3)

STANDARDS
These library functions conform to FUSE 2.6.

HISTORY
These functions first appeared in OpenBSD 5.4.

AUTHORS
Sylvestre Gallon <ccna.syl@gmail.com> Helg Bredow <helg@openbsd.org>

This manual was written by Ray Lai <ray@raylai.com> and updated by Helg Bredow <helg@openbsd.org>