mirror of
https://github.com/freebsd/freebsd-src
synced 2024-10-15 04:43:53 +00:00
6211cd4be3
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
129 lines
4.1 KiB
Groff
129 lines
4.1 KiB
Groff
.\" Copyright (c) 2002,2003 Alexey Zelkin <phantom@FreeBSD.org>
|
|
.\" All rights reserved.
|
|
.\" Copyright (c) 2024 The FreeBSD Foundation
|
|
.\"
|
|
.\" Portions of this documentation were written by Olivier Certner
|
|
.\" <olce@FreeBSD.org> 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
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd January 5, 2024
|
|
.Dt PTHREAD_ATTR_GET_NP 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pthread_attr_get_np
|
|
.Nd get attributes of an existing thread
|
|
.Sh LIBRARY
|
|
.Lb libpthread
|
|
.Sh SYNOPSIS
|
|
.In pthread_np.h
|
|
.Ft int
|
|
.Fn pthread_attr_get_np "pthread_t pid" "pthread_attr_t *dst"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn pthread_attr_get_np
|
|
function is used to retrieve the attributes of the specified thread into an
|
|
existing
|
|
.Vt pthread_attr_t
|
|
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
|
|
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
|
|
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 tid)
|
|
{
|
|
pthread_attr_t attr;
|
|
size_t 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
|
|
The
|
|
.Fn pthread_attr_get_np
|
|
function will fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
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 ,
|
|
.Xr pthread_attr_getschedparam 3 ,
|
|
.Xr pthread_attr_getschedpolicy 3 ,
|
|
.Xr pthread_attr_getscope 3 ,
|
|
.Xr pthread_attr_getstack 3 ,
|
|
.Xr pthread_attr_getstackaddr 3 ,
|
|
.Xr pthread_attr_getstacksize 3 ,
|
|
.Xr pthread_attr_init 3 ,
|
|
.Xr pthread_np 3
|
|
.Sh AUTHORS
|
|
The
|
|
.Fn pthread_attr_get_np
|
|
function and this manual page were written by
|
|
.An Alexey Zelkin Aq Mt phantom@FreeBSD.org ,
|
|
and the latter was revised by
|
|
.An Olivier Certner Aq Mt olce@FreeBSD.org .
|