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