Date: Fri, 8 Aug 2025 18:11:20 +0200 From: Mariusz Zaborski <oshogbo@freebsd.org> To: src-committers@freebsd.org, dev-commits-src-all@freebsd.org, dev-commits-src-main@freebsd.org Subject: Re: git: 50dee972977a - main - cap_fileargs.3: Polish Message-ID: <CAGOYWV9S3ajTworOJsgWrM17iW8CqZA6Z9rZa1Z9pqPgMp2z1A@mail.gmail.com> In-Reply-To: <202508081609.578G9oId013868@gitrepo.freebsd.org> References: <202508081609.578G9oId013868@gitrepo.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
[-- Attachment #1 --] PR: https://github.com/freebsd/freebsd-src/pull/1551 On Fri, 8 Aug 2025 at 18:10, Mariusz Zaborski <oshogbo@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 <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. > [-- Attachment #2 --] <div dir="ltr">PR: <a href="https://github.com/freebsd/freebsd-src/pull/1551">https://github.com/freebsd/freebsd-src/pull/1551</a></div><br><div class="gmail_quote gmail_quote_container"><div dir="ltr" class="gmail_attr">On Fri, 8 Aug 2025 at 18:10, Mariusz Zaborski <<a href="mailto:oshogbo@freebsd.org">oshogbo@freebsd.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">The branch main has been updated by oshogbo:<br> <br> URL: <a href="https://cgit.FreeBSD.org/src/commit/?id=50dee972977a17d47bd76f52c54461ee8581d1b1" rel="noreferrer" target="_blank">https://cgit.FreeBSD.org/src/commit/?id=50dee972977a17d47bd76f52c54461ee8581d1b1</a><br>; <br> commit 50dee972977a17d47bd76f52c54461ee8581d1b1<br> Author: Faraz Vahedi <<a href="mailto:kfv@kfv.io" target="_blank">kfv@kfv.io</a>><br> AuthorDate: 2024-12-14 15:43:36 +0000<br> Commit: Mariusz Zaborski <oshogbo@FreeBSD.org><br> CommitDate: 2025-08-08 16:08:21 +0000<br> <br> cap_fileargs.3: Polish<br> <br> Extensively revised the manual page with clearer phrasing, better<br> structure, and corrected grammar throughout. Also fixed typos and<br> improved overall readability of the documentation.<br> <br> Signed-off-by: Faraz Vahedi <<a href="mailto:kfv@kfv.io" target="_blank">kfv@kfv.io</a>><br> ---<br> lib/libcasper/services/cap_fileargs/cap_fileargs.3 | 174 ++++++++++-----------<br> 1 file changed, 86 insertions(+), 88 deletions(-)<br> <br> diff --git a/lib/libcasper/services/cap_fileargs/cap_fileargs.3 b/lib/libcasper/services/cap_fileargs/cap_fileargs.3<br> index c7ce45c518d1..6a69fe7e1f4a 100644<br> --- a/lib/libcasper/services/cap_fileargs/cap_fileargs.3<br> +++ b/lib/libcasper/services/cap_fileargs/cap_fileargs.3<br> @@ -22,10 +22,11 @@<br> .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF<br> .\" SUCH DAMAGE.<br> .\"<br> -.Dd December 6, 2023<br> +.Dd August 8, 2025<br> .Dt CAP_FILEARGS 3<br> .Os<br> .Sh NAME<br> +.Nm cap_fileargs ,<br> .Nm fileargs_cinit ,<br> .Nm fileargs_cinitnv ,<br> .Nm fileargs_init ,<br> @@ -35,9 +36,8 @@<br> .Nm fileargs_open ,<br> .Nm fileargs_fopen<br> .Nd "library for handling files in capability mode"<br> -.Sh LIBRARY<br> -.Lb libcap_fileargs<br> .Sh SYNOPSIS<br> +.Lb libcap_fileargs<br> .In sys/nv.h<br> .In libcasper.h<br> .In casper/cap_fileargs.h<br> @@ -60,52 +60,57 @@<br> .Ft "char *"<br> .Fn fileargs_realpath "fileargs_t *fa" "const char *pathname" "char *reserved_path"<br> .Sh DESCRIPTION<br> -The library is used to simplify Capsicumizing a tools that are using file system.<br> -Idea behind the library is that we are passing a remaining<br> -.Fa argc<br> -and<br> +The<br> +.Nm<br> +library is used to simplify Capsicumizing tools that are using file system.<br> +The idea behind the library is that we pass the remaining arguments from<br> .Fa argv<br> -which contains a list of files that should be open for this program.<br> -The library will create a service that will serve those files.<br> +(with count specified by<br> +.Fa argc )<br> +which contains the list of files that should be opened by the program.<br> +The library creates a service that will serve those files.<br> .Pp<br> The function<br> .Fn fileargs_init<br> -create a service to the<br> +creates a service to the<br> .Nm system.fileargs .<br> The<br> .Fa argv<br> contains a list of files that should be opened.<br> The argument can be set to<br> .Dv NULL<br> -which will not create a service and all files will be prohibited to be opened.<br> +to create no service and prohibit all files from being opened.<br> The<br> .Fa argc<br> -argument contains a number of passed files.<br> +argument contains the number of files passed to the program.<br> The<br> .Fa flags<br> -argument limits opened files for either execution or reading and/or writing.<br> +argument specifies whether files can be opened for execution, for reading,<br> +and/or for writing.<br> The<br> .Fa mode<br> -argument tells which what mode file should be created if the<br> -.Dv O_CREATE<br> -flag is present .<br> -For more details of the<br> +argument specifies the permissions to use when creating new files if the<br> +.Dv O_CREAT<br> +flag is set.<br> +For more information about the<br> .Fa flags<br> and<br> .Fa mode<br> -arguments see<br> +arguments, see<br> .Xr open 2 .<br> The<br> .Fa rightsp<br> -argument contains a list of the capability rights which file should be limited to.<br> -For more details of the capability rights see<br> +argument specifies the capability rights that will be applied to restrict<br> +access to the files.<br> +For more information about capability rights, see<br> .Xr cap_rights_init 3 .<br> The<br> .Fa operations<br> -argument limits the operations that are available using<br> +argument specifies which operations are permitted when using<br> .Nm system.fileargs .<br> +The following flags can be combined to form the<br> .Fa operations<br> -is a combination of:<br> +value:<br> .Bl -ohang -offset indent<br> .It FA_OPEN<br> Allow<br> @@ -122,121 +127,117 @@ Allow<br> .Pp<br> The function<br> .Fn fileargs_cinit<br> -is equivalent to<br> -.Fn fileargs_init<br> -except that the connection to the Casper needs to be provided.<br> +behaves identically to<br> +.Fn fileargs_init ,<br> +but requires an existing Casper connection to be passed as an argument.<br> .Pp<br> The functions<br> .Fn fileargs_initnv<br> and<br> .Fn fileargs_cinitnv<br> -are respectively equivalent to<br> +are equivalent to<br> .Fn fileargs_init<br> and<br> .Fn fileargs_cinit<br> -expect that all arguments all provided as<br> -.Xr nvlist 9 .<br> -For details see<br> -.Sx LIMITS .<br> +respectively, but take their arguments in the form of an<br> +.Xr nvlist 9<br> +structure.<br> +See the<br> +.Sx LIMITS<br> +section for details on the expected argument types and values.<br> .Pp<br> The<br> -.Fa fileargs_free<br> -close connection to the<br> +.Fn fileargs_free<br> +function closes the connection to the<br> .Nm system.fileargs<br> -service and free are structures.<br> -The function handle<br> +service and frees all associated data structures.<br> +The function safely handles<br> .Dv NULL<br> -argument.<br> +arguments.<br> .Pp<br> The function<br> .Fn fileargs_lstat<br> -is equivalent to<br> +provides the same functionality as<br> .Xr lstat 2 .<br> .Pp<br> The functions<br> .Fn fileargs_open<br> and<br> .Fn fileargs_fopen<br> -are respectively equivalent to<br> +behave identically to<br> .Xr open 2<br> and<br> .Xr fopen 3<br> -expect that all arguments are fetched from the<br> +respectively, but retrieve their arguments from the<br> .Va fileargs_t<br> structure.<br> .Pp<br> The function<br> .Fn fileargs_realpath<br> -is equivalent to<br> -.Xr realpath 3 .<br> +provides the same functionality as the standard C library function<br> +.Xr realpath 3 ,<br> +resolving all symbolic links and references in a pathname.<br> .Pp<br> +The following functions are reentrant but require synchronization for<br> +thread safety:<br> .Fn fileargs_open ,<br> .Fn fileargs_lstat ,<br> .Fn fileargs_realpath ,<br> .Fn fileargs_cinitnv ,<br> .Fn fileargs_initnv ,<br> and<br> -.Fn fileargs_fopen<br> -are reentrant but not thread-safe.<br> -That is, they may be called from separate threads only with different<br> +.Fn fileargs_fopen .<br> +Multiple threads can call these functions safely only if they use different<br> .Vt cap_channel_t<br> -arguments or with synchronization.<br> +arguments or proper synchronization mechanisms.<br> .Sh LIMITS<br> -This section describe which values and types should be used to pass arguments to the<br> +This section describes the required and optional arguments that must be<br> +passed to<br> .Fa system.fileargs<br> -through the<br> +via the<br> .Fn fileargs_initnv<br> and<br> .Fn fileargs_cinitnv<br> -functions.<br> -The<br> +functions using an<br> .Xr nvlist 9<br> -for that functions must contain the following values and types:<br> +structure.<br> +.Pp<br> +The following arguments are required:<br> .Bl -ohang -offset indent<br> -.It flags ( NV_TYPE_NUMBER )<br> -The<br> -.Va flags<br> -limits opened files for either execution or reading and/or writing.<br> -.It mode (NV_TYPE_NUMBER)<br> -If in the<br> -.Va flags<br> -argument the<br> +.It flags Pq Dv NV_TYPE_NUMBER<br> +Specifies access permissions for opened files.<br> +.It mode Pq Dv NV_TYPE_NUMBER<br> +Required when the<br> .Dv O_CREATE<br> -flag was defined the<br> -.Xr nvlist 9<br> -must contain the<br> -.Va mode .<br> -The<br> -.Va mode<br> -argument tells which what mode file should be created.<br> -.It operations (NV_TYPE_NUMBER)<br> -The<br> -.Va operations<br> -limits the usable operations for<br> +flag is set in<br> +.Va flags .<br> +Specifies the permissions to use when creating new files.<br> +.It operations Pq Dv NV_TYPE_NUMBER<br> +Specifies which operations are allowed for<br> .Fa system.fileargs .<br> -The possible values are explained as<br> +See the description of the<br> .Va operations<br> -argument with<br> -.Fn fileargs_init .<br> +argument in<br> +.Fn fileargs_init<br> +for possible values.<br> .El<br> .Pp<br> -The<br> +The following arguments are optional in the<br> .Xr nvlist 9<br> -for that functions may contain the following values and types:<br> +structure:<br> .Bl -ohang -offset indent<br> -.It cap_rights ( NV_TYPE_BINARY )<br> +.It cap_rights Pq Dv NV_TYPE_BINARY<br> The<br> .Va cap_rights<br> -argument contains a list of the capability rights which file should be limited to.<br> -.It ( NV_TYPE_NULL )<br> -Any number of<br> +argument specifies the capability rights that will be applied to restrict<br> +access to opened files.<br> +.It filenames Pq Dv NV_TYPE_NULL<br> +Multiple<br> .Dv NV_TYPE_NULL<br> -where the name of the element is name of the file which can be opened.<br> +elements can be provided, where each element's name represents a file<br> +path that is allowed to be opened.<br> .El<br> .Sh EXAMPLES<br> -The following example first parse some options and then create the<br> -.Nm system.fileargs<br> -service with remaining arguments.<br> .Bd -literal<br> int ch, fd, i;<br> cap_rights_t rights;<br> @@ -287,16 +288,13 @@ fileargs_free(fa);<br> .Xr nv 9<br> .Sh HISTORY<br> The<br> -.Nm cap_fileargs<br> +.Nm<br> service first appeared in<br> .Fx 10.3 .<br> .Sh AUTHORS<br> .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org<br> .Sh BUGS<br> The<br> -.Lb cap_fileargs<br> -included in<br> -.Fx<br> -is considered experimental, and should not be deployed in production<br> -environments without careful consideration of the risks associated with<br> -the use of experimental operating system features.<br> +.Nm<br> +service is considered experimental and should be thoroughly evaluated<br> +for risks before deploying in production environments.<br> </blockquote></div>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAGOYWV9S3ajTworOJsgWrM17iW8CqZA6Z9rZa1Z9pqPgMp2z1A>