git: 50dee972977a - main - cap_fileargs.3: Polish

The branch main has been updated by oshogbo:

URL: https://cgit.FreeBSD.org/src/commit/?id=50dee972977a17d47bd76f52c54461ee8581d1b1

commit 50dee972977a17d47bd76f52c54461ee8581d1b1
Author:     Faraz Vahedi <kfv@kfv.io>
AuthorDate: 2024-12-14 15:43:36 +0000
Commit:     Mariusz Zaborski <oshogbo@FreeBSD.org>
CommitDate: 2025-08-08 16:08:21 +0000

    cap_fileargs.3: Polish
    
    Extensively revised the manual page with clearer phrasing, better
    structure, and corrected grammar throughout. Also fixed typos and
    improved overall readability of the documentation.
    
    Signed-off-by: Faraz Vahedi <kfv@kfv.io>
---
 lib/libcasper/services/cap_fileargs/cap_fileargs.3 | 174 ++++++++++-----------
 1 file changed, 86 insertions(+), 88 deletions(-)

diff --git a/lib/libcasper/services/cap_fileargs/cap_fileargs.3 b/lib/libcasper/services/cap_fileargs/cap_fileargs.3
index c7ce45c518d1..6a69fe7e1f4a 100644
--- a/lib/libcasper/services/cap_fileargs/cap_fileargs.3
+++ b/lib/libcasper/services/cap_fileargs/cap_fileargs.3
@@ -22,10 +22,11 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd December 6, 2023
+.Dd August 8, 2025
 .Dt CAP_FILEARGS 3
 .Os
 .Sh NAME
+.Nm cap_fileargs ,
 .Nm fileargs_cinit ,
 .Nm fileargs_cinitnv ,
 .Nm fileargs_init ,
@@ -35,9 +36,8 @@
 .Nm fileargs_open ,
 .Nm fileargs_fopen
 .Nd "library for handling files in capability mode"
-.Sh LIBRARY
-.Lb libcap_fileargs
 .Sh SYNOPSIS
+.Lb libcap_fileargs
 .In sys/nv.h
 .In libcasper.h
 .In casper/cap_fileargs.h
@@ -60,52 +60,57 @@
 .Ft "char *"
 .Fn fileargs_realpath "fileargs_t *fa" "const char *pathname" "char *reserved_path"
 .Sh DESCRIPTION
-The library is used to simplify Capsicumizing a tools that are using file system.
-Idea behind the library is that we are passing a remaining
-.Fa argc
-and
+The
+.Nm
+library is used to simplify Capsicumizing tools that are using file system.
+The idea behind the library is that we pass the remaining arguments from
 .Fa argv
-which contains a list of files that should be open for this program.
-The library will create a service that will serve those files.
+(with count specified by
+.Fa argc )
+which contains the list of files that should be opened by the program.
+The library creates a service that will serve those files.
 .Pp
 The function
 .Fn fileargs_init
-create a service to the
+creates a service to the
 .Nm system.fileargs .
 The
 .Fa argv
 contains a list of files that should be opened.
 The argument can be set to
 .Dv NULL
-which will not create a service and all files will be prohibited to be opened.
+to create no service and prohibit all files from being opened.
 The
 .Fa argc
-argument contains a number of passed files.
+argument contains the number of files passed to the program.
 The
 .Fa flags
-argument limits opened files for either execution or reading and/or writing.
+argument specifies whether files can be opened for execution, for reading,
+and/or for writing.
 The
 .Fa mode
-argument tells which what mode file should be created if the
-.Dv O_CREATE
-flag is present .
-For more details of the
+argument specifies the permissions to use when creating new files if the
+.Dv O_CREAT
+flag is set.
+For more information about the
 .Fa flags
 and
 .Fa mode
-arguments see
+arguments, see
 .Xr open 2 .
 The
 .Fa rightsp
-argument contains a list of the capability rights which file should be limited to.
-For more details of the capability rights see
+argument specifies the capability rights that will be applied to restrict
+access to the files.
+For more information about capability rights, see
 .Xr cap_rights_init 3 .
 The
 .Fa operations
-argument limits the operations that are available using
+argument specifies which operations are permitted when using
 .Nm system.fileargs .
+The following flags can be combined to form the
 .Fa operations
-is a combination of:
+value:
 .Bl -ohang -offset indent
 .It FA_OPEN
 Allow
@@ -122,121 +127,117 @@ Allow
 .Pp
 The function
 .Fn fileargs_cinit
-is equivalent to
-.Fn fileargs_init
-except that the connection to the Casper needs to be provided.
+behaves identically to
+.Fn fileargs_init ,
+but requires an existing Casper connection to be passed as an argument.
 .Pp
 The functions
 .Fn fileargs_initnv
 and
 .Fn fileargs_cinitnv
-are respectively equivalent to
+are equivalent to
 .Fn fileargs_init
 and
 .Fn fileargs_cinit
-expect that all arguments all provided as
-.Xr nvlist 9 .
-For details see
-.Sx LIMITS .
+respectively, but take their arguments in the form of an
+.Xr nvlist 9
+structure.
+See the
+.Sx LIMITS
+section for details on the expected argument types and values.
 .Pp
 The
-.Fa fileargs_free
-close connection to the
+.Fn fileargs_free
+function closes the connection to the
 .Nm system.fileargs
-service and free are structures.
-The function handle
+service and frees all associated data structures.
+The function safely handles
 .Dv NULL
-argument.
+arguments.
 .Pp
 The function
 .Fn fileargs_lstat
-is equivalent to
+provides the same functionality as
 .Xr lstat 2 .
 .Pp
 The functions
 .Fn fileargs_open
 and
 .Fn fileargs_fopen
-are respectively equivalent to
+behave identically to
 .Xr open 2
 and
 .Xr fopen 3
-expect that all arguments are fetched from the
+respectively, but retrieve their arguments from the
 .Va fileargs_t
 structure.
 .Pp
 The function
 .Fn fileargs_realpath
-is equivalent to
-.Xr realpath 3 .
+provides the same functionality as the standard C library function
+.Xr realpath 3 ,
+resolving all symbolic links and references in a pathname.
 .Pp
+The following functions are reentrant but require synchronization for
+thread safety:
 .Fn fileargs_open ,
 .Fn fileargs_lstat ,
 .Fn fileargs_realpath ,
 .Fn fileargs_cinitnv ,
 .Fn fileargs_initnv ,
 and
-.Fn fileargs_fopen
-are reentrant but not thread-safe.
-That is, they may be called from separate threads only with different
+.Fn fileargs_fopen .
+Multiple threads can call these functions safely only if they use different
 .Vt cap_channel_t
-arguments or with synchronization.
+arguments or proper synchronization mechanisms.
 .Sh LIMITS
-This section describe which values and types should be used to pass arguments to the
+This section describes the required and optional arguments that must be
+passed to
 .Fa system.fileargs
-through the
+via the
 .Fn fileargs_initnv
 and
 .Fn fileargs_cinitnv
-functions.
-The
+functions using an
 .Xr nvlist 9
-for that functions must contain the following values and types:
+structure.
+.Pp
+The following arguments are required:
 .Bl -ohang -offset indent
-.It flags ( NV_TYPE_NUMBER )
-The
-.Va flags
-limits opened files for either execution or reading and/or writing.
-.It mode (NV_TYPE_NUMBER)
-If in the
-.Va flags
-argument the
+.It flags Pq Dv NV_TYPE_NUMBER
+Specifies access permissions for opened files.
+.It mode Pq Dv NV_TYPE_NUMBER
+Required when the
 .Dv O_CREATE
-flag was defined the
-.Xr nvlist 9
-must contain the
-.Va mode .
-The
-.Va mode
-argument tells which what mode file should be created.
-.It operations (NV_TYPE_NUMBER)
-The
-.Va operations
-limits the usable operations for
+flag is set in
+.Va flags .
+Specifies the permissions to use when creating new files.
+.It operations Pq Dv NV_TYPE_NUMBER
+Specifies which operations are allowed for
 .Fa system.fileargs .
-The possible values are explained as
+See the description of the
 .Va operations
-argument with
-.Fn fileargs_init .
+argument in
+.Fn fileargs_init
+for possible values.
 .El
 .Pp
-The
+The following arguments are optional in the
 .Xr nvlist 9
-for that functions may contain the following values and types:
+structure:
 .Bl -ohang -offset indent
-.It cap_rights ( NV_TYPE_BINARY )
+.It cap_rights Pq Dv NV_TYPE_BINARY
 The
 .Va cap_rights
-argument contains a list of the capability rights which file should be limited to.
-.It ( NV_TYPE_NULL )
-Any number of
+argument specifies the capability rights that will be applied to restrict
+access to opened files.
+.It filenames Pq Dv NV_TYPE_NULL
+Multiple
 .Dv NV_TYPE_NULL
-where the name of the element is name of the file which can be opened.
+elements can be provided, where each element's name represents a file
+path that is allowed to be opened.
 .El
 .Sh EXAMPLES
-The following example first parse some options and then create the
-.Nm system.fileargs
-service with remaining arguments.
 .Bd -literal
 int ch, fd, i;
 cap_rights_t rights;
@@ -287,16 +288,13 @@ fileargs_free(fa);
 .Xr nv 9
 .Sh HISTORY
 The
-.Nm cap_fileargs
+.Nm
 service first appeared in
 .Fx 10.3 .
 .Sh AUTHORS
 .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org
 .Sh BUGS
 The
-.Lb cap_fileargs
-included in
-.Fx
-is considered experimental, and should not be deployed in production
-environments without careful consideration of the risks associated with
-the use of experimental operating system features.
+.Nm
+service is considered experimental and should be thoroughly evaluated
+for risks before deploying in production environments.