git: cf037972ea88 - main - libcasper: document that most libcasper functions are not thread-safe
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Fri, 08 Dec 2023 16:23:01 UTC
The branch main has been updated by asomers: URL: https://cgit.FreeBSD.org/src/commit/?id=cf037972ea8863e2bab7461d77345367d2c1e054 commit cf037972ea8863e2bab7461d77345367d2c1e054 Author: Alan Somers <asomers@FreeBSD.org> AuthorDate: 2023-12-05 23:24:28 +0000 Commit: Alan Somers <asomers@FreeBSD.org> CommitDate: 2023-12-08 16:22:39 +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. MFC after: 2 weeks Sponsored by: Axcient Reviewed by: oshogbo Differential Revision: https://reviews.freebsd.org/D42928 --- 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