From nobody Fri Dec 8 16:23:01 2023 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 4SmxJP604Hz52ysc; Fri, 8 Dec 2023 16:23:01 +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 4SmxJP5V3Xz3K9W; Fri, 8 Dec 2023 16:23:01 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1702052581; 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=vTsxoMLaEA5cAECPxll4KYABueWfqD1pJU+ow7rLzQI=; b=wORzOAc31ht2ZjK9rW6ZyTvAUKQnVj98kgZoVZ8SDPqMz0oMmYDVY3HFun6oeFUxq8iElG 3/RMUTsGBrnwXI42xy8iu4HbgLvyz72dyRSVC6K0raHCeuVyoHoK0pMBKPSaq5nXRDHWkg 5jeujEeEHV7ILbjl6Rp4KQk1cdIkVPAI+GC8YC1tzMVO5mJH+5B4IuLIcm0F6coL7k+4vA u/ojDWTTK2ZCicUn7uUxQSeEJJsw/nb6JSq20Jd+pU4ojXTtXBmR/ho+ySuPRezZBJKB1j jBAPO3Y21wL/e7yCUD5rYT2cLxIJt7sCtrJqnxwyGYwhVaq4olvizgW8xIbieg== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1702052581; a=rsa-sha256; cv=none; b=SY76xE3b2N0dE7vcH7fVZa5SNRs/U4lmSMAmDudWnHC4J9uwr5NEufcQiY1fIGqMV/hkA5 nYtTS+LPUOoNrF7pTgwWvbHXVZa3qoeT0sap9CxWVexh/P/YQkTwHPHzkwqj4hbEKxa6tN wwOSBP3y1JSXKQ34D3FVFAyYKsBFa7ouXicFSKTvFa/XwuG4QiNVhlXOqy5s+3lQI+l2su S5FoK3mQmLPVxvYSG8G6uspRiQNn1Uw/ftz9Solb3YXbSXe5QhMmlcBdeTkBJOJ6JHAvgl Z/MRzYpLHNVzao6Be9IOaY7coY7Qsl8nsm92BjGXCjWH85KuVtMg084zx1gzYw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1702052581; 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=vTsxoMLaEA5cAECPxll4KYABueWfqD1pJU+ow7rLzQI=; b=AT5BdPUrXhgvM1NB5Tu563zz/l6kc9/Hy0u5HgiEw6RHgf1DWEGWDXJVW0m38n6jpteaEK lF6Z49khJYROtMfs09WtB+fp0GrlXlIFOZWzfE+n3bFE+S0GGjAiBlH7975pexNN/ytOrw vqDMwdYA35eOoT8kjS+K2SQPPgVodtyw6os/bT5lj+x56QzMZXJtMTMVP0HBRK0tvwqLlo nvYJ3/b7L/Xn/MhYEfFLXmPVFa8WREExAqA+7VfVhWj4bkXqKJ/ihM8508lQ2KZBDvnl1m Ep9EQtzL/W+KKw6Q6JbJYNuhelkwnq8C9L/XfqVKU7qyQfqN9oTo1bFo+WlVUw== 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 4SmxJP4YWpzCg8; Fri, 8 Dec 2023 16:23:01 +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 3B8GN1We050283; Fri, 8 Dec 2023 16:23:01 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.17.1/8.17.1/Submit) id 3B8GN1tA050280; Fri, 8 Dec 2023 16:23:01 GMT (envelope-from git) Date: Fri, 8 Dec 2023 16:23:01 GMT Message-Id: <202312081623.3B8GN1tA050280@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Alan Somers Subject: git: cf037972ea88 - main - 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/main X-Git-Reftype: branch X-Git-Commit: cf037972ea8863e2bab7461d77345367d2c1e054 Auto-Submitted: auto-generated The branch main has been updated by asomers: URL: https://cgit.FreeBSD.org/src/commit/?id=cf037972ea8863e2bab7461d77345367d2c1e054 commit cf037972ea8863e2bab7461d77345367d2c1e054 Author: Alan Somers AuthorDate: 2023-12-05 23:24:28 +0000 Commit: Alan Somers 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