\"      $NetBSD: pthread_attr_getstack.3,v 1.9 2023/12/07 16:55:01 riastradh Exp $
\"
\" Copyright (c) 2010 Jukka Ruohonen <[email protected]>
\" All rights reserved.
\"
\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 July 9, 2010
Dt PTHREAD_ATTR_GETSTACK 3
Os
Sh NAME
Nm pthread_attr_getstack ,
Nm pthread_attr_setstack ,
Nm pthread_attr_getstacksize ,
Nm pthread_attr_setstacksize ,
Nm pthread_attr_getstackaddr ,
Nm pthread_attr_setstackaddr
Nd get and set thread stack attributes
Sh LIBRARY
Lb libpthread
Sh SYNOPSIS
In pthread.h
Ft int
Fn pthread_attr_getstack \
"const pthread_attr_t * restrict attr" \
"void ** restrict stackaddr" "size_t * restrict stacksize"
Ft int
Fn pthread_attr_setstack \
"pthread_attr_t * restrict attr" "void *stackaddr" "size_t stacksize"
Ft int
Fn pthread_attr_getstacksize \
"const pthread_attr_t * restrict attr" "size_t * restrict stacksize"
Ft int
Fn pthread_attr_setstacksize \
"pthread_attr_t *attr" "size_t stacksize"
Ft int
Fn pthread_attr_getstackaddr \
"const pthread_attr_t * restrict attr" "void ** restrict stackaddr"
Ft int
Fn pthread_attr_setstackaddr \
"pthread_attr_t *attr" "void *stackaddr"
Sh DESCRIPTION
The
Fn pthread_attr_getstack
and
Fn pthread_attr_setstack
functions get and set, respectively, the thread stack attributes
Fa stackaddr
and
Fa stacksize
in the
Fa attr
object.
The remaining four functions behave similarly,
but instead of getting or setting both
Fa stackaddr
and
Fa stacksize ,
these get and set the values individually.
Pp
The
Fa stacksize
parameter is defined to be the minimum stack size (in bytes)
allocated for the thread's stack during the creation of the thread.
The
Fa stackaddr
attribute specifies the location of storage to be used for the thread's stack.
All pages within the stack described by
Fa stackaddr
and
Fa stacksize
should be both readable and writable by the thread.
Pp
The behavior is undefined in all functions if the
Fa attr
parameter does not refer to an attribute object initialized by using
Xr pthread_attr_init 3
prior to the call.
In addition, undefined behavior may follow if the
Fn pthread_attr_getstack
function is called before the
Fa stackaddr
attribute has been set.
Ss Rationale
The rationale behind these functions is to address cases where an application
may be used in an environment where the stack of a thread must be placed to
some particular region of memory.
For the majority of applications, this is seldom necessary,
and the use of these functions should be generally avoided.
At least few potential caveats can be mentioned.
Bl -bullet -offset 2n
It
There is a certain degree of ambiguity in the POSIX
standard with respect to thread stack.
It
The exact behavior of the functions may vary
both across machines and operating systems.
In particular, the address specified by
Fa stackaddr
should be suitably aligned.
The system page size, as specified by
Xr sysconf 3 ,
and the use of
Xr posix_memalign 3
may guarantee some degree of portability.
Also
Xr mmap 2
provides means for alignment.
It
If the application modifies the stack address, it claims also
the responsibility of allocating the stack area and guarding it against
possible stack overflow.
No default guard area will be allocated (see
Xr pthread_attr_getguardsize 3 ) .
It may be necessary to manually use
Xr mprotect 2
in order to define a guard area at the end of the allocated stack.
It
Moreover, if
Fa attr
is used to create multiple threads, the stack address must be changed
by the application between successive calls to
Xr pthread_create 3 .
El
Sh RETURN VALUES
If successful, these functions return 0.
Otherwise, an error number is returned to indicate the error.
Sh ERRORS
No errors are defined for the three functions that obtain the stack values.
The three functions that set the stack values may fail if:
Bl -tag -width Er
It Bq Er ENOMEM
There was insufficient memory to complete the operation.
El
Pp
The
Fn pthread_attr_setstacksize
function may additionally fail if:
Bl -tag -width Er
It Bq Er EINVAL
The specified
Fa stacksize
is less than
Dv PTHREAD_STACK_MIN
or exceeds some system-imposed limit.
El
Sh SEE ALSO
Xr pthread_attr 3 ,
Xr pthread_attr_setguardsize 3
Sh STANDARDS
All described functions conform to
St -p1003.1-2001 .
Note that
Fn pthread_attr_getstackaddr
and
Fn pthread_attr_setstackaddr
were however removed from the specification in the
St -p1003.1-2008
revision.
Sh BUGS
Older versions of
Nx ,
prior to 10.0, 9.4, and 8.3, incorrectly adjust the stack address by
the guard size in threads configured with
Fn pthread_attr_setstack ,
instead of ignoring the guard size in that case as
Tn POSIX
prescribes
Po
see
Lk https://gnats.NetBSD.org/57721 "PR lib/57721"
Pc .
Pp
Even if you didn't set a nonzero guard size with
Xr pthread_attr_setguardsize 3 ,
the system will choose a nonzero default guard size.
Pp
To work around this in applications that run on older and newer
versions of
Nx ,
as well as on other operating systems, you can safely set the guard
size to zero:
Dl "pthread_attr_setguardsize(&attr, 0);"

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.