NAME
pthread_attr_getstack —
get and set
thread stack attributes
LIBRARY
POSIX Threads Library (libpthread, -lpthread)
SYNOPSIS
#include <pthread.h>
int
pthread_attr_getstack(
const
pthread_attr_t * restrict attr,
void ** restrict stackaddr,
size_t * restrict
stacksize);
int
pthread_attr_setstack(
pthread_attr_t
* restrict attr,
void
*stackaddr,
size_t
stacksize);
int
pthread_attr_getstacksize(
const
pthread_attr_t * restrict attr,
size_t * restrict
stacksize);
int
pthread_attr_setstacksize(
pthread_attr_t
*attr,
size_t
stacksize);
int
pthread_attr_getstackaddr(
const
pthread_attr_t * restrict attr,
void ** restrict
stackaddr);
int
pthread_attr_setstackaddr(
pthread_attr_t
*attr,
void
*stackaddr);
DESCRIPTION
The
pthread_attr_getstack() and
pthread_attr_setstack() functions get and set, respectively,
the thread stack attributes
stackaddr and
stacksize in the
attr object. The
remaining four functions behave similarly, but instead of getting or setting
both
stackaddr and
stacksize,
these get and set the values individually.
The
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
stackaddr attribute specifies the location
of storage to be used for the thread's stack. All pages within the stack
described by
stackaddr and
stacksize should be both readable and writable by the
thread.
The behavior is undefined in all functions if the
attr
parameter does not refer to an attribute object initialized by using
pthread_attr_init(3)
prior to the call. In addition, undefined behavior may follow if the
pthread_attr_getstack() function is called before the
stackaddr attribute has been set.
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.
- There is a certain degree of ambiguity in the POSIX
standard with respect to thread stack.
- The exact behavior of the functions may vary both across
machines and operating systems. In particular, the address specified by
stackaddr should be suitably aligned. The system
page size, as specified by
sysconf(3), and the use of
posix_memalign(3)
may guarantee some degree of portability. Also
mmap(2) provides means for
alignment.
- 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
pthread_attr_getguardsize(3)).
It may be necessary to manually use
mprotect(2) in order to
define a guard area at the end of the allocated stack.
- Moreover, if attr is used to
create multiple threads, the stack address must be changed by the
application between successive calls to
pthread_create(3).
RETURN VALUES
If successful, these functions return 0. Otherwise, an error number is returned
to indicate the error.
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:
-
-
- [
ENOMEM
]
- There was insufficient memory to complete the
operation.
The
pthread_attr_setstacksize() function may additionally fail
if:
-
-
- [
EINVAL
]
- The specified stacksize is less than
PTHREAD_STACK_MIN
or exceeds some system-imposed
limit.
SEE ALSO
pthread_attr(3),
pthread_attr_setguardsize(3)
STANDARDS
All described functions conform to
IEEE Std 1003.1-2001
(“POSIX.1”). Note that
pthread_attr_getstackaddr() and
pthread_attr_setstackaddr() were however removed from the
specification in the
IEEE Std 1003.1-2008
(“POSIX.1”) revision.