libcasper: document that most libcasper functions are not thread-safe

And neither are most libcasper services' functions, because internally
they all use cap_xfer_nvlist.  cap_xfer_nvlist sends and then receives
data over a unix domain socket and associated with the cap_channel_t
argument.  So absent synchronization, two threads may not use the same
cap_channel_t argument or they risk receiving the other's reply.

MFC after:	2 weeks
Sponsored by:	Axcient
Reviewed by:	oshogbo
Differential Revision: https://reviews.freebsd.org/D42928

8 files changed, 76 insertions, 13 deletions

diff --git a/lib/libcasper/libcasper/libcasper.3 b/lib/libcasper/libcasper/libcasper.3
index ccd347232777..15f231d7e366 100644
--- a/lib/libcasper/libcasper/libcasper.3
+++ b/lib/libcasper/libcasper/libcasper.3
@@ -26,7 +26,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd September 6, 2023
+.Dd December 6, 2023
 .Dt LIBCASPER 3
 .Os
 .Sh NAME
@@ -94,7 +94,6 @@ The
 .Fn cap_init
 function instantiates a capability to allow a program to access
 the casper daemon.
-It must be called from a single-threaded context.
 .Pp
 The
 .Fn cap_wrap
@@ -235,6 +234,21 @@ provides a
 .Xr syslog 3
 compatible API
 .El
+.Pp
+.Fn cap_init
+must be called from a single-threaded context.
+.Fn cap_clone ,
+.Fn cap_close ,
+.Fn cap_limit_get ,
+.Fn cap_limit_set ,
+.Fn cap_send_nvlist ,
+.Fn cap_recv_nvlist ,
+and
+.Fn cap_service_open
+are reentrant but not thread-safe.
+That is, they may be called from separate threads only with different
+.Vt cap_channel_t
+arguments or with synchronization.
 .Sh RETURN VALUES
 The
 .Fn cap_clone ,
diff --git a/lib/libcasper/services/cap_fileargs/cap_fileargs.3 b/lib/libcasper/services/cap_fileargs/cap_fileargs.3
index ef43c26cb3ed..c7ce45c518d1 100644
--- a/lib/libcasper/services/cap_fileargs/cap_fileargs.3
+++ b/lib/libcasper/services/cap_fileargs/cap_fileargs.3
@@ -22,7 +22,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd January 10, 2021
+.Dd December 6, 2023
 .Dt CAP_FILEARGS 3
 .Os
 .Sh NAME
@@ -169,6 +169,18 @@ The function
 .Fn fileargs_realpath
 is equivalent to
 .Xr realpath 3 .
+.Pp
+.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
+.Vt cap_channel_t
+arguments or with synchronization.
 .Sh LIMITS
 This section describe which values and types should be used to pass arguments to the
 .Fa system.fileargs
diff --git a/lib/libcasper/services/cap_grp/cap_grp.3 b/lib/libcasper/services/cap_grp/cap_grp.3
index 7c1bf0320e25..9647b1936b0c 100644
--- a/lib/libcasper/services/cap_grp/cap_grp.3
+++ b/lib/libcasper/services/cap_grp/cap_grp.3
@@ -22,7 +22,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd May 5, 2020
+.Dd December 6, 2023
 .Dt CAP_GRP 3
 .Os
 .Sh NAME
@@ -152,6 +152,11 @@ The
 and
 .Fa ngids
 variables provide numbers of limited names and gids.
+.Pp
+All of these functions are reentrant but not thread-safe.
+That is, they may be called from separate threads only with different
+.Vt cap_channel_t
+arguments or with synchronization.
 .Sh EXAMPLES
 The following example first opens a capability to casper and then uses this
 capability to create the
diff --git a/lib/libcasper/services/cap_net/cap_net.3 b/lib/libcasper/services/cap_net/cap_net.3
index 534d28c2ef7c..6e525508d3c4 100644
--- a/lib/libcasper/services/cap_net/cap_net.3
+++ b/lib/libcasper/services/cap_net/cap_net.3
@@ -21,7 +21,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd December 5, 2023
+.Dd December 6, 2023
 .Dt CAP_NET 3
 .Os
 .Sh NAME
@@ -84,22 +84,31 @@
 The functions
 .Fn cap_bind ,
 .Fn cap_connect ,
+.Fn cap_getaddrinfo ,
+.Fn cap_getnameinfo ,
 .Fn cap_gethostbyname ,
 .Fn cap_gethostbyname2 ,
-.Fn cap_gethostbyaddr
 and
-.Fn cap_getnameinfo
+.Fn cap_gethostbyaddr
 provide a set of APIs equivalent to
 .Xr bind 2 ,
 .Xr connect 2 ,
+.Xr getaddrinfo 3 ,
+.Xr getnameinfo 3 ,
 .Xr gethostbyname 3 ,
 .Xr gethostbyname2 3 ,
-.Xr gethostbyaddr 3
 and
-.Xr getnameinfo 3
+.Xr gethostbyaddr 3
 except that a connection to the
 .Nm system.net
 service needs to be provided.
+.Pp
+These functions, as well as
+.Fn cap_net_limit ,
+are reentrant but not thread-safe.
+That is, they may be called from separate threads only with different
+.Vt cap_channel_t
+arguments or with synchronization.
 .Sh LIMITS
 By default, the cap_net capability provides unrestricted access to the network
 namespace.
diff --git a/lib/libcasper/services/cap_netdb/cap_netdb.3 b/lib/libcasper/services/cap_netdb/cap_netdb.3
index 1f08ff275067..1f587c2057e7 100644
--- a/lib/libcasper/services/cap_netdb/cap_netdb.3
+++ b/lib/libcasper/services/cap_netdb/cap_netdb.3
@@ -21,7 +21,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd September 29, 2022
+.Dd December 6, 2023
 .Dt CAP_NETDB 3
 .Os
 .Sh NAME
@@ -43,6 +43,10 @@ is equivalent to
 except that the connection to the
 .Nm system.netdb
 service needs to be provided.
+It is reentrant but not thread-safe.
+That is, it may be called from separate threads only with different
+.Vt cap_channel_t
+arguments or with synchronization.
 .Sh EXAMPLES
 The following example first opens a capability to casper and then uses this
 capability to create the
diff --git a/lib/libcasper/services/cap_pwd/cap_pwd.3 b/lib/libcasper/services/cap_pwd/cap_pwd.3
index 7417d177a678..b66a0cd083ba 100644
--- a/lib/libcasper/services/cap_pwd/cap_pwd.3
+++ b/lib/libcasper/services/cap_pwd/cap_pwd.3
@@ -22,7 +22,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd May 5, 2020
+.Dd December 6, 2023
 .Dt CAP_PWD 3
 .Os
 .Sh NAME
@@ -158,6 +158,11 @@ The
 and
 .Fa nuids
 variables provide numbers of limited names and uids.
+.Pp
+All of these functions are reentrant but not thread-safe.
+That is, they may be called from separate threads only with different
+.Vt cap_channel_t
+arguments or with synchronization.
 .Sh EXAMPLES
 The following example first opens a capability to casper and then uses this
 capability to create the
diff --git a/lib/libcasper/services/cap_sysctl/cap_sysctl.3 b/lib/libcasper/services/cap_sysctl/cap_sysctl.3
index c007c04aa3b7..2c7a491a1f8b 100644
--- a/lib/libcasper/services/cap_sysctl/cap_sysctl.3
+++ b/lib/libcasper/services/cap_sysctl/cap_sysctl.3
@@ -22,7 +22,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd December 1, 2022
+.Dd December 6, 2023
 .Dt CAP_SYSCTL 3
 .Os
 .Sh NAME
@@ -64,6 +64,15 @@ except that they are implemented by the
 service and require a corresponding
 .Xr libcasper 3
 capability.
+.Pp
+All of these functions, with the exceptions of
+.Fn cap_sysctl_limit_init
+and
+.Fn cap_sysctl_limit_mib ,
+are reentrant but not thread-safe.
+That is, they may be called from separate threads only with different
+.Vt cap_channel_t
+arguments or with synchronization.
 .Sh LIMITS
 By default, the
 .Nm
diff --git a/lib/libcasper/services/cap_syslog/cap_syslog.3 b/lib/libcasper/services/cap_syslog/cap_syslog.3
index 7e5376c5ca89..4d6463ef3f81 100644
--- a/lib/libcasper/services/cap_syslog/cap_syslog.3
+++ b/lib/libcasper/services/cap_syslog/cap_syslog.3
@@ -22,7 +22,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd May 5, 2020
+.Dd December 6, 2023
 .Dt CAP_SYSLOG 3
 .Os
 .Sh NAME
@@ -63,6 +63,11 @@ are respectively equivalent to
 except that the connection to the
 .Nm system.syslog
 service needs to be provided.
+.Pp
+All of these functions are reentrant but not thread-safe.
+That is, they may be called from separate threads only with different
+.Vt cap_channel_t
+arguments or with synchronization.
 .Sh EXAMPLES
 The following example first opens a capability to casper and then uses this
 capability to create the