git: 406feaa862d7 - main - Initial clean up the language in the manual pages.
Date: Tue, 16 Nov 2021 14:00:44 UTC
The branch main has been updated by gnn: URL: https://cgit.FreeBSD.org/src/commit/?id=406feaa862d702d17ac3e8df096cfe22cdb7091a commit 406feaa862d702d17ac3e8df096cfe22cdb7091a Author: George V. Neville-Neil <gnn@FreeBSD.org> AuthorDate: 2021-11-10 06:38:36 +0000 Commit: George V. Neville-Neil <gnn@FreeBSD.org> CommitDate: 2021-11-10 18:09:18 +0000 Initial clean up the language in the manual pages. Summary: The manual pages need a bit of editing for language and clarity. Reviewers: oshogbo, #manpages Subscribers: imp Differential Revision: https://reviews.freebsd.org/D32976 --- lib/libcasper/libcasper/libcasper.3 | 98 ++++++++++++++++------------- lib/libcasper/libcasper/libcasper_service.3 | 35 +++++------ lib/libcasper/services/cap_net/cap_net.3 | 8 ++- 3 files changed, 75 insertions(+), 66 deletions(-) diff --git a/lib/libcasper/libcasper/libcasper.3 b/lib/libcasper/libcasper/libcasper.3 index bf678457abeb..c08ea0f21f8b 100644 --- a/lib/libcasper/libcasper/libcasper.3 +++ b/lib/libcasper/libcasper/libcasper.3 @@ -78,68 +78,71 @@ .Sh DESCRIPTION The .Nm libcasper -library allows to manage application capabilities through the casper process. +library provides for the control of application capabilities through the casper process. .Pp -The application capability (represented by the +An application capability, represented by the .Vt cap_channel_t -type) is a communication channel between the caller and the casper process -daemon or an instance of one of its services. -A capability to the casper process obtained with the +type, is a communication channel between the caller and the casper +daemon or an instance of one of the daemon's services. +A capability to the casper process, obtained with the .Fn cap_init -function allows to create capabilities to casper's services via the +function, allows a program to create capabilities to acacce +the casper daemon's services via the .Fn cap_service_open function. .Pp The .Fn cap_init -function opens capability to the casper process. +function instantiates a capability to allow a program to access +the casper daemon. .Pp The .Fn cap_wrap -function creates +function creates a .Vt cap_channel_t -based on the given socket. -The function is used when capability is inherited through +based on the socket supplied in the call. +The function is used when a capability is inherited through the .Xr execve 2 -or send over +system call, +or sent over a .Xr unix 4 -domain socket as a regular file descriptor and has to be represented as -.Vt cap_channel_t -again. +domain socket as a file descriptor, +nd has to be converted into a +.Vt cap_channel_t . The .Fa flags argument defines the channel behavior. The supported flags are: .Bl -ohang -offset indent .It CASPER_NO_UNIQ -The communication between process and casper uses no unique version of nvlist. +The communication between the process and the casper daemon no unique version of nvlist. .El .Pp The .Fn cap_unwrap -function is the opposite of the +function returns the +.Xr unix 4 +domain socket that was provided to the .Fn cap_wrap -function. -It frees the +function, +and frees the .Vt cap_channel_t -structure and returns -.Xr unix 4 -domain socket associated with it. +structure. .Pp The .Fn cap_clone -function clones the given capability. +function returns a clone of the capability passed as its only argument. .Pp The .Fn cap_close -function closes the given capability. +function closes, and frees, the given capability. .Pp The .Fn cap_sock -function returns +function returns the .Xr unix 4 domain socket descriptor associated with the given capability for use with -system calls like +system calls such as: .Xr kevent 2 , .Xr poll 2 and @@ -147,33 +150,36 @@ and .Pp The .Fn cap_limit_get -function stores current limits of the given capability in the +function stores the current limits of the given capability in the .Fa limitsp argument. -If the function return +If the function returns .Va 0 and .Dv NULL -is stored in +is stored in the .Fa limitsp -it means there are no limits set. +argument, +there are no limits set. .Pp The .Fn cap_limit_set function sets limits for the given capability. -The limits are provided as a +The limits are provided as an .Xr nvlist 9 . -The exact format depends on the service the capability represents. +The exact format of the limits depends on the service that the +capability represents. .Fn cap_limit_set -frees the limits regardless of whether the operation succeeds or fails. +frees the limits passed to the call, +whether or not the operation succeeds or fails. .Pp The .Fn cap_send_nvlist function sends the given .Xr nvlist 9 over the given capability. -This is low level interface to communicate with casper services. -Most services should provide higher level API. +This is a low level interface to communicate with casper services. +It is expected that most services will provide a higher level API. .Pp The .Fn cap_recv_nvlist @@ -185,41 +191,43 @@ The .Fn cap_xfer_nvlist function sends the given .Xr nvlist 9 , -destroys it and receives new +destroys it, and receives a new .Xr nvlist 9 in response over the given capability. It does not matter if the function succeeds or fails, the .Xr nvlist 9 -given for sending will always be destroyed once the function returns. +given for sending will always be destroyed before the function returns. .Pp The .Fn cap_service_open -function opens casper service of the given name through casper capability -obtained via the +function opens the casper service named in the call using +the casper capability obtained via the .Fn cap_init function. -The function returns capability that provides access to opened service. +The +.Fn cap_service_open +function returns a capability that provides access to the opened service. Casper supports the following services in the base system: .Pp .Bl -tag -width "system.random" -compact -offset indent .It system.dns -provides DNS libc compatible API +provides libc compatible DNS API .It system.grp -provides +provides a .Xr getgrent 3 compatible API .It system.net -provides network libc compatible API +provides a libc compatible network API .It system.pwd -provides +provides a .Xr getpwent 3 compatible API .It system.sysctl -provides +provides a .Xr sysctlbyname 3 compatible API .It system.syslog -provides +provides a .Xr syslog 3 compatible API .El diff --git a/lib/libcasper/libcasper/libcasper_service.3 b/lib/libcasper/libcasper/libcasper_service.3 index c0656a23a572..c210cdde182a 100644 --- a/lib/libcasper/libcasper/libcasper_service.3 +++ b/lib/libcasper/libcasper/libcasper_service.3 @@ -47,7 +47,7 @@ typedef int service_command_func_t(const char *, const nvlist_t *, nvlist_t *, .Sh DESCRIPTION The .Nm CREATE_SERVICE -macro to create a new Casper service. +macro is used to create a new Casper service. The .Fa name is a string containing the service name, which will be used in the @@ -57,44 +57,43 @@ function to identify it. The .Fa limit_func is a function of type -.Li service_limit_func_t . -The first argument of the function contains +.Li service_limit_func_t +where the first argument of the function contains an containing .Xr nvlist 9 , -old service limits and second one the new limits. -If the services wasn't limited the old limits will be set to +old service limits and the second argument contains the new limits. +If the service wasn't limited then the old limits will be set to .Dv NULL . -This function should not allow to extend service limits and only limit it -further. +This function must not allow the extension of service limits. The .Fa command_func is a function of type -.Li service_command_func_t . -First argument is the name of the command that should be executed. +.Li service_command_func_t +where the first argument is the name of the command that should be executed. The first .Xr nvlist 9 -contains the current limits. -Next one contains a +contains the current limits and the second contains an .Xr nvlist 9 -with current request. -The last one contains an output +with the current request. +The last argument contains a return value .Xr nvlist 9 which contains the response from Casper. .Pp The .Fa flags -argument defines limits of the service. +argument defines the limits of the service. The supported flags are: .Bl -ohang -offset indent .It CASPER_SERVICE_STDIO The Casper service has access to the stdio descriptors from the process it was spawned from. .It CASPER_SERVICE_FD -The Casper service has access to all descriptors besides stdio descriptors from -the process it was spawned from. +The Casper service has access to all of the descriptors, +besides the stdio descriptors, +from the process it was spawned from. .It CASPER_SERVICE_NO_UNIQ_LIMITS -The whole Casper communication is using +The whole Casper communication is using an .Xr nvlist 9 -with +with the .Xr NVLIST_NO_UNIQ 9 flag. .El diff --git a/lib/libcasper/services/cap_net/cap_net.3 b/lib/libcasper/services/cap_net/cap_net.3 index e74f7dd70d67..765abbdf41aa 100644 --- a/lib/libcasper/services/cap_net/cap_net.3 +++ b/lib/libcasper/services/cap_net/cap_net.3 @@ -91,7 +91,7 @@ The functions .Fn cap_gethostbyaddr and .Fn cap_getnameinfo -are respectively equivalent to +provide a set of APIs equivalent to .Xr bind 2 , .Xr connect 2 , .Xr gethostbyname 3 , @@ -99,7 +99,7 @@ are respectively equivalent to .Xr gethostbyaddr 3 and .Xr getnameinfo 3 -except that the connection to the +except that a connection to the .Nm system.net service needs to be provided. .Sh LIMITS @@ -107,8 +107,10 @@ By default, the cap_net capability provides unrestricted access to the network namespace. Applications typically only require access to a small portion of the network namespace: +The .Fn cap_net_limit -interface can be used to restrict access to the network. +function can be used to restrict access to the network. +The .Fn cap_net_limit_init returns an opaque limit handle used to store a list of capabilities. The