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

@@ -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
-.Fn cap_wrap
-function.
-It frees the
-.Vt cap_channel_t
-structure and returns
+function returns the
 .Xr unix 4
-domain socket associated with it.
+domain socket that was provided to the
+.Fn cap_wrap
+function,
+and frees the
+.Vt cap_channel_t
+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

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

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