1.\" $OpenBSD: fuse_opt.3,v 1.3 2018/11/30 18:19:12 mpi Exp $ 2.\" 3.\" Copyright (c) Ray Lai <ray@raylai.com> 4.\" Copyright (c) Helg Bredow <helg@openbsd.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: November 30 2018 $ 19.Dt FUSE_OPT 3 20.Os 21.Sh NAME 22.Nm FUSE_ARGS_INIT , 23.Nm FUSE_OPT_IS_OPT_KEY , 24.Nm FUSE_OPT_KEY , 25.Nm fuse_opt_add_arg , 26.Nm fuse_opt_insert_arg , 27.Nm fuse_opt_add_opt , 28.Nm fuse_opt_add_opt_escaped , 29.Nm fuse_opt_free_args , 30.Nm fuse_opt_match , 31.Nm fuse_opt_parse 32.Nd FUSE argument and option parser 33.Sh SYNOPSIS 34.In fuse_opt.h 35.Ft struct fuse_args 36.Fo FUSE_ARGS_INIT 37.Fa "int argc" 38.Fa "char argv**" 39.Fc 40.Ft int 41.Fo FUSE_OPT_IS_OPT_KEY 42.Fa "fuse_opt *t" 43.Fc 44.Ft struct fuse_opt 45.Fo FUSE_OPT_KEY 46.Fa "const char *templ" 47.Fa "int key" 48.Fc 49.Ft int 50.Fo fuse_opt_add_arg 51.Fa "struct fuse_args *args" 52.Fa "const char *arg" 53.Fc 54.Ft int 55.Fo fuse_opt_insert_arg 56.Fa "struct fuse_args *args" 57.Fa "int pos" 58.Fa "const char *opt" 59.Fc 60.Ft int 61.Fo fuse_opt_add_opt 62.Fa "char **opts" 63.Fa "const char *opt" 64.Fc 65.Ft int 66.Fo fuse_opt_add_opt_escaped 67.Fa "char **opts" 68.Fa "const char *opt" 69.Fc 70.Ft void 71.Fo fuse_opt_free_args 72.Fa "struct fuse_args *args" 73.Fc 74.Ft int 75.Fo fuse_opt_match 76.Fa "const struct fuse_opt *opts" 77.Fa "const char *opt" 78.Fc 79.Ft int 80.Fo fuse_opt_parse 81.Fa "struct fuse_args *args" 82.Fa "void *data" 83.Fa "const struct fuse_opt *opts" 84.Fa "fuse_opt_proc_t proc" 85.Fc 86.Sh DESCRIPTION 87These FUSE library functions and macros provide support for complex 88argument and option parsing. 89These are typically entered on the command line 90but may also be passed by file systems to the 91.Xr fuse_mount 3 92and 93.Xr fuse_new 3 94functions. 95.Ft struct fuse_args 96holds string options in an array: 97.Bd -literal -offset indent 98struct fuse_args { 99 int argc; /* argument count */ 100 char **argv; /* NULL-terminated array of arguments */ 101 int allocated; /* argv was allocated and must be freed */ 102}; 103.Ed 104.Pp 105.Bl -tag -width Ds -compact 106.It Fn FUSE_OPT_KEY templ key 107returns a 108.Fa struct fuse_opt 109template that matches an argument or option 110.Fa templ 111with option key 112.Fa key . 113This macro is used as an element in 114.Fa struct fuse_opt 115arrays to create a template that is processed by a fuse_opt_proc_t. 116The special constants FUSE_OPT_KEEP and FUSE_OPT_DISCARD can be specified if 117proc does not need to handle this option or argument; proc is not called in 118this case. 119.Pp 120.It Fn FUSE_OPT_IS_OPT_KEY templ 121checks if 122.Fa templ 123is an option key. 124.Pp 125The last element of the 126.Fa opts 127.Ft struct fuse_opt 128option array must be 129.Dv FUSE_OPT_END . 130.Pp 131.Fa proc 132points to a function with the following signature: 133.Ft int (*fuse_opt_proc_t) 134.Fo proc 135.Fa "void *data" 136.Fa "const char *arg" 137.Fa "int key" 138.Fa "struct fuse_args *outargs" 139.Fc 140.Pp 141Special key values: 142.Bd -literal -offset indent 143FUSE_OPT_KEY_OPT /* no match */ 144FUSE_OPT_KEY_NONOPT /* non-option */ 145FUSE_OPT_KEY_KEEP /* don't process; return 1 */ 146FUSE_OPT_KEY_DISCARD /* don't process; return 0 */ 147.Ed 148.Pp 149.It Fn FUSE_ARGS_INIT 150initializes a 151.Ft struct fuse_args 152with 153.Fa argc 154and 155.Fa argv , 156which are usually obtained from 157.Fn main . 158.Fa argv 159is NULL-terminated, and is suitable for use with 160.Xr execvp 3 . 161.Fa argv 162is used directly and 163.Fa allocated 164is set to 0. 165.Pp 166.It Fn fuse_opt_add_arg 167adds a single option to the end of 168.Fa args . 169If 170.Fa args->allocated 171is 0, 172.Fa args->argv 173is copied to the heap and 174.Fa args->allocated 175is set to a non-zero value. 176.Pp 177.It Fn fuse_opt_insert_arg 178inserts a single argument at position 179.Fa pos 180into 181.Fa args , 182shifting 183.Fa args->argv 184as needed. 185.Pp 186.It Fn fuse_opt_add_opt 187adds an option 188.Fa opt 189to a comma-separated string of options 190.Fa opts . 191.Fa *opts 192can be NULL, which is typically used when adding the first option. 193.Pp 194.It Fn fuse_opt_add_opt_escaped 195escapes any 196.Sq "," 197and 198.Sq "\\" 199characters in 200.Fa opt 201before adding it to 202.Fa opts . 203.Pp 204.It Fn fuse_opt_free_args 205frees 206.Fa args->argv 207if it was allocated 208.Fa args 209and initializes everything to 0. 210.Pp 211.It Fn fuse_opt_match 212tests if the argument or option 213.Fa opt 214appears in the list of templates 215.Fa opts . 216If 217.Fa opt 218is an option then it must not include the -o prefix. 219.Pp 220.It Fn fuse_opt_parse 221parses options, setting any members of 222.Fa data 223automatically depending on the format of the template. 224If 225.Fa proc 226is not NULL, then this is called for any argument that matches a template 227that has 228.Fa val 229= FUSE_OPT_KEY. 230.Fa opts 231is an array of 232.Ft struct fuse_opt , 233each of which describes actions for each option: 234.Bd -literal -offset indent 235struct fuse_opt { 236 const char *templ; /* template for option */ 237 unsigned long off; /* data offset */ 238 int val; /* key value */ 239}; 240.Ed 241.Pp 242The following templates are supported. 243foo= 244.Pp 245foo=%u %u can be any format that can be parsed by 246.Fn sscanf 3 . 247If this is %s then a copy of the string is allocated. 248foo=bar matches the option exactly (treated the same as if it didn't have an =). 249.Pp 250foo matches exactly 251.Pp 252-b or --bar matches the argument 253"-b " or "--bar " (trailing space) argument expects a value, that is passed to 254.Fa proc 255.Pp 256-b %u or:w 257 --bar %u Treated the same as foo=%u above 258.Pp 259Each argument or option is matched against every template. 260This allows more than one member of 261.Fa data 262to be set by a single argument or option (see example for gid below). 263.El 264.Sh RETURN VALUES 265.Fn fuse_opt_add_arg , 266.Fn fuse_opt_insert_arg , 267.Fn fuse_opt_add_opt , 268.Fn fuse_opt_add_opt_escaped , 269and 270.Fn fuse_opt_parse 271return 0 on success, -1 on error. 272.Pp 273.Fn fuse_opt_match 274returns 1 on match, 0 if no match. 275.Sh ERRORS 276.Fn fuse_opt_add_arg , 277.Fn fuse_opt_insert_arg , 278.Fn fuse_opt_add_opt , 279and 280.Fn fuse_opt_add_opt_escaped 281can run out of memory and set 282.Va errno . 283.Sh SEE ALSO 284.Xr fuse_main 3 285.Sh STANDARDS 286These library functions conform to FUSE 2.6. 287.Sh HISTORY 288These functions first appeared in 289.Ox 5.4 . 290.Sh AUTHORS 291.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com 292.An Helg Bredow Aq Mt xx404@msn.com 293.Pp 294This manual was written by 295.An Ray Lai Aq Mt ray@raylai.com 296and updated by 297.An Helg Bredow Aq Mt xx404@msn.com 298