From nobody Fri Jan 26 21:02:56 2024 X-Original-To: dev-commits-src-branches@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 4TM9Bm3tMmz58qmV; Fri, 26 Jan 2024 21:02:56 +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 4TM9Bm2s6tz4LvL; Fri, 26 Jan 2024 21:02:56 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1706302976; 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=vJMwk3sODRYH1L+PKg6sFxUAo8UDIfaezV216edF67s=; b=Pt/P6Z81VBhY/QXcawq3ngV7zWinUso6Jd46CLRwmyCDrJthZ/nrc8AUrb15BbXZjs0AJU N+hnwbCVfrAgLtoZH3zfy3TFZe0xOIkzBynLKRYyhuwNoZv3N1QSvIE1Fu/cd4upLzBlpP L3GhZCgqKVY0QJRZEjbJXl9xpUUUrHY7Qc8qvBkIrnYpawK1L5fyrJtCmL1q9nCpIlVBcU jeBsSmSkL9Se1O5exon+TJ34YakHZwAE3KqDmlzW1lRfwoOmJF4I3/57Q6jztpXdNUWSub vRR8BfwFHO9pbpn6Ghxq/nJfIPyknMelSe4A4aufnitr+BcyOCqlVcjmJTfI0g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1706302976; 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=vJMwk3sODRYH1L+PKg6sFxUAo8UDIfaezV216edF67s=; b=y2IFvxoEjUUaHa4aUaOTGr2s7fLTG4/yAOh9UVCpAucCG6eHoRlH35Dkjz9nBnDRWWi/PA 23TDtuCh9p8+HYvAb+zK5p7BkNPPke1C9L1NByDq8yTbEmCVGxfti6x8ivBKNbyTt8UMIP cQnVedWDwtBhhOY0VmbS/i5ifTxtv2+NqWgUPqPIC7eRjhvV0M0S64xmCEOxBu7MAIK720 84GxAEhBi6Fai18jvKBT/MelG17YjMK5XStrIVzbNLW09p1jNyAUh2H/SaGAL1FD6o3BSV 3Inmsi4ofJRk6E1QxMMJ3ckQxxbfIeXkh17g1NwJt26ffi8gA9FsXYOmr1RBAg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1706302976; a=rsa-sha256; cv=none; b=ExiKYgxSIKnN5xvJSaSO099q2t97IxDaQmsd7Tk/PdZp7KK55e/2uy0UDLsh5CB+uezp0I YSHiJBXQupobJCVBAL1d4EKbVU2a+qsAciJnIo3EW4aZMMvT+nWhaHwaY1FZBicuL9+arq Em8XArVrpdt8lM16obrDDr8NUM8R61e5opOPaaC0KGQeS6uclb/h/Lo/mnpkaX0TKyxjOm MbK7kjBwklmMBb3uGeDjEJYHRXYBkmx8IXYSkfRbzaorqbf9sFJRYpbKKQ5ttlFaBOq+F3 c4EuNi3nbX8UPcD4cp7IucD16E3LURWkch5XfgUvRua9OgRnOGJHrRpHJgkGhg== 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 4TM9Bm1yg0zxRb; Fri, 26 Jan 2024 21:02:56 +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 40QL2upk083891; Fri, 26 Jan 2024 21:02:56 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.17.1/8.17.1/Submit) id 40QL2ufg083888; Fri, 26 Jan 2024 21:02:56 GMT (envelope-from git) Date: Fri, 26 Jan 2024 21:02:56 GMT Message-Id: <202401262102.40QL2ufg083888@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Olivier Certner Subject: git: efdf24fd9bb9 - stable/14 - pthread_attr_get_np(3): Revamp List-Id: Commits to the stable branches of the FreeBSD src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-branches List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-branches@freebsd.org X-BeenThere: dev-commits-src-branches@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: olce X-Git-Repository: src X-Git-Refname: refs/heads/stable/14 X-Git-Reftype: branch X-Git-Commit: efdf24fd9bb92a3742fb16bb39a4c9940647b1b4 Auto-Submitted: auto-generated The branch stable/14 has been updated by olce: URL: https://cgit.FreeBSD.org/src/commit/?id=efdf24fd9bb92a3742fb16bb39a4c9940647b1b4 commit efdf24fd9bb92a3742fb16bb39a4c9940647b1b4 Author: Olivier Certner AuthorDate: 2024-01-05 13:14:48 +0000 Commit: Olivier Certner CommitDate: 2024-01-26 21:01:39 +0000 pthread_attr_get_np(3): Revamp Fix and more thoroughly describe the attributes object lifecycle. Also, correct the text about which attributes' values are reported. Add the ENOMEM error. While here, rephrase unclear passages, add references and fix the example's style. Reviewed by: kib, emaste Approved by: emaste (mentor) MFC after: 2 weeks Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D43330 (cherry picked from commit 6211cd4be32dfdc51b5ac452d4ead98a36ec42a6) Approved by: markj (mentor) --- share/man/man3/pthread_attr_get_np.3 | 84 +++++++++++++++++++++--------------- 1 file changed, 49 insertions(+), 35 deletions(-) diff --git a/share/man/man3/pthread_attr_get_np.3 b/share/man/man3/pthread_attr_get_np.3 index a13835287d7f..07153586c1b2 100644 --- a/share/man/man3/pthread_attr_get_np.3 +++ b/share/man/man3/pthread_attr_get_np.3 @@ -1,5 +1,10 @@ .\" Copyright (c) 2002,2003 Alexey Zelkin .\" All rights reserved. +.\" Copyright (c) 2024 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by Olivier Certner +.\" at Kumacom SARL under sponsorship from the +.\" FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -22,12 +27,12 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd October 12, 2021 +.Dd January 5, 2024 .Dt PTHREAD_ATTR_GET_NP 3 .Os .Sh NAME .Nm pthread_attr_get_np -.Nd get attributes of existent thread +.Nd get attributes of an existing thread .Sh LIBRARY .Lb libpthread .Sh SYNOPSIS @@ -37,51 +42,54 @@ .Sh DESCRIPTION The .Fn pthread_attr_get_np -function is used to get existent thread's attributes. -Most fields of -.Vt pthread_attr_t -structure are exact values of attributes provided at thread creation -time (as parameter to -.Xr pthread_create 3 -function), except for the stack address. -.Pp -Value returned as -.Fa dst -is supposed to be used in conjunction with -.Fn pthread_attr_get* -functions to retrieve individual values from +function is used to retrieve the attributes of the specified thread into an +existing .Vt pthread_attr_t structure. -Parameter -.Fa dst -should point to allocated memory area big enough to fit this structure. +The attributes' values are the current ones for the target thread, except for +the stack top address if not properly aligned for the architecture, since in +this case its value has been adjusted internally before use. .Pp -It is HIGHLY RECOMMENDED to use +Argument +.Fa dst +must be a pointer to a valid attributes object +.Po +it was initialized at some point by .Xr pthread_attr_init 3 -function to allocate attribute storage. -.Sh IMPLEMENTATION NOTES -The -.Fn pthread_attr_get_np -function will always return a pointer to the thread's real stack address, -regardless of its value in the original attributes structure. +and was not destroyed since then +.Pc . +After a successful call to +.Fn pthread_attr_get_np , +the individual attributes' values can be retrieved as usual via the +corresponding accessor functions as documented in +.Xr pthread_attr 3 . +After a failed call to +.Fn pthread_attr_get_np , +the object pointed to by +.Fa dst +is left unmodified, and can continue to be used as if the failed call never +happened. .Sh RETURN VALUES If successful, .Fn pthread_attr_get_np function returns 0. Otherwise, an error number is returned to indicate the error. .Sh EXAMPLES +This function retrieves the stack size of the thread specified by the +.Fa pid +argument: .Bd -literal size_t -my_thread_stack_size(pthread_t pid) +my_thread_stack_size(pthread_t tid) { - pthread_attr_t attr; - size_t size; + pthread_attr_t attr; + size_t size; - pthread_attr_init(&attr); - pthread_attr_get_np(pid, &attr); - pthread_attr_getstacksize(&attr, &size); - pthread_attr_destroy(&attr); - return(size); + pthread_attr_init(&attr); + pthread_attr_get_np(tid, &attr); + pthread_attr_getstacksize(&attr, &size); + pthread_attr_destroy(&attr); + return (size); } .Ed .Sh ERRORS @@ -90,12 +98,16 @@ The function will fail if: .Bl -tag -width Er .It Bq Er EINVAL -Invalid value for one of given parameters. +One of the arguments has an invalid value. .It Bq Er ESRCH No thread could be found corresponding to that specified by the given thread ID. +.It Bq Er ENOMEM +There was not enough memory to allocate additional storage needed by the attributes +object's implementation. .El .Sh SEE ALSO +.Xr pthread_attr 3 , .Xr pthread_attr_destroy 3 , .Xr pthread_attr_getdetachstate 3 , .Xr pthread_attr_getinheritsched 3 , @@ -111,4 +123,6 @@ thread ID. The .Fn pthread_attr_get_np function and this manual page were written by -.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org , +and the latter was revised by +.An Olivier Certner Aq Mt olce@FreeBSD.org .