From nobody Sat Jan 20 01:52:12 2024 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4TGzxm6t5Nz57v7l; Sat, 20 Jan 2024 01:52:12 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4TGzxm6Njfz4dH7; Sat, 20 Jan 2024 01:52:12 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1705715532; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=xApw3YEVJAmtsYEkkjI1mF4pK0+o7Z6gR2T7wtCX4ZU=; b=U32nY9YToiK5FpNbmdDaH7KxlANzpNk7pW5EWweHTdpwFIHAf7b1LKp3P7IvEJEj4A52WA sT+Nyaa2exkqg85F2GHwnSV4Qis9llullgKv+ZkImqydEgcwljsRf3/FFuVS7DpJFvJJHM KqFaU3cFtH3PuP6aKE1r6pxlttZYr4gmHrGbnDp+B2iy7UOpisOPK8zWU4lh9ICdbFYNqv ZZbhMZYB7J5DrlZSpleKR3T+1AXTuUgFfqJQP13vjkKVy9Ta1WT0IYHkjlE/R69sUz7NAr Qs9YTa5R8f+p2T4JWQIRIOu4bac2yfsnsiclCI8FfsbitDLiphryyTThlwi0/w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1705715532; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=xApw3YEVJAmtsYEkkjI1mF4pK0+o7Z6gR2T7wtCX4ZU=; b=xTQkOMW71IlGBq7TStI225dXvHRqnGYHt3oUp0YuK+iLsvtFTUL/bGMZTE2UB0dWcWUNW1 T0cPtaHuHTx2Ofc8JZ95/EAx8unKSCeGJNDc2+sgpQqA0kwPK9SRj4tCUV0p4u2o83gy35 QOse5hQksaJgJ9dkYmSflT9C5YzDNIB5q4EMd57n5aWfq1vl2Tz+kspuqcuFFSn1VYtXOy SiGNik+HeD5AJyNUKtpmI7TxRnaZ2GmqyIv5QhCo/Ug2QZkWVw0uORTBlan/LAj9k1eSaT dYO8GsdA3ZcoadUZ/063L5ZW7MjBSnzv5xJ4Wp2lbAWqr5d4ZnIj38EkMknPcw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1705715532; a=rsa-sha256; cv=none; b=DoAe//Wop9ZkWmAtoNTG+da2ND4nmbGnZ8f4OmieEmb2F2nS2Zz4sLS9avJKu9+M6YA/29 JnxB5qeq0RIHqyUYseCnW82cYbT+HLgoQ2WPuzzPqB6nAcX6AuucibYbQuPRJhR+nO4n9p 2CwBtkWLgmZ2Xq1HVfBR24YcS/tS73MxqgJnq6QsvXlahQWna7wHO4G0jP+0nhC9MPhNDk UgwCGHE9h38RZFuQEpeOm4CKuD3jHrtdQpCgH1L0FUqaAqnIJZbJ2kcneW9KHvRX+YAWph am7ojqzwn1gDs5Uc3zp3DNVfntcfHNX8dsH66eNAtlTcBjaGqcOi9AZP3DE0/Q== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4TGzxm5S0gzGDX; Sat, 20 Jan 2024 01:52:12 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.17.1/8.17.1) with ESMTP id 40K1qCjd070518; Sat, 20 Jan 2024 01:52:12 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.17.1/8.17.1/Submit) id 40K1qC8S070515; Sat, 20 Jan 2024 01:52:12 GMT (envelope-from git) Date: Sat, 20 Jan 2024 01:52:12 GMT Message-Id: <202401200152.40K1qC8S070515@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Alan Somers Subject: git: 0125d6a23ba9 - stable/14 - libcasper: document that most libcasper functions are not thread-safe List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-all@freebsd.org X-BeenThere: dev-commits-src-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: asomers X-Git-Repository: src X-Git-Refname: refs/heads/stable/14 X-Git-Reftype: branch X-Git-Commit: 0125d6a23ba93efc2587f9935600f9a607c80cb7 Auto-Submitted: auto-generated The branch stable/14 has been updated by asomers: URL: https://cgit.FreeBSD.org/src/commit/?id=0125d6a23ba93efc2587f9935600f9a607c80cb7 commit 0125d6a23ba93efc2587f9935600f9a607c80cb7 Author: Alan Somers AuthorDate: 2023-12-05 23:24:28 +0000 Commit: Alan Somers 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