From b16650830d69cbe2d13e74c4318757c15f2c552f Mon Sep 17 00:00:00 2001 From: Nikolaus Rath Date: Sat, 15 Oct 2016 19:46:57 -0700 Subject: [PATCH] Make --help output more suitable for end-user We now only list options that are potentially useful for an end-user (and unlikely to accidentally break a file system). The full list of FUSE options has been moved to the documentation of the fuse_new() and fuse_session_new() functions. --- ChangeLog.rst | 8 +++++++- example/hello_ll.c | 3 +-- example/notify_inval_entry.c | 3 +-- example/notify_inval_inode.c | 3 +-- example/notify_store_retrieve.c | 3 +-- example/passthrough_ll.c | 3 +-- include/fuse.h | 33 +++++++++++++++++++++++++++------ include/fuse_lowlevel.h | 27 +++++++++++++++------------ lib/fuse.c | 14 ++++---------- lib/fuse_lowlevel.c | 6 ++++++ lib/helper.c | 6 +++--- lib/mount.c | 9 +++------ lib/mount_bsd.c | 2 -- 13 files changed, 70 insertions(+), 50 deletions(-) diff --git a/ChangeLog.rst b/ChangeLog.rst index 1748855..9246dd1 100644 --- a/ChangeLog.rst +++ b/ChangeLog.rst @@ -1,6 +1,12 @@ Unreleased Changes ================== +* The help text generated by fuse_lowlevel_help(), fuse_new() (and + indirectly fuse_main()) no longer includes options that are unlikely + to be of interest to end-users. The full list of accepted options is + now included in the respective function's documentation (located in + the fuse.h/fuse_lowlevel.h and doc/html). + * The ``-o nopath`` option has been dropped - it never actually did anything (since it is unconditionally overwritten with the value of the `nopath` flag in `struct fuse_operations). @@ -57,7 +63,7 @@ Unreleased Changes * The `fuse_parse_cmdline` function no longer prints out help when the ``--verbose`` or ``--help`` flags are given. This needs to be done by the file system (e.g. using the `fuse_cmdline_help()` and - `fuse_mount_help()` functions). + `fuse_lowlevel_help()` functions). * Added ``example/cuse_client.c`` to test ``example/cuse.c``. diff --git a/example/hello_ll.c b/example/hello_ll.c index 81d04c3..d673a5d 100644 --- a/example/hello_ll.c +++ b/example/hello_ll.c @@ -195,13 +195,12 @@ int main(int argc, char *argv[]) if (opts.show_help) { printf("usage: %s [options] \n\n", argv[0]); fuse_cmdline_help(); - fuse_mount_help(); + fuse_lowlevel_help(); ret = 0; goto err_out1; } else if (opts.show_version) { printf("FUSE library version %s\n", fuse_pkgversion()); fuse_lowlevel_version(); - fuse_mount_version(); ret = 0; goto err_out1; } diff --git a/example/notify_inval_entry.c b/example/notify_inval_entry.c index bb6f2ef..7c33dc4 100644 --- a/example/notify_inval_entry.c +++ b/example/notify_inval_entry.c @@ -287,13 +287,12 @@ int main(int argc, char *argv[]) { if (opts.show_help) { show_help(argv[0]); fuse_cmdline_help(); - fuse_mount_help(); + fuse_lowlevel_help(); ret = 0; goto err_out1; } else if (opts.show_version) { printf("FUSE library version %s\n", fuse_pkgversion()); fuse_lowlevel_version(); - fuse_mount_version(); ret = 0; goto err_out1; } diff --git a/example/notify_inval_inode.c b/example/notify_inval_inode.c index 078107e..934be60 100644 --- a/example/notify_inval_inode.c +++ b/example/notify_inval_inode.c @@ -310,13 +310,12 @@ int main(int argc, char *argv[]) { if (opts.show_help) { show_help(argv[0]); fuse_cmdline_help(); - fuse_mount_help(); + fuse_lowlevel_help(); ret = 0; goto err_out1; } else if (opts.show_version) { printf("FUSE library version %s\n", fuse_pkgversion()); fuse_lowlevel_version(); - fuse_mount_version(); ret = 0; goto err_out1; } diff --git a/example/notify_store_retrieve.c b/example/notify_store_retrieve.c index 8cc6666..6c8678a 100644 --- a/example/notify_store_retrieve.c +++ b/example/notify_store_retrieve.c @@ -353,13 +353,12 @@ int main(int argc, char *argv[]) { if (opts.show_help) { show_help(argv[0]); fuse_cmdline_help(); - fuse_mount_help(); + fuse_lowlevel_help(); ret = 0; goto err_out1; } else if (opts.show_version) { printf("FUSE library version %s\n", fuse_pkgversion()); fuse_lowlevel_version(); - fuse_mount_version(); ret = 0; goto err_out1; } diff --git a/example/passthrough_ll.c b/example/passthrough_ll.c index 7884242..dc5e10a 100644 --- a/example/passthrough_ll.c +++ b/example/passthrough_ll.c @@ -469,13 +469,12 @@ int main(int argc, char *argv[]) if (opts.show_help) { printf("usage: %s [options] \n\n", argv[0]); fuse_cmdline_help(); - fuse_mount_help(); + fuse_lowlevel_help(); ret = 0; goto err_out1; } else if (opts.show_version) { printf("FUSE library version %s\n", fuse_pkgversion()); fuse_lowlevel_version(); - fuse_mount_version(); ret = 0; goto err_out1; } diff --git a/include/fuse.h b/include/fuse.h index fb5f3fb..47bb154 100644 --- a/include/fuse.h +++ b/include/fuse.h @@ -615,8 +615,8 @@ struct fuse_context { * passing NULL as the processing function). That way, the remaining * options can be passed directly to fuse_main(). * - * To get a list of the options recognized by fuse_main(), look - * at the output when running with ``--help``. + * fuse_main() accepts all options that can be passed to + * fuse_parse_cmdline(), fuse_new(), or fuse_session_new(). * * Normally, fuse_main() includes a basic ``usage: `` message in the * --help output. However, if argv[0] is an empty string, the usage @@ -648,10 +648,31 @@ struct fuse_context { /** * Create a new FUSE filesystem. * - * Known options are defined in `struct fuse_opt fuse_lib_opts[]`, - * `struct fuse_opt fuse_mount_opts[]`, and `struct fuse_opt - * fuse_ll_opts[]`. If not all options are known, an error message is - * written to stderr and the function returns NULL. + * This function accepts any option that can be passed to + * fuse_session_new(), as well as the following (high-level API + * specific) options: + * + * -o hard_remove immediate removal (don't hide files) + * -o use_ino let filesystem set inode numbers + * -o readdir_ino try to fill in d_ino in readdir + * -o direct_io use direct I/O + * -o kernel_cache cache files in kernel + * -o [no]auto_cache enable caching based on modification times (off) + * -o umask=M set file permissions (octal) + * -o uid=N set file owner + * -o gid=N set file group + * -o entry_timeout=T cache timeout for names (1.0s) + * -o negative_timeout=T cache timeout for deleted names (0.0s) + * -o attr_timeout=T cache timeout for attributes (1.0s) + * -o ac_attr_timeout=T auto cache timeout for attributes (attr_timeout) + * -o noforget never forget cached inodes + * -o remember=T remember cached inodes for T seconds (0s) + * -o intr allow requests to be interrupted + * -o intr_signal=NUM signal to send on interrupt (%i) + * -o modules=M1[:M2...] names of modules to push onto filesystem stack + * + * If an unknown option is passed in, an error message is written to + * stderr and the function returns NULL. * * If the --help option is specified, the function writes a help text * to stdout and returns NULL. diff --git a/include/fuse_lowlevel.h b/include/fuse_lowlevel.h index d3aa484..f17920d 100644 --- a/include/fuse_lowlevel.h +++ b/include/fuse_lowlevel.h @@ -1618,20 +1618,16 @@ int fuse_req_interrupted(fuse_req_t req); * ----------------------------------------------------------- */ /** - * Print FUSE library version to stdout. + * Print low-level version information to stdout. */ void fuse_lowlevel_version(void); /** - * Print FUSE mount (fusermount) version stdout. + * Print available low-level options to stdout. This is not an + * exhaustive list, but includes only those options that may be of + * interest to an end-user of a file system. */ -void fuse_mount_version(void); - -/** - * Print available mount options to stdout. - * These options may be passed to `fuse_session_new()` - */ -void fuse_mount_help(void); +void fuse_lowlevel_help(void); /** * Print available options for `fuse_parse_cmdline()`. @@ -1677,9 +1673,16 @@ int fuse_parse_cmdline(struct fuse_args *args, * Returns a session structure suitable for passing to * fuse_session_mount() and fuse_session_loop(). * - * Known options can be listed by fuse_mount_help(). Additionally, - * this function accepts the `--debug` option (which is not explicitly - * listed by fuse_mount_help()). + * Under Linux, this function accepts the following options: + * + * -d, --debug enable debugging output + * -o allow_other allow access to other users + * -o allow_root allow access to root + * -o auto_unmount auto unmount on process termination + * -o default_permissions enable permission checking by kernel + * -o fsname=NAME set filesystem name + * -o subtype=NAME set filesystem type + * -o max_read=N set maximum size of read requests * * If not all options are known, an error message is written to stderr * and the function returns NULL. diff --git a/lib/fuse.c b/lib/fuse.c index 826de4e..07e63d2 100644 --- a/lib/fuse.c +++ b/lib/fuse.c @@ -4414,12 +4414,9 @@ static const struct fuse_opt fuse_lib_opts[] = { static void fuse_lib_help(void) { + /* These are not all options, but only the ones that + may be of interest to an end-user */ printf( -"High-level options\n" -" -o hard_remove immediate removal (don't hide files)\n" -" -o use_ino let filesystem set inode numbers\n" -" -o readdir_ino try to fill in d_ino in readdir\n" -" -o direct_io use direct I/O\n" " -o kernel_cache cache files in kernel\n" " -o [no]auto_cache enable caching based on modification times (off)\n" " -o umask=M set file permissions (octal)\n" @@ -4431,10 +4428,7 @@ static void fuse_lib_help(void) " -o ac_attr_timeout=T auto cache timeout for attributes (attr_timeout)\n" " -o noforget never forget cached inodes\n" " -o remember=T remember cached inodes for T seconds (0s)\n" -" -o intr allow requests to be interrupted\n" -" -o intr_signal=NUM signal to send on interrupt (%i)\n" -" -o modules=M1[:M2...] names of modules to push onto filesystem stack\n\n", - FUSE_DEFAULT_INTR_SIGNAL); +" -o modules=M1[:M2...] names of modules to push onto filesystem stack\n"); } static void fuse_lib_help_modules(void) @@ -4610,7 +4604,7 @@ struct fuse *fuse_new(struct fuse_args *args, if (f->conf.show_help) { fuse_lib_help(); - fuse_mount_help(); + fuse_lowlevel_help(); /* Defer printing module help until modules have been loaded */ } diff --git a/lib/fuse_lowlevel.c b/lib/fuse_lowlevel.c index 736cec6..92e0ea3 100644 --- a/lib/fuse_lowlevel.c +++ b/lib/fuse_lowlevel.c @@ -2531,6 +2531,12 @@ void fuse_lowlevel_version(void) { printf("using FUSE kernel interface version %i.%i\n", FUSE_KERNEL_VERSION, FUSE_KERNEL_MINOR_VERSION); + fuse_mount_version(); +} + +void fuse_lowlevel_help(void) +{ + fuse_mount_help(); } void fuse_session_destroy(struct fuse_session *se) diff --git a/lib/helper.c b/lib/helper.c index 6044bb3..6d72802 100644 --- a/lib/helper.c +++ b/lib/helper.c @@ -114,14 +114,13 @@ static const struct fuse_opt conn_info_opt_spec[] = { void fuse_cmdline_help(void) { - printf("General options:\n" - " -h --help print help\n" + printf(" -h --help print help\n" " -V --version print version\n" " -d -o debug enable debug output (implies -f)\n" " -f foreground operation\n" " -s disable multi-threaded operation\n" " -o clone_fd use separate fuse device fd for each thread\n" - "\n"); + " (may improve performance)\n"); } static int fuse_helper_opt_proc(void *data, const char *arg, int key, @@ -270,6 +269,7 @@ int fuse_main_real(int argc, char *argv[], const struct fuse_operations *op, if(args.argv[0] != '\0') printf("usage: %s [options] \n\n", args.argv[0]); + printf("FUSE options:\n"); fuse_cmdline_help(); if (fuse_opt_add_arg(&args, "--help") == -1) { res = 1; diff --git a/lib/mount.c b/lib/mount.c index faac1ea..c00367f 100644 --- a/lib/mount.c +++ b/lib/mount.c @@ -117,15 +117,12 @@ static const struct fuse_opt fuse_mount_opts[] = { void fuse_mount_help(void) { + /* These are not all options, but the ones that are + potentially of interest to an end-user */ printf( -"FUSE-specific mount options:\n" " -o allow_other allow access to other users\n" " -o allow_root allow access to root\n" -" -o auto_unmount auto unmount on process termination\n" -" -o default_permissions enable permission checking by kernel\n" -" -o fsname=NAME set filesystem name\n" -" -o subtype=NAME set filesystem type\n" -" -o max_read=N set maximum size of read requests\n\n"); +" -o auto_unmount auto unmount on process termination\n"); } static void exec_fusermount(const char *argv[]) diff --git a/lib/mount_bsd.c b/lib/mount_bsd.c index dc05506..c39414b 100644 --- a/lib/mount_bsd.c +++ b/lib/mount_bsd.c @@ -96,10 +96,8 @@ static const struct fuse_opt fuse_mount_opts[] = { void fuse_mount_help(void) { printf( -"FUSE-specific mount options:\n" " -o allow_root allow access to root\n"); system(FUSERMOUNT_PROG " --help"); - fputc('\n', stderr); } void fuse_mount_version(void) -- 2.30.2