From nobody Wed Nov 11 01:06:56 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 4jPQN11sVNz6y1nN for ; Wed, 11 Nov 2026 01:06:57 +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 4jPQN05w8Sz4nbh for ; Wed, 11 Nov 2026 01:06:56 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1794359216; 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=Onm8b6iqy3u57SAE1wQlft9DkwmIhHG6uMneDjsjCnU=; b=sekTEjIr35xIHguHRWIjVURpr3YSkqlNS2+Gpf8mo0C//V6Eh4rva8mlpIDdA5hdY6vPTH ybn2XB+rkEoQPL3NZI/NP8oFhGSJrsU6dNu0UA7rqkjPAKvNutsXZ6ey4zJ8V7SoBFM5Rj QA8nxfEXk9N8CH2Z4RThN0gwmXPij6dwrmvGhbSoSIiyOKk4tp+lyq7u5KtMkXhqVFNUaf cq/knkqVorxa77aHHUV+GxzeDpkaDjoovwnwIbGky9PXHrw/SWsoJhCRmHdzkOw4sc7FAB OS7mYkW3tu9sY+aCBe3jqB64/Luht1h5R9T71pBVhqIfO8iZFhnj/xv1kvYt2g== ARC-Seal: i=1; a=rsa-sha256; d=freebsd.org; s=dkim; cv=none; t=1794359216; b=JpirfJs+CP5CyuFFb3Mx7thTg2h2d7UKOudqeFsuomNvDvfaNBadTWnclNXWoHJdg13Ikw 96MQ2SoxOCZ3NC2CrN3nL6Q63HOEJUZKqqKUJUo5ISTdn+RWzgEuiVRql461xvLpPiwqi3 zRrNkpE4AuD21+ob6vjBgNPLiOttgIoKSxflGvCSkgVRzEYl2Lrdt22TQdrHyeyVcwGANh c78m7m8udHf7729bnyI7LZL5tyPDMTHqz6ssaK8y/EQhgF4DCPWw8rLsZZNwhKo0x+VJ/a c8W7360TiQpFXX4LuNUnouuJ/EhU61yxLHIZJCRFnzDcZtBNCeXWqhyYKN3/9Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1794359216; 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=Onm8b6iqy3u57SAE1wQlft9DkwmIhHG6uMneDjsjCnU=; b=D6CByPsbjw1leiylRq8DYGo8EwExxQu160dTai0fL12c934pWJ78UigZIrloP+tvPy5cYO M2BwUrnko+woeN4PIea9krvzeDnY7iHucJ5MmrqRxfnD93qQbSpWeUxq4xmkDoT+1XJJDB 2e58kK2jPgzo/rK3+jAXs68hpXRYjkYncXPcAtPQQL/HYVFOniwr2dTrVoEtZb4Q96ifRB 3vBXajzIyY4lvqE7T7roW6nvWYs1s/jfnmwzDI5P9PWoCXfz3ospS0y1kcrQemJNkeyGBD IrkiT+/bSRpOjWvqBvFXwywe2rdKvIFFF6j6Exig2WZzsGbDKGSXCAeQajVFjg== 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 4jPQN05Q1zzsZc for ; Wed, 11 Nov 2026 01:06:56 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 22733 by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Wed, 11 Nov 2026 01:06:56 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Konstantin Belousov Subject: git: f10f1e24fc9d - stable/15 - 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 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/stable/15 X-Git-Reftype: branch X-Git-Commit: f10f1e24fc9d7cd62221388dc0dc28aa97e95f39 Auto-Submitted: auto-generated Date: Wed, 11 Nov 2026 01:06:56 +0000 Message-Id: <6af3bfb0.22733.2a6e9fba@gitrepo.freebsd.org> The branch stable/15 has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=f10f1e24fc9d7cd62221388dc0dc28aa97e95f39 commit f10f1e24fc9d7cd62221388dc0dc28aa97e95f39 Author: Konstantin Belousov AuthorDate: 2026-10-19 20:43:55 +0000 Commit: Konstantin Belousov CommitDate: 2026-11-10 19:53:55 +0000 man3: document pthread_query_np(3) and pthread_query_all_np(3) (cherry picked from commit 7e904a6ef80321ad6ebd192126e05f8b714dce46) --- 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.