lkml.org 
[lkml]   [2020]   [Aug]   [7]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    Subject[PATCH 5/5] Add manpage for fsconfig(2)
    From
    Date
    Add a manual page to document the fsconfig() system call.

    Signed-off-by: David Howells <dhowells@redhat.com>
    ---

    man2/fsconfig.2 | 282 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
    1 file changed, 282 insertions(+)
    create mode 100644 man2/fsconfig.2

    diff --git a/man2/fsconfig.2 b/man2/fsconfig.2
    new file mode 100644
    index 000000000..32f0bce13
    --- /dev/null
    +++ b/man2/fsconfig.2
    @@ -0,0 +1,282 @@
    +'\" t
    +.\" Copyright (c) 2020 David Howells <dhowells@redhat.com>
    +.\"
    +.\" %%%LICENSE_START(VERBATIM)
    +.\" Permission is granted to make and distribute verbatim copies of this
    +.\" manual provided the copyright notice and this permission notice are
    +.\" preserved on all copies.
    +.\"
    +.\" Permission is granted to copy and distribute modified versions of this
    +.\" manual under the conditions for verbatim copying, provided that the
    +.\" entire resulting derived work is distributed under the terms of a
    +.\" permission notice identical to this one.
    +.\"
    +.\" Since the Linux kernel and libraries are constantly changing, this
    +.\" manual page may be incorrect or out-of-date. The author(s) assume no
    +.\" responsibility for errors or omissions, or for damages resulting from
    +.\" the use of the information contained herein. The author(s) may not
    +.\" have taken the same level of care in the production of this manual,
    +.\" which is licensed free of charge, as they might when working
    +.\" professionally.
    +.\"
    +.\" Formatted or processed versions of this manual, if unaccompanied by
    +.\" the source, must acknowledge the copyright and authors of this work.
    +.\" %%%LICENSE_END
    +.\"
    +.TH FSCONFIG 2 2020-08-07 "Linux" "Linux Programmer's Manual"
    +.SH NAME
    +fsconfig \- Filesystem parameterisation
    +.SH SYNOPSIS
    +.nf
    +.B #include <sys/types.h>
    +.br
    +.B #include <sys/mount.h>
    +.br
    +.B #include <unistd.h>
    +.br
    +.B #include <sys/mount.h>
    +.PP
    +.BI "int fsconfig(int *" fd ", unsigned int " cmd ", const char *" key ,
    +.br
    +.BI " const void __user *" value ", int " aux ");"
    +.br
    +.BI
    +.fi
    +.PP
    +.IR Note :
    +There is no glibc wrapper for this system call.
    +.SH DESCRIPTION
    +.PP
    +.BR fsconfig ()
    +is used to supply parameters to and issue commands against a filesystem
    +configuration context as set up by
    +.BR fsopen (2)
    +or
    +.BR fspick (2).
    +The context is supplied attached to the file descriptor specified by
    +.I fd
    +argument.
    +.PP
    +The
    +.I cmd
    +argument indicates the command to be issued, where some of the commands simply
    +supply parameters to the context. The meaning of
    +.IR key ", " value " and " aux
    +are command-dependent; unless required for the command, these should be set to
    +NULL or 0.
    +.PP
    +The available commands are:
    +.TP
    +.B FSCONFIG_SET_FLAG
    +Set the parameter named by
    +.IR key
    +to true. This may incur error
    +.B EINVAL
    +if the parameter requires an argument.
    +.TP
    +.B FSCONFIG_SET_STRING
    +Set the parameter named by
    +.I key
    +to a string. This may incur error
    +.B EINVAL
    +if the parser doesn't want a parameter here, wants a non-string or the string
    +cannot be interpreted appropriately.
    +.I value
    +points to a NUL-terminated string.
    +.TP
    +.B FSCONFIG_SET_BINARY
    +Set the parameter named by
    +.I key
    +to be a binary blob argument. This may cause
    +.B EINVAL
    +to be returned if the filesystem parser isn't expecting a binary blob and it
    +can't be converted to something usable.
    +.I value
    +points to the data and
    +.I aux
    +indicates the size of the data.
    +.TP
    +.B FSCONFIG_SET_PATH
    +Set the parameter named by
    +.I key
    +to the object at the provided path.
    +.I value
    +should point to a NULL-terminated pathname string and aux may indicate
    +.B AT_FDCWD
    +or a file descriptor indicating a directory from which to begin a relative
    +pathwalk. This may return any errors incurred by the pathwalk and may return
    +.B EINVAL
    +if the parameter isn't expecting a path.
    +.IP
    +Note that FSCONFIG_SET_STRING can be used instead, implying AT_FDCWD.
    +.TP
    +.B FSCONFIG_SET_PATH_EMPTY
    +As FSCONFIG_SET_PATH, but with
    +.B AT_EMPTY_PATH
    +applied to the pathwalk.
    +.TP
    +.B FSCONFIG_SET_FD
    +Set the parameter named by
    +.I key
    +to the file descriptor specified by
    +.IR aux .
    +This will incur
    +.B EINVAL
    +if the parameter doesn't expect a file descriptor or
    +.B EBADF
    +if the file descriptor is invalid.
    +.IP
    +Note that FSCONFIG_SET_STRING can be used instead with the file descriptor
    +passed as a decimal string.
    +.TP
    +.B FSCONFIG_CMD_CREATE
    +This command causes the filesystem to take the parameters set in the context
    +and to try to create filesystem representation in the kernel. If it can share
    +an existing one, it may do that instead if the filesystem type and parameters
    +permit that. This is intended for use with
    +.BR fsopen (2).
    +.TP
    +.B FSCONFIG_CMD_RECONFIGURE
    +This command causes the filesystem to apply the parameters set in the context
    +to an already existing filesystem representation in memory and to alter it.
    +This is intended for use with
    +.BR fspick (2),
    +but may also by used against the context created by
    +.BR fsopen()
    +after
    +.BR fsmount (2)
    +has been called on it.
    +
    +.\"________________________________________________________
    +.SH EXAMPLES
    +.PP
    +.in +4n
    +.nf
    +fsconfig(sfd, FSCONFIG_SET_FLAG, "ro", NULL, 0);
    +
    +fsconfig(sfd, FSCONFIG_SET_STRING, "user_xattr", "false", 0);
    +
    +fsconfig(sfd, FSCONFIG_SET_BINARY, "ms_pac", pac_buffer, pac_size);
    +
    +fsconfig(sfd, FSCONFIG_SET_PATH, "journal", "/dev/sdd4", AT_FDCWD);
    +
    +dirfd = open("/dev/", O_PATH);
    +fsconfig(sfd, FSCONFIG_SET_PATH, "journal", "sdd4", dirfd);
    +
    +fd = open("/overlays/mine/", O_PATH);
    +fsconfig(sfd, FSCONFIG_SET_PATH_EMPTY, "lower_dir", "", fd);
    +
    +pipe(pipefds);
    +fsconfig(sfd, FSCONFIG_SET_FD, "fd", NULL, pipefds[1]);
    +.fi
    +.in
    +.PP
    +
    +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    +.SH RETURN VALUE
    +On success, the function returns 0. On error, \-1 is returned, and
    +.I errno
    +is set appropriately.
    +.SH ERRORS
    +The error values given below result from filesystem type independent
    +errors.
    +Each filesystem type may have its own special errors and its
    +own special behavior.
    +See the Linux kernel source code for details.
    +.TP
    +.B EACCES
    +A component of a path was not searchable.
    +(See also
    +.BR path_resolution (7).)
    +.TP
    +.B EACCES
    +Mounting a read-only filesystem was attempted without specifying the
    +.RB ' ro '
    +parameter.
    +.TP
    +.B EACCES
    +A specified block device is located on a filesystem mounted with the
    +.B MS_NODEV
    +option.
    +.\" mtk: Probably: write permission is required for MS_BIND, with
    +.\" the error EPERM if not present; CAP_DAC_OVERRIDE is required.
    +.TP
    +.B EBADF
    +The file descriptor given by
    +.I fd
    +or possibly by
    +.I aux
    +(depending on the command) is invalid.
    +.TP
    +.B EBUSY
    +The context attached to
    +.I fd
    +is in the wrong state for the given command.
    +.TP
    +.B EBUSY
    +The filesystem representation cannot be reconfigured read-only because it still
    +holds files open for writing.
    +.TP
    +.B EFAULT
    +One of the pointer arguments points outside the user address space.
    +.TP
    +.B EINVAL
    +.I fd
    +does not refer to a filesystem configuration context.
    +.TP
    +.B EINVAL
    +One of the source parameters referred to an invalid superblock.
    +.TP
    +.B ELOOP
    +Too many links encountered during pathname resolution.
    +.TP
    +.B ENAMETOOLONG
    +A path name was longer than
    +.BR MAXPATHLEN .
    +.TP
    +.B ENOENT
    +A pathname was empty or had a nonexistent component.
    +.TP
    +.B ENOMEM
    +The kernel could not allocate sufficient memory to complete the call.
    +.TP
    +.B ENOTBLK
    +Once of the parameters does not refer to a block device (and a device was
    +required).
    +.TP
    +.B ENOTDIR
    +.IR pathname ,
    +or a prefix of
    +.IR source ,
    +is not a directory.
    +.TP
    +.B EOPNOTSUPP
    +The command given by
    +.I cmd
    +was not valid.
    +.TP
    +.B ENXIO
    +The major number of a block device parameter is out of range.
    +.TP
    +.B EPERM
    +The caller does not have the required privileges.
    +.SH CONFORMING TO
    +These functions are Linux-specific and should not be used in programs intended
    +to be portable.
    +.SH VERSIONS
    +.BR fsconfig ()
    +was added to Linux in kernel 5.1.
    +.SH NOTES
    +Glibc does not (yet) provide a wrapper for the
    +.BR fsconfig ()
    +system call; call it using
    +.BR syscall (2).
    +.SH SEE ALSO
    +.BR mountpoint (1),
    +.BR fsmount (2),
    +.BR fsopen (2),
    +.BR fspick (2),
    +.BR mount_namespaces (7),
    +.BR path_resolution (7)

    \
     
     \ /
      Last update: 2020-08-07 16:08    [W:5.864 / U:0.208 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site