From nobody Fri Oct 30 13:52:37 2026 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 4jGMx20bK3z6wvLQ for ; Fri, 30 Oct 2026 13:52:38 +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) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 4jGMx168fSz4kBt for ; Fri, 30 Oct 2026 13:52:37 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1793368357; 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=ilx/01bVx7q11nRj8r49z1JED1GiahfFI3g1LzuUCOc=; b=AJTwwt8D56w1Utyh9dpAIyMPCPpWD8d6Vx+FCOP0oA5L+/AeVKlcDZXETEGHcBvcVQ+vCU QNHEUkuDQuTwOPO0ftBOb//x+cByakjgGcTLiwMKYwuLxohUG2p9/1osdTnClRxxiQ6Pcp dRTqetu8mH/eiLgCc8Nq37YmfaJHTrnwBkifQfiBlv2NPDqd3f4tHAZNhw9zlzLPU15hAM h3H5J/YgXPg0ivwbVesgP+B4GlK/RLjO4oTYdp44dayCErS/+MIhQry2ymLzbnx4IOJur2 UtZGRxSGK7wzkhkYIKEPfISHo20meQc5RUlSzFqLZnzoFXnp5E46d4zWTTBqBQ== ARC-Seal: i=1; a=rsa-sha256; d=freebsd.org; s=dkim; cv=none; t=1793368357; b=bSJLEF+VyMNIbOvXSBrX751adyfJbp5iAA2EEpMCuPuXLpZQ5YMRHxTqM4ZCdbcWX1LS/v SRAK3F9GpbEiqXAK+2vhTrEXmhXsi7q7yWQtbXkhrZ1SNKAGezw8dgvg77Ci++2xGQwouk TmRLUhH8dkvwcRjvapxOplgHk25Wm05zUkpCrqOhOyqAqd3e9eL2XbOQEmXxTPkmjnIoGO +ThQH7aHixvM6hXc1TdySq3bnkxSpaalhjL2DTzILr9WWh9ByZxUwXYGWh0I/GcHio5ZpX JYe157riao/6muRbwG90vM6VeZxUn9esf9sl2NuzO1k6HVCii2A/iTRNjj0j5A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1793368357; 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=ilx/01bVx7q11nRj8r49z1JED1GiahfFI3g1LzuUCOc=; b=FMaVSxAegrRzzq2gdP/RHA7wZ4GwYIM1RQnT1Z88/HyWY2bc3/0gdELlOqoqKCKrhRj3x0 fTfFr5fB0FsCIHOKVvwQZOqiM8F9UX08kuLCBHshSULYnWawDKG/I4Lz/p2lUAkvXCzXdb 1V9kXYl2Xp0jE45e8QmW8R0gFmXOaNR7qUSrZomtLghmo1t/e1JiqQpfy/FfVdLnonfD9f wjZ+71geFgJXphtNjmSy1uP2+Rd6aU8C0gMADdMiekYbBztWnkU8k3NVQVfq6/ghx/OinQ KVhn6i6CYTIDWoJWfU2pzefWQ3SeXvtVc8zjNMcQCBAk+ei3oRi+Bv/2rJf0mA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4jGMx15PlLzSyK for ; Fri, 30 Oct 2026 13:52:37 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 1ec27 by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Fri, 30 Oct 2026 13:52:37 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Konstantin Belousov Subject: git: 7e904a6ef803 - main - man3: document pthread_query_np(3) and pthread_query_all_np(3) List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org List-Id: Commit messages for all branches of the src repository List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: kib X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 7e904a6ef80321ad6ebd192126e05f8b714dce46 Auto-Submitted: auto-generated Date: Fri, 30 Oct 2026 13:52:37 +0000 Message-Id: <6ae4a125.1ec27.135f47cc@gitrepo.freebsd.org> The branch main has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=7e904a6ef80321ad6ebd192126e05f8b714dce46 commit 7e904a6ef80321ad6ebd192126e05f8b714dce46 Author: Konstantin Belousov AuthorDate: 2026-10-19 20:43:55 +0000 Commit: Konstantin Belousov CommitDate: 2026-10-30 13:51:03 +0000 man3: document pthread_query_np(3) and pthread_query_all_np(3) Reviewed by: aokblast, markj Sponsored by: The FreeBSD Foundation MFC after: 1 week Differential revision: https://reviews.freebsd.org/D60838 --- share/man/man3/Makefile | 2 + share/man/man3/pthread_query_np.3 | 254 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 256 insertions(+) diff --git a/share/man/man3/Makefile b/share/man/man3/Makefile index 2a4dbc426d05..874926bda0f1 100644 --- a/share/man/man3/Makefile +++ b/share/man/man3/Makefile @@ -447,6 +447,7 @@ PTHREAD_MAN= pthread.3 \ pthread_mutex_unlock.3 \ pthread_np.3 \ pthread_once.3 \ + pthread_query_np.3 \ pthread_resume_all_np.3 \ pthread_resume_np.3 \ pthread_rwlockattr_destroy.3 \ @@ -543,5 +544,6 @@ PTHREAD_MLINKS+=pthread_testcancel.3 pthread_setcancelstate.3 \ PTHREAD_MLINKS+=pthread_join.3 pthread_peekjoin_np.3 \ pthread_join.3 pthread_timedjoin_np.3 \ pthread_join.3 pthread_tryjoin_np.3 +PTHREAD_MLINKS+=pthread_query_np.3 pthread_query_all_np.3 .include diff --git a/share/man/man3/pthread_query_np.3 b/share/man/man3/pthread_query_np.3 new file mode 100644 index 000000000000..07f8adeb273c --- /dev/null +++ b/share/man/man3/pthread_query_np.3 @@ -0,0 +1,254 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright 2026 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov under sponsorship +.\" from the FreeBSD Foundation. +.\" +.Dd October 19, 2026 +.Dt PTHREAD_QUERY_NP 3 +.Os +.Sh NAME +.Nm pthread_query_all_np , +.Nm pthread_query_np +.Nd query thread information +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.In pthread_np.h +.Ft int +.Fo pthread_query_np +.Fa "pthread_t thread" +.Fa "struct pthread_info_np *info" +.Fa "size_t bufsz" +.Fc +.Ft int +.Fo pthread_query_all_np +.Fa "struct pthread_info_np *info" +.Fa "size_t *bufsz" +.Fc +.Sh DESCRIPTION +The +.Fn pthread_query_np +function returns the +.Fx +threading library implementation-specific information about +the thread specified by the +.Fa thread +argument. +The +.Fa info +argument must point to a +.Vt struct pthread_info_np +structure, which is filled with the following information +if the corresponding thread is found: +.Bd -literal +struct pthread_info_np { + size_t pthread_info_size; + pthread_t thread; + long lwpid; + enum pthread_state_np state; + int flags; + int cancel_state; + int *errno_location; + struct tcb *tcb; + struct uexterror *exterr; + char name[128]; +}; +.Ed +.Pp +The meaning of the structure fields is the following: +.Bl -tag -width pthread_info_size +.It Va pthread_info_size +The size of the structure. +If new fields are added in the future, it is guaranteed they will be +added at the end of the +.Vt pthread_info_np +structure. +.It Va thread +The thread identifier, as defined by the threading library. +.It Va lwpid +The thread identifier, as defined by the kernel. +See +.Xr pthread_getthreadid_np 3 . +.It Va state +The state of the thread. +Can be one of the following values: +.Bl -tag -width PTHREAD_STATE_SUSPENDED_NP +.It Dv PTHREAD_STATE_RUNNING_NP +Thread is runnable. +.It Dv PTHREAD_STATE_SUSPENDED_NP +Thread was suspended, see +.Xr pthread_suspend_np 3 . +.It Dv PTHREAD_STATE_DEAD_NP +Thread has exited but was not yet reclaimed by +.Xr pthread_join 3 . +.El +.It Va flags +Additional information about the reported thread is provided +by the following flags: +.Bl -tag -width PTHREAD_INFO_DETACHED_NP +.It Dv PTHREAD_INFO_DETACHED_NP +Set if the thread is detached, see +.Xr pthread_attr_setdetachstate 3 +and +.Xr pthread_detach 3 . +.It Dv PTHREAD_INFO_INITIAL_NP +Set if the thread was the first thread in the process, +that is it was executing the +.Fn main +function in the process. +.El +.It Va cancel_state +Provides information about the thread cancellability state, +as flags. +The following flags are defined: +.Bl -tag -width PTHREAD_INFO_CANCEL_AT_POINT_NP +.It Dv PTHREAD_INFO_CANCEL_ENABLED_NP +Cancellation is enabled, see +.Xr pthread_setcancelstate 3 . +.It Dv PTHREAD_INFO_CANCEL_ASYNC_NP +Thread cancellation is asynchronous, see +.Xr pthread_setcanceltype 3 . +.It Dv PTHREAD_INFO_CANCEL_PENDING_NP +The cancel event is pending, see +.Xr pthread_cancel 3 . +.It Dv PTHREAD_INFO_CANCEL_AT_POINT_NP +The thread is executing at a cancellation point. +.It Dv PTHREAD_INFO_CANCEL_IN_PROG_NP +The cancellation is in progress. +In particular, the stack unwinding might happen. +.El +.It Va errno_location +The address of the thread-private instance of the +.Xr errno 3 +variable. +.It Va tcb +The address of the architecture-specific thread control block. +The +.In machine/tls.h +header provides the definition of +.Vt struct tcb . +.It Va exterr +The location of the thread-private instance of the +.Vt struct uexterror , +used by the kernel to pass extended information about errors +from system calls. +See +.Xr exterror 9 . +.It Va name +Name of the thread, as set by +.Xr pthread_setname_np 3 . +.El +.Pp +The +.Fa bufsz +argument must specify the size of the passed structure. +At most +.Fa bufsz +bytes are copied to it. +The +.Va pthread_info_size +member reports the size of the buffer needed for +the full structure, +if the library has updated its definition. +The system guarantees that the layout of existing members +never changes. +.Pp +The +.Fn pthread_query_all_np +function returns the information about all threads in the calling +process. +The buffer pointed to by the +.Fa info +argument must have the size in bytes as provided by the value +pointed to by the +.Fa bufsz +argument. +To iterate over the buffer, increment the pointer to the previous +.Vt pthread_info_np +structure by its +.Va pthread_info_size +member. +The +.Fa bufsz +location is always updated with the size of the buffer required +to report all threads. +.Sh RETURN VALUES +If successful, the described functions return zero. +Otherwise an error number is returned to indicate the error or +special condition. +.Sh ERRORS +The +.Fn pthread_query_np +and +.Fn pthread_query_all_np +functions will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The threading library was not yet initialized. +.El +.Pp +The +.Fn pthread_query_np +function also fails if: +.Bl -tag -width Er +.It Bq Er ESRCH +The passed +.Fa thread +argument does not designate a valid thread. +.El +.Pp +The +.Fn pthread_query_all_np +function also fails if: +.Bl -tag -width Er +.It Bq Er ENOMEM +The value pointed to by the +.Fa bufsz +argument is too small. +The value is updated with the required size of the buffer. +.El +.Sh SEE ALSO +.Xr pthread 3 , +.Xr pthread_create 3 , +.Xr pthread_np 3 +.Sh STANDARDS +The +.Fn pthread_query_np +and +.Fn pthread_query_all_np +functions are an +.Fx +extension. +.Sh HISTORY +The described functions first appeared in +.Fx 16.0 . +.Sh CAVEATS +The +.Fn pthread_query_np +and +.Fn pthread_query_all_np +functions expose the internal transient state of the C runtime. +A running thread changes its state over time. +As such, it is up to the consumer of the interface to accommodate the +temporal nature of the reported values. +.Pp +For instance, the +.Va thread +thread library identifier can be reused +after the exited thread is joined, or, +for a detached thread, reclaimed. +The +.Va lwpid +kernel thread identifier can be reused immediately after the +thread exits. +Similarly, +.Va errno_location , +.Va tcb , +and +.Va exterr +pointers are only guaranteed to point to valid objects while +the thread has not exited.