From nobody Fri Aug 8 16:11:20 2025 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4bz8D43T9gz646xF; Fri, 08 Aug 2025 16:11:32 +0000 (UTC) (envelope-from oshogbo@freebsd.org) Received: from smtp.freebsd.org (smtp.freebsd.org [96.47.72.83]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "smtp.freebsd.org", Issuer "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4bz8D40k3cz3frQ; Fri, 08 Aug 2025 16:11:32 +0000 (UTC) (envelope-from oshogbo@freebsd.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1754669492; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=AJK21CzHGgK87Zfm8j1XLfJ030089U4ZnUYVZCqtNkM=; b=Qo8+e1e0Ah+fjCeJAq5RV82/VXe660kH1DDK6CbeVcsYvSFMNOVG11rUHJrAJfyRQYfKAm f/OQymM9ujUOCaMzUALSQqwEMM4J7CQsGUbIplsOyICUqrbLqc4Q1mOXIN7IC8kpudLtMQ hC8IKOFnFMKVBQWE1YBMcDa0F65IuUPVFoBHTRsDXnFVRZvWFUVGTUo5ty3PWbpAFkcfNl 5phWotXBDHSPHVLXCtf8KmYeFZCqiyE33NRWeSHIJj9lmn5Ougm8aHnmAvppXzTl6E4s4H B8FjmSBQCvzocnqgV9qJeZCx+ojy6di7IProPdSZmi0ZKMayD7k/24lWnVo2nA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1754669492; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=AJK21CzHGgK87Zfm8j1XLfJ030089U4ZnUYVZCqtNkM=; b=K+Ar2n2bNIKjbOuCckkiun9lkj/8I16GemG1aUdjIC9Y7u5NUMj+uxvMRU6HQIl5hjHGlW TLzNpYDtSScUoI+krxG+q5dq1Qcw924en196e9uUWPbMayr5B6ZOzp+5c1wZXPX5ECar0L tfWKTGNtl8ali51IfVOhr9EaaofsMc+Nj8vi7WZMgGGaJO/srS0W18G/IdGeP30SJfM4Zp G+h2zqkcUqohESHfoUsRvQlpfPG9J3SOayMU3RnQ2dbgu6oucm4gwoMmwc3OSNuNSODMPt 57lSKllL9yzdvO6kRsMC9Ecn/bmYNPMWZKyPA7bOoWpDW78t42FjXZjRvQhyig== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1754669492; a=rsa-sha256; cv=none; b=uo0VVgzz60kG9FFiNrzRI88tkG/sI6YajbjNxgirqzdRqyeNBaXZ8m5iB9iPpP+nXMhwJ9 gz3C3phBgM1beWm82EDVYtb9yXJFjDL06ZdMbxyMKYuRMQ6GBKxSvCI1TOb03MT9Kb5c/y a6ywcheQw5gWA+j/GpTFlzCqDqjf05wvs0cgauu+HGsudb22U7EkS0qpyLQxeoJSG7CNPD yb/KFKsQPuBlMZTlnSqVCFv90ZzNUE3ASgldR/t6YhiV/OFs2l2cUUI9zsMpuYCPowi30P LJN36vjkbMq61BBOD2Zd7x0/7ZHZFqEncyv1ptWJknp2S+SkIgCqbzGDr08i8w== Received: from mail-oo1-f47.google.com (mail-oo1-f47.google.com [209.85.161.47]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "WR4" (verified OK)) (Authenticated sender: oshogbo) by smtp.freebsd.org (Postfix) with ESMTPSA id 4bz8D36sQ9zM52; Fri, 08 Aug 2025 16:11:31 +0000 (UTC) (envelope-from oshogbo@freebsd.org) Received: by mail-oo1-f47.google.com with SMTP id 006d021491bc7-61b4b90fb87so1121613eaf.0; Fri, 08 Aug 2025 09:11:31 -0700 (PDT) X-Forwarded-Encrypted: i=1; AJvYcCWsT5IECdqU4qZjPcZ2R/K/Dr54R3LAJ1jkothvfvxJzuUAwu+SnyqsJkwgtW32amCQdVP7vsSZshEz7ykw6aIjPch6@freebsd.org, AJvYcCXGUtrckK2xdITcjFY/Dx0dOq9P7IAo/9b1TUYzGUxe91s5jwqDpHh/86EXPEp6Et/9P8jRKVYKmlMAfIbpIqNMhO4txDU=@freebsd.org X-Gm-Message-State: AOJu0Yyyj2HGOoeQT/sx+te7LtMocjMayIjQzVzJ7inHJF2DLDBbDEkj Ex1Y3H0d7wVKJDJuhSAAXU0FkqamsTQCLIi9be+1apuk8ddK77gHNdsAKhnKj92gZCyjOuz87hH AsLxn6/7CJOtJTXKDnp/2L/lRUN4ILbY= X-Google-Smtp-Source: AGHT+IEAVHjz4b3xraIalbNuvM0n41iZGIzxGzfklB29Odzvak33HoVn24+J7yUoo+GhAq7DMMohoCSIV6mrvWIyM8E= X-Received: by 2002:a05:6820:168a:b0:619:950f:2413 with SMTP id 006d021491bc7-61b7c2e5650mr1720221eaf.2.1754669491045; Fri, 08 Aug 2025 09:11:31 -0700 (PDT) List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 References: <202508081609.578G9oId013868@gitrepo.freebsd.org> In-Reply-To: <202508081609.578G9oId013868@gitrepo.freebsd.org> From: Mariusz Zaborski Date: Fri, 8 Aug 2025 18:11:20 +0200 X-Gmail-Original-Message-ID: X-Gm-Features: Ac12FXz2R-nWEjv9QoLRpF1kA1NYLhp1WnkNdaaVBUnXs_jXYlToi1a-1r841AY Message-ID: Subject: Re: git: 50dee972977a - main - cap_fileargs.3: Polish To: src-committers@freebsd.org, dev-commits-src-all@freebsd.org, dev-commits-src-main@freebsd.org Content-Type: multipart/alternative; boundary="000000000000b64d70063bdcd3c3" --000000000000b64d70063bdcd3c3 Content-Type: text/plain; charset="UTF-8" PR: https://github.com/freebsd/freebsd-src/pull/1551 On Fri, 8 Aug 2025 at 18:10, Mariusz Zaborski wrote: > The branch main has been updated by oshogbo: > > URL: > https://cgit.FreeBSD.org/src/commit/?id=50dee972977a17d47bd76f52c54461ee8581d1b1 > > commit 50dee972977a17d47bd76f52c54461ee8581d1b1 > Author: Faraz Vahedi > AuthorDate: 2024-12-14 15:43:36 +0000 > Commit: Mariusz Zaborski > 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 > --- > 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. > --000000000000b64d70063bdcd3c3 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
<= div class=3D"gmail_quote gmail_quote_container">
On Fri, 8 Aug 2025 at 18:10, Mariusz Zaborski <oshogbo@freebsd.org> wrote:
The branch main has been update= d by oshogbo:

URL: https://cgit.= FreeBSD.org/src/commit/?id=3D50dee972977a17d47bd76f52c54461ee8581d1b1
commit 50dee972977a17d47bd76f52c54461ee8581d1b1
Author:=C2=A0 =C2=A0 =C2=A0Faraz Vahedi <kfv@kfv.io>
AuthorDate: 2024-12-14 15:43:36 +0000
Commit:=C2=A0 =C2=A0 =C2=A0Mariusz Zaborski <oshogbo@FreeBSD.org>
CommitDate: 2025-08-08 16:08:21 +0000

=C2=A0 =C2=A0 cap_fileargs.3: Polish

=C2=A0 =C2=A0 Extensively revised the manual page with clearer phrasing, be= tter
=C2=A0 =C2=A0 structure, and corrected grammar throughout. Also fixed typos= and
=C2=A0 =C2=A0 improved overall readability of the documentation.

=C2=A0 =C2=A0 Signed-off-by: Faraz Vahedi <kfv@kfv.io>
---
=C2=A0lib/libcasper/services/cap_fileargs/cap_fileargs.3 | 174 ++++++++++--= ---------
=C2=A01 file changed, 86 insertions(+), 88 deletions(-)

diff --git a/lib/libcasper/services/cap_fileargs/cap_fileargs.3 b/lib/libca= sper/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 @@
=C2=A0.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSS= IBILITY OF
=C2=A0.\" SUCH DAMAGE.
=C2=A0.\"
-.Dd December 6, 2023
+.Dd August 8, 2025
=C2=A0.Dt CAP_FILEARGS 3
=C2=A0.Os
=C2=A0.Sh NAME
+.Nm cap_fileargs ,
=C2=A0.Nm fileargs_cinit ,
=C2=A0.Nm fileargs_cinitnv ,
=C2=A0.Nm fileargs_init ,
@@ -35,9 +36,8 @@
=C2=A0.Nm fileargs_open ,
=C2=A0.Nm fileargs_fopen
=C2=A0.Nd "library for handling files in capability mode"
-.Sh LIBRARY
-.Lb libcap_fileargs
=C2=A0.Sh SYNOPSIS
+.Lb libcap_fileargs
=C2=A0.In sys/nv.h
=C2=A0.In libcasper.h
=C2=A0.In casper/cap_fileargs.h
@@ -60,52 +60,57 @@
=C2=A0.Ft "char *"
=C2=A0.Fn fileargs_realpath "fileargs_t *fa" "const char *pa= thname" "char *reserved_path"
=C2=A0.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 =C2=A0.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.
=C2=A0.Pp
=C2=A0The function
=C2=A0.Fn fileargs_init
-create a service to the
+creates a service to the
=C2=A0.Nm system.fileargs .
=C2=A0The
=C2=A0.Fa argv
=C2=A0contains a list of files that should be opened.
=C2=A0The argument can be set to
=C2=A0.Dv NULL
-which will not create a service and all files will be prohibited to be ope= ned.
+to create no service and prohibit all files from being opened.
=C2=A0The
=C2=A0.Fa argc
-argument contains a number of passed files.
+argument contains the number of files passed to the program.
=C2=A0The
=C2=A0.Fa flags
-argument limits opened files for either execution or reading and/or writin= g.
+argument specifies whether files can be opened for execution, for reading,=
+and/or for writing.
=C2=A0The
=C2=A0.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
=C2=A0.Fa flags
=C2=A0and
=C2=A0.Fa mode
-arguments see
+arguments, see
=C2=A0.Xr open 2 .
=C2=A0The
=C2=A0.Fa rightsp
-argument contains a list of the capability rights which file should be lim= ited to.
-For more details of the capability rights see
+argument specifies the capability rights that will be applied to restrict<= br> +access to the files.
+For more information about capability rights, see
=C2=A0.Xr cap_rights_init 3 .
=C2=A0The
=C2=A0.Fa operations
-argument limits the operations that are available using
+argument specifies which operations are permitted when using
=C2=A0.Nm system.fileargs .
+The following flags can be combined to form the
=C2=A0.Fa operations
-is a combination of:
+value:
=C2=A0.Bl -ohang -offset indent
=C2=A0.It FA_OPEN
=C2=A0Allow
@@ -122,121 +127,117 @@ Allow
=C2=A0.Pp
=C2=A0The function
=C2=A0.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. =C2=A0.Pp
=C2=A0The functions
=C2=A0.Fn fileargs_initnv
=C2=A0and
=C2=A0.Fn fileargs_cinitnv
-are respectively equivalent to
+are equivalent to
=C2=A0.Fn fileargs_init
=C2=A0and
=C2=A0.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.
=C2=A0.Pp
=C2=A0The
-.Fa fileargs_free
-close connection to the
+.Fn fileargs_free
+function closes the connection to the
=C2=A0.Nm system.fileargs
-service and free are structures.
-The function handle
+service and frees all associated data structures.
+The function safely handles
=C2=A0.Dv NULL
-argument.
+arguments.
=C2=A0.Pp
=C2=A0The function
=C2=A0.Fn fileargs_lstat
-is equivalent to
+provides the same functionality as
=C2=A0.Xr lstat 2 .
=C2=A0.Pp
=C2=A0The functions
=C2=A0.Fn fileargs_open
=C2=A0and
=C2=A0.Fn fileargs_fopen
-are respectively equivalent to
+behave identically to
=C2=A0.Xr open 2
=C2=A0and
=C2=A0.Xr fopen 3
-expect that all arguments are fetched from the
+respectively, but retrieve their arguments from the
=C2=A0.Va fileargs_t
=C2=A0structure.
=C2=A0.Pp
=C2=A0The function
=C2=A0.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.
=C2=A0.Pp
+The following functions are reentrant but require synchronization for
+thread safety:
=C2=A0.Fn fileargs_open ,
=C2=A0.Fn fileargs_lstat ,
=C2=A0.Fn fileargs_realpath ,
=C2=A0.Fn fileargs_cinitnv ,
=C2=A0.Fn fileargs_initnv ,
=C2=A0and
-.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 differen= t
=C2=A0.Vt cap_channel_t
-arguments or with synchronization.
+arguments or proper synchronization mechanisms.
=C2=A0.Sh LIMITS
-This section describe which values and types should be used to pass argume= nts to the
+This section describes the required and optional arguments that must be +passed to
=C2=A0.Fa system.fileargs
-through the
+via the
=C2=A0.Fn fileargs_initnv
=C2=A0and
=C2=A0.Fn fileargs_cinitnv
-functions.
-The
+functions using an
=C2=A0.Xr nvlist 9
-for that functions must contain the following values and types:
+structure.
+.Pp
+The following arguments are required:
=C2=A0.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
=C2=A0.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
=C2=A0.Fa system.fileargs .
-The possible values are explained as
+See the description of the
=C2=A0.Va operations
-argument with
-.Fn fileargs_init .
+argument in
+.Fn fileargs_init
+for possible values.
=C2=A0.El
=C2=A0.Pp
-The
+The following arguments are optional in the
=C2=A0.Xr nvlist 9
-for that functions may contain the following values and types:
+structure:
=C2=A0.Bl -ohang -offset indent
-.It cap_rights ( NV_TYPE_BINARY )
+.It cap_rights Pq Dv NV_TYPE_BINARY
=C2=A0The
=C2=A0.Va cap_rights
-argument contains a list of the capability rights which file should be lim= ited to.
-.It ( NV_TYPE_NULL )
-Any number of
+argument specifies the capability rights that will be applied to restrict<= br> +access to opened files.
+.It filenames Pq Dv NV_TYPE_NULL
+Multiple
=C2=A0.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<= br> +path that is allowed to be opened.
=C2=A0.El
=C2=A0.Sh EXAMPLES
-The following example first parse some options and then create the
-.Nm system.fileargs
-service with remaining arguments.
=C2=A0.Bd -literal
=C2=A0int ch, fd, i;
=C2=A0cap_rights_t rights;
@@ -287,16 +288,13 @@ fileargs_free(fa);
=C2=A0.Xr nv 9
=C2=A0.Sh HISTORY
=C2=A0The
-.Nm cap_fileargs
+.Nm
=C2=A0service first appeared in
=C2=A0.Fx 10.3 .
=C2=A0.Sh AUTHORS
=C2=A0.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org
=C2=A0.Sh BUGS
=C2=A0The
-.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.
--000000000000b64d70063bdcd3c3--