git: 0125d6a23ba9 - stable/14 - libcasper: document that most libcasper functions are not thread-safe
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Sat, 20 Jan 2024 01:52:12 UTC
The branch stable/14 has been updated by asomers:
URL: https://cgit.FreeBSD.org/src/commit/?id=0125d6a23ba93efc2587f9935600f9a607c80cb7
commit 0125d6a23ba93efc2587f9935600f9a607c80cb7
Author: Alan Somers <asomers@FreeBSD.org>
AuthorDate: 2023-12-05 23:24:28 +0000
Commit: Alan Somers <asomers@FreeBSD.org>
CommitDate: 2024-01-20 01:51:58 +0000
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.
Sponsored by: Axcient
Reviewed by: oshogbo
Differential Revision: https://reviews.freebsd.org/D42928
(cherry picked from commit cf037972ea8863e2bab7461d77345367d2c1e054)
---
lib/libcasper/libcasper/libcasper.3 | 18 ++++++++++++++++--
lib/libcasper/services/cap_fileargs/cap_fileargs.3 | 14 +++++++++++++-
lib/libcasper/services/cap_grp/cap_grp.3 | 7 ++++++-
lib/libcasper/services/cap_net/cap_net.3 | 19 ++++++++++++++-----
lib/libcasper/services/cap_netdb/cap_netdb.3 | 6 +++++-
lib/libcasper/services/cap_pwd/cap_pwd.3 | 7 ++++++-
lib/libcasper/services/cap_sysctl/cap_sysctl.3 | 11 ++++++++++-
lib/libcasper/services/cap_syslog/cap_syslog.3 | 7 ++++++-
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