path: root/static/openbsd/man3/fuse_opt.3

.\"	$OpenBSD: fuse_opt.3,v 1.9 2026/03/14 10:47:00 helg Exp $
.\"
.\" Copyright (c) Ray Lai <ray@raylai.com>
.\" Copyright (c) Helg Bredow <helg@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: March 14 2026 $
.Dt FUSE_OPT 3
.Os
.Sh NAME
.Nm FUSE_ARGS_INIT ,
.Nm FUSE_OPT_IS_OPT_KEY ,
.Nm FUSE_OPT_KEY ,
.Nm FUSE_OPT_END ,
.Nm fuse_opt_add_arg ,
.Nm fuse_opt_insert_arg ,
.Nm fuse_opt_add_opt ,
.Nm fuse_opt_add_opt_escaped ,
.Nm fuse_opt_free_args ,
.Nm fuse_opt_match ,
.Nm fuse_opt_parse
.Nd FUSE argument and option parser
.Sh SYNOPSIS
.Lb libfuse
.In fuse_opt.h
.Ft struct fuse_args
.Fo FUSE_ARGS_INIT
.Fa "int argc"
.Fa "char argv**"
.Fc
.Ft int
.Fo FUSE_OPT_IS_OPT_KEY
.Fa "fuse_opt *t"
.Fc
.Ft struct fuse_opt
.Fo FUSE_OPT_KEY
.Fa "const char *templ"
.Fa "int key"
.Fc
.Ft struct fuse_opt
.Fn FUSE_OPT_END
.Ft int
.Fo fuse_opt_add_arg
.Fa "struct fuse_args *args"
.Fa "const char *arg"
.Fc
.Ft int
.Fo fuse_opt_insert_arg
.Fa "struct fuse_args *args"
.Fa "int pos"
.Fa "const char *opt"
.Fc
.Ft int
.Fo fuse_opt_add_opt
.Fa "char **opts"
.Fa "const char *opt"
.Fc
.Ft int
.Fo fuse_opt_add_opt_escaped
.Fa "char **opts"
.Fa "const char *opt"
.Fc
.Ft void
.Fo fuse_opt_free_args
.Fa "struct fuse_args *args"
.Fc
.Ft int
.Fo fuse_opt_match
.Fa "const struct fuse_opt *opts"
.Fa "const char *opt"
.Fc
.Ft int
.Fo fuse_opt_parse
.Fa "struct fuse_args *args"
.Fa "void *data"
.Fa "const struct fuse_opt *opts"
.Fa "fuse_opt_proc_t proc"
.Fc
.Ft typedef int
.Fo (*fuse_opt_proc_t)
.Fa "void *data"
.Fa "const char *arg"
.Fa "int key"
.Fa "struct fuse_args *outargs"
.Fc
.Sh 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
.Xr fuse_mount 3
and
.Xr fuse_new 3
functions.
.Ft struct fuse_args
holds string options in an array:
.Bd -literal -offset indent
struct fuse_args {
        int argc;	/* argument count */
        char **argv;	/* NULL-terminated array of arguments */
        int allocated;	/* argv was allocated and must be freed */
};
.Ed
.Pp
.Bl -tag -width Ds -compact
.It Fn FUSE_ARGS_INIT
initializes a
.Ft struct fuse_args
with
.Fa argc
and
.Fa argv ,
which are usually obtained from
.Fn main .
.Fa argv
is
.Dv NULL Ns -terminated ,
and is suitable for use with
.Xr execvp 3 .
.Fa argv
is used directly and
.Fa allocated
is set to 0.
.Pp
.It Fn fuse_opt_add_arg
adds a single option to the end of
.Fa args .
If
.Fa args->allocated
is 0,
.Fa args->argv
is copied to the heap and
.Fa args->allocated
is set to a non-zero value.
.Pp
.It Fn fuse_opt_insert_arg
inserts a single argument at position
.Fa pos
into
.Fa args ,
shifting
.Fa args->argv
as needed.
.Pp
.It Fn fuse_opt_free_args
If
.Fa args
is allocated, free
.Fa args->argv
and zero all members of
.Fa args .
Otherwise, do nothing.
.Pp
.It Fn FUSE_OPT_KEY templ key
Return a
.Fa struct fuse_opt
template that matches an argument or option
.Vt templ
with option key
.Vt key .
This macro is used as an element in
.Fa struct fuse_opt
arrays to create a template that is processed by a
.Vt fuse_opt_proc_t .
The special constants
.Dv FUSE_OPT_KEY_KEEP
and
.Dv FUSE_OPT_KEY_DISCARD
can be specified for
.Fa val
if
.Fa proc
does not need to handle this option or argument;
.Fa proc
is not called in this case.
.Bd -literal -offset indent
struct fuse_opt {
        const char *templ;	/* template for option */
        unsigned long off;	/* data offset */
        int val;		/* key value */
};
.Ed
.Pp
The following special key values can be used for
.Fa val :
.Bd -literal -offset indent
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 */
.Ed
.It Fn FUSE_OPT_END
The last element of each
.Fa "struct fuse_opt *opts"
array passed to any function must be
.Dv FUSE_OPT_END .
.Pp
.It Fn FUSE_OPT_IS_OPT_KEY templ
Check whether
.Fa templ
is an option key.
.Pp
.It Fn fuse_opt_add_opt
adds an option
.Fa opt
to a comma-separated string of options
.Fa opts .
.Fa *opts
can be
.Dv NULL ,
which is typically used when adding the first option.
.Pp
.It Fn fuse_opt_add_opt_escaped
escapes any
.Sq ,\&
and
.Sq \e
characters in
.Fa opt
before adding it to
.Fa opts .
.Pp
.It Fn fuse_opt_match
tests if the argument or option
.Fa opt
appears in the list of templates
.Fa opts .
If
.Fa opt
is an option then it must not include the -o prefix.
.Pp
.It Fn fuse_opt_parse
parses options, setting any members of
.Fa data
automatically depending on the format of the template.
If
.Fa proc
is not
.Dv NULL ,
then this is called for any argument that matches a template
that has
.Fa offset No = Dv FUSE_OPT_KEY_OPT .
.Fa opts
is an array of
.Ft struct fuse_opt ,
each of which describes actions for each option:
.Pp
The following templates are supported as options and must be preceded by
.Fl o
in the list of arguments, with or without a space between
.Fl o
and the option.
If multiple options are specified they can be comma separated or specified
individually with
.Fl o
each time.
For example, these are all valid:
.Bd -unfilled -offset indent
.Fl o Ar foo
.Sm off
.Fl o Ar bar
.Fl o Ar foo , bar
.Sm on
.Ed
.Pp
foo matches exactly
.Pp
foo= matches exactly
.Pp
foo=bar matches the option exactly (treated the same as if it didn't have an =).
.Pp
foo=%u %u can be any format that can be parsed by
.Fn sscanf 3 .
If this is %s then a copy of the string is allocated.
.Pp
Arguments
.Pp
-b or --bar matches the argument and sets the value of the struct at offset
to key.
.Pp
.Qq Fl b Ns \ \&
or
.Qq Fl \-bar Ns \ \&
(trailing space) argument expects a value, the whole argument,
including -b, is passed to
.Fa proc
.Pp
.Qq Fl b Ar %u
or
.Qq Fl \-bar Ar %u
is treated the same as foo=%u above
.Pp
Each argument or option is matched against every template.
This allows more than one member of
.Fa data
to be set by a single argument or option (see example for gid below).
.Pp
.It Fn fuse_opt_proc_t
The fuse_opt_proc_t function takes the following arguments.
.Bl -tag -width Ds
.It Fa data
data argument passed to
.Fn fuse_opt_parse
.It Fa arg
the whole argument or option
.It Fa key
is the key defined with the option or one of the special keys.
.It Fa outargs
The current list of arguments
.El
.El
.Sh RETURN VALUES
.Fn fuse_opt_add_arg ,
.Fn fuse_opt_insert_arg ,
.Fn fuse_opt_add_opt ,
.Fn fuse_opt_add_opt_escaped ,
and
.Fn fuse_opt_parse
return 0 on success or \-1 on error.
.Pp
.Fn fuse_opt_match
returns 1 on match or 0 if no match.
.Pp
The
.Fn 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
.Fn fuse_opt_parse
to terminate with failure.
.Sh EXAMPLES
.Bd -literal
#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\en", config.foo);
	printf("toggle=%d\en", config.toggle);
	printf("bar=%d\en", config.bar);
	printf("set_gid=%d\en", config.set_gid);
	printf("gid=%u\en", config.gid);
}
.Ed
.Sh ERRORS
.Fn fuse_opt_add_arg ,
.Fn fuse_opt_insert_arg ,
.Fn fuse_opt_add_opt ,
and
.Fn fuse_opt_add_opt_escaped
can run out of memory and set
.Va errno .
.Sh SEE ALSO
.Xr fuse_main 3
.Sh STANDARDS
These library functions conform to FUSE 2.6.
.Sh HISTORY
These functions first appeared in
.Ox 5.4 .
.Sh AUTHORS
.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com
.An Helg Bredow Aq Mt helg@openbsd.org
.Pp
This manual was written by
.An Ray Lai Aq Mt ray@raylai.com
and updated by
.An Helg Bredow Aq Mt helg@openbsd.org