1
0
mirror of https://github.com/openbsd/src.git synced 2026-04-29 16:47:15 +00:00

Minor cleanup in several of the FUSE manuals, including:

* clarify that dying from a signal is not considered a failure of fuse_loop(3)
* add many missing .Dv macros and a few missing .Pa and .Er macros
* remove future tense in several cases where it's pointless
* polish some capitalization and punctuation and fix a few typos
OK helg@
This commit is contained in:
schwarze
2025-09-23 09:28:28 +00:00
parent d4a733e3e9
commit a61ae78563
10 changed files with 99 additions and 62 deletions

View File

@@ -1,4 +1,4 @@
.\" $OpenBSD: fuse_chan_fd.3,v 1.4 2025/06/10 12:55:33 schwarze Exp $
.\" $OpenBSD: fuse_chan_fd.3,v 1.5 2025/09/23 09:28:28 schwarze Exp $
.\"
.\" Copyright (c) 2018 Helg Bredow <helg.bredow@openbsd.org>
.\"
@@ -14,7 +14,7 @@
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: June 10 2025 $
.Dd $Mdocdate: September 23 2025 $
.Dt FUSE_CHAN_FD 3
.Os
.Sh NAME
@@ -27,7 +27,7 @@
.Fn fuse_chan_fd "struct fuse_chan *ch"
.Sh DESCRIPTION
.Fn fuse_chan_fd
will return the file descriptor to the FUSE device opened for reading
returns the file descriptor to the FUSE device opened for reading
and writing by
.Xr fuse_mount 3 .
.Sh RETURN VALUES
@@ -36,7 +36,9 @@ If successful,
returns a non-negative integer, termed a file descriptor.
If
.Fa ch
is NULL, a value of -1 is returned.
is
.Dv NULL ,
a value of -1 is returned.
.Sh SEE ALSO
.Xr fuse_mount 3 ,
.Xr open 3 ,

View File

@@ -1,4 +1,4 @@
.\" $OpenBSD: fuse_daemonize.3,v 1.5 2025/06/10 12:55:33 schwarze Exp $
.\" $OpenBSD: fuse_daemonize.3,v 1.6 2025/09/23 09:28:28 schwarze Exp $
.\"
.\" Copyright (c) 2018 Helg Bredow <helg@openbsd.org>
.\"
@@ -14,7 +14,7 @@
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: June 10 2025 $
.Dd $Mdocdate: September 23 2025 $
.Dt FUSE_DAEMONIZE 3
.Os
.Sh NAME
@@ -30,12 +30,14 @@ If
.Fa foreground
is 0,
.Fn fuse_daemonize
will detach from the controlling terminal and run in the background as a
detaches from the controlling terminal and runs in the background as a
system daemon.
Otherwise, the process will continue to run in the foreground.
Otherwise, the process continues to run in the foreground.
.Pp
The current working directory is changed to the root (/) and standard input;
standard output and standard error are redirected to /dev/null.
The current working directory is changed to the root directory
.Pq Pa / .
Standard input, standard output, and standard error are redirected to
.Pa /dev/null .
.Sh RETURN VALUES
Upon success,
.Fn fuse_daemonize

View File

@@ -1,4 +1,4 @@
.\" $OpenBSD: fuse_destroy.3,v 1.4 2025/09/20 15:01:23 helg Exp $
.\" $OpenBSD: fuse_destroy.3,v 1.5 2025/09/23 09:28:28 schwarze Exp $
.\"
.\" Copyright (c) 2018 Helg Bredow <helg.bredow@openbsd.org>
.\"
@@ -14,7 +14,7 @@
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: September 20 2025 $
.Dd $Mdocdate: September 23 2025 $
.Dt FUSE_DESTROY 3
.Os
.Sh NAME
@@ -27,12 +27,13 @@
.Fn fuse_destroy "struct fuse *f"
.Sh DESCRIPTION
.Fn fuse_destroy
Frees memory associated with the FUSE channel and FUSE handle specified by
frees memory associated with the FUSE channel and FUSE handle specified by
.Fa f .
The file system's destroy operation will be called if
The file system's destroy operation is called if
.Xr fuse_loop 3
did not receive the FBT_DESTROY message.
Usually due to terminating from a signal.
did not receive the
.Dv FBT_DESTROY
message, usually due to terminating from a signal.
.Pp
This function does not unmount the file system, which should be done
with

View File

@@ -1,4 +1,4 @@
.\" $OpenBSD: fuse_loop.3,v 1.4 2025/09/20 15:01:23 helg Exp $
.\" $OpenBSD: fuse_loop.3,v 1.5 2025/09/23 09:28:28 schwarze Exp $
.\"
.\" Copyright (c) 2018 Helg Bredow <helg@openbsd.org>
.\"
@@ -14,7 +14,7 @@
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: September 20 2025 $
.Dd $Mdocdate: September 23 2025 $
.Dt FUSE_LOOP 3
.Os
.Sh NAME
@@ -41,15 +41,22 @@ prior to calling
.Fn fuse_loop .
.Pp
.Fn fuse_loop
will return when it reads the FBT_DESTROY message, which indicates that
returns when it reads the
.Dv FBT_DESTROY
message, which indicates that
the file system is being unmounted.
.Pp
If FUSE signaler handlers have been installed and either SIGHUP, SIGINT
or SIGTERM is received then
If FUSE signal handlers have been installed and
.Dv SIGHUP ,
.Dv SIGINT ,
or
.Dv SIGTERM
is received,
.Fn fuse_loop
will terminate.
terminates successfully.
See
.Xr fuse_set_signal_handlers 3 .
.Xr fuse_set_signal_handlers 3
for more details.
.Pp
.Fn fuse_loop_mt
is a multi-threaded variant that allows the file system to process
@@ -58,7 +65,7 @@ This is not implemented on
.Ox .
.Sh RETURN VALUES
.Fn fuse_loop
will return 0 on success and -1 on failure.
returns 0 on success or -1 on failure.
.Pp
.Fn fuse_loop_mt
always returns -1.

View File

@@ -1,4 +1,4 @@
.\" $OpenBSD: fuse_mount.3,v 1.4 2025/09/20 15:01:23 helg Exp $
.\" $OpenBSD: fuse_mount.3,v 1.5 2025/09/23 09:28:28 schwarze Exp $
.\"
.\" Copyright (c) 2018 Helg Bredow <helg@openbsd.org>
.\"
@@ -13,7 +13,7 @@
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: September 20 2025 $
.Dd $Mdocdate: September 23 2025 $
.Dt FUSE_MOUNT 3
.Os
.Sh NAME
@@ -45,7 +45,7 @@ either individually or together separated by a comma.
.Bl -tag -width Ds
.It allow_other
Allow other users to access the file system.
By default, FUSE will prevent other users from accessing the file system or to
By default, FUSE prevents other users from accessing the file system or to
.Xr statfs 2
the file system.
This security measure is particularly important for
@@ -77,22 +77,25 @@ Can also be specified by itself with
.El
.Pp
.Fn fuse_unmount
will close the FUSE device and attempt to unmount the file system mounted at
closes the FUSE device and attempts to unmount the file system mounted at
.Fa dir
by calling the
.Xr unmount 2
system call.
To avoid a deadlock, the kernel will not send the
FBT_DESTROY message to the file system.
.Dv FBT_DESTROY
message to the file system.
There is no way to determine whether this call was successful.
.Pp
Only the super user can mount and unmount FUSE file systems.
.Sh RETURN VALUES
.Fn fuse_main
will return NULL if the file system cannot be mounted.
returns
.Dv NULL
if the file system cannot be mounted.
.Sh ERRORS
.Fn fuse_mount
will fail when one of the following occurs:
fails when one of the following occurs:
.Fa dir
does not exist or is not a directory.
The fuse device cannot be opened for reading and writing.

View File

@@ -1,4 +1,4 @@
.\" $OpenBSD: fuse_new.3,v 1.10 2025/09/20 15:01:23 helg Exp $
.\" $OpenBSD: fuse_new.3,v 1.11 2025/09/23 09:28:28 schwarze Exp $
.\"
.\" Copyright (c) 2013 Sylvestre Gallon <ccna.syl@gmail.com>
.\" Copyright (c) 2018 Helg Bredow <helg@openbsd.org>
@@ -15,7 +15,7 @@
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: September 20 2025 $
.Dd $Mdocdate: September 23 2025 $
.Dt FUSE_NEW 3
.Os
.Sh NAME
@@ -39,11 +39,13 @@ a negated errno value (-errno) on failure.
.Pp
All operations are optional but a functional file system will want to
implement at least statfs, readdir, open, read and getattr.
FUSE will return ENOSYS if any operation other than flush, fsync or
FUSE returns
.Er ENOSYS
if any operation other than flush, fsync or
fsyncdir is not implemented.
.Pp
The first parameter to each of these operations (except for init and
destroy) is a NULL terminated string representing the full path to
destroy) is a NUL-terminated string representing the full path to
the file or directory, relative to the root of the file system, that
is being operated on.
.Bd -literal

View File

@@ -1,4 +1,4 @@
.\" $OpenBSD: fuse_opt.3,v 1.5 2025/09/22 17:18:40 schwarze Exp $
.\" $OpenBSD: fuse_opt.3,v 1.6 2025/09/23 09:28:28 schwarze Exp $
.\"
.\" Copyright (c) Ray Lai <ray@raylai.com>
.\" Copyright (c) Helg Bredow <helg@openbsd.org>
@@ -15,7 +15,7 @@
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: September 22 2025 $
.Dd $Mdocdate: September 23 2025 $
.Dt FUSE_OPT 3
.Os
.Sh NAME
@@ -157,7 +157,9 @@ and
which are usually obtained from
.Fn main .
.Fa argv
is NULL-terminated, and is suitable for use with
is
.Dv NULL Ns -terminated ,
and is suitable for use with
.Xr execvp 3 .
.Fa argv
is used directly and
@@ -190,7 +192,9 @@ adds an option
to a comma-separated string of options
.Fa opts .
.Fa *opts
can be NULL, which is typically used when adding the first option.
can be
.Dv NULL ,
which is typically used when adding the first option.
.Pp
.It Fn fuse_opt_add_opt_escaped
escapes any
@@ -224,7 +228,9 @@ parses options, setting any members of
automatically depending on the format of the template.
If
.Fa proc
is not NULL, then this is called for any argument that matches a template
is not
.Dv NULL ,
then this is called for any argument that matches a template
that has
.Fa val
= FUSE_OPT_KEY.
@@ -269,10 +275,10 @@ to be set by a single argument or option (see example for gid below).
.Fn fuse_opt_add_opt_escaped ,
and
.Fn fuse_opt_parse
return 0 on success, -1 on error.
return 0 on success or -1 on error.
.Pp
.Fn fuse_opt_match
returns 1 on match, 0 if no match.
returns 1 on match or 0 if no match.
.Sh ERRORS
.Fn fuse_opt_add_arg ,
.Fn fuse_opt_insert_arg ,

View File

@@ -1,4 +1,4 @@
.\" $OpenBSD: fuse_parse_cmdline.3,v 1.2 2025/06/10 12:55:33 schwarze Exp $
.\" $OpenBSD: fuse_parse_cmdline.3,v 1.3 2025/09/23 09:28:28 schwarze Exp $
.\"
.\" Copyright (c) 2018 Helg Bredow <helg.bredow@openbsd.org>
.\"
@@ -14,7 +14,7 @@
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: June 10 2025 $
.Dd $Mdocdate: September 23 2025 $
.Dt FUSE_PARSE_CMDLINE 3
.Os
.Sh NAME
@@ -73,7 +73,7 @@ will be set to the canonicalized absolute pathname of this directory.
.Sh RETURN VALUES
The
.Fn fuse_parse_cmdline
function will return 0 on success and -1 if
function returns 0 on success or -1 if
.Fl h , Fl -help , Fl ho , Fl v
or
.Fl -version

View File

@@ -1,4 +1,4 @@
.\" $OpenBSD: fuse_set_signal_handlers.3,v 1.3 2025/06/10 12:55:33 schwarze Exp $
.\" $OpenBSD: fuse_set_signal_handlers.3,v 1.4 2025/09/23 09:28:28 schwarze Exp $
.\"
.\" Copyright (c) 2018 Helg Bredow <helg@openbsd.org>
.\"
@@ -14,7 +14,7 @@
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: June 10 2025 $
.Dd $Mdocdate: September 23 2025 $
.Dt FUSE_SET_SIGNAL_HANDLERS 3
.Os
.Sh NAME
@@ -30,19 +30,24 @@
.Fn fuse_remove_signal_handlers "struct fuse_session *se"
.Sh DESCRIPTION
.Fn fuse_set_signal_handlers
installs signal handlers for the signals SIGHUP, SIGINT and SIGTERM that
will attempt to unmount the file system.
SIGPIPE will be ignored.
installs signal handlers for the signals
.Dv SIGHUP ,
.Dv SIGINT ,
and
.Dv SIGTERM
that will attempt to unmount the file system.
.Dv SIGPIPE
will be ignored.
If there is already a signal handler installed for any of these signals
then it is not replaced.
.Pp
.Fn fuse_remove_signal_handlers
will restore the default signal handlers for any signals that were
restores the default signal handlers for any signals that were
installed by
.Fn fuse_set_signal_handlers .
.Sh RETURN VALUES
.Fn fuse_set_signal_handlers
will return 0 on success and -1 on failure.
returns 0 on success or -1 on failure.
.Sh SEE ALSO
.Xr sigaction 2 ,
.Xr fuse_setup 3

View File

@@ -1,4 +1,4 @@
.\" $OpenBSD: fuse_setup.3,v 1.4 2025/06/10 12:55:33 schwarze Exp $
.\" $OpenBSD: fuse_setup.3,v 1.5 2025/09/23 09:28:28 schwarze Exp $
.\"
.\" Copyright (c) 2018 Helg Bredow <helg.bredow@openbsd.org>
.\"
@@ -14,7 +14,7 @@
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: June 10 2025 $
.Dd $Mdocdate: September 23 2025 $
.Dt FUSE_SETUP 3
.Os
.Sh NAME
@@ -31,19 +31,26 @@
.Fn fuse_setup
is a helper function that mounts a FUSE file system, creates a new FUSE
session and installs signal handlers that will try to unmount the file
system on SIGINT, SIGTERM or SIGHUP.
system on
.Dv SIGINT ,
.Dv SIGTERM ,
or
.Dv SIGHUP .
.Pp
.Fn fuse_setup
will parse the arguments specified by argv and if neither the
.Fl f , Fl d
parses the arguments specified by
.Fa argv ,
and if neither the
.Fl f ,
.Fl d ,
or
.Fl odebug
options were specified, detach from the controlling terminal
and run in the background.
options were specified, detaches from the controlling terminal
and runs in the background.
On success,
.Fa mt
will be 1 if the file system operations will be invoked in
parallel (multi-threaded) or 0 if file system operations are serialized.
is set to 1 if the file system operations will be invoked in
parallel (multi-threaded) or to 0 if file system operations are serialized.
File systems that do not support multi-threaded operation must include the
.Fl s
argument in
@@ -65,7 +72,9 @@ See
.Xr fuse_new 3 .
.Sh RETURN VALUES
.Fn fuse_setup
will return NULL on failure.
returns
.Dv NULL
on failure.
.Sh SEE ALSO
.Xr fuse_main 3 ,
.Xr fuse_mount 3 ,