PR: https://github.com/freebsd/freebsd-src/pull/1551
On Fri, 8 Aug 2025 at 18:10, Mariusz Zaborski <osho...@freebsd.org> wrote: > The branch main has been updated by oshogbo: > > URL: > https://cgit.FreeBSD.org/src/commit/?id=50dee972977a17d47bd76f52c54461ee8581d1b1 > > commit 50dee972977a17d47bd76f52c54461ee8581d1b1 > Author: Faraz Vahedi <k...@kfv.io> > AuthorDate: 2024-12-14 15:43:36 +0000 > Commit: Mariusz Zaborski <osho...@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 <k...@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 osho...@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. >
