pthread_attr_setstacksize(3T) SDK R4.11 pthread_attr_setstacksize(3T)
NAME
pthreadattrsetstacksize, pthreadattrgetstacksize - manipulate
thread stacksize attribute
SYNOPSIS
#include <pthread.h>
int pthreadattrsetstacksize(pthreadattrt *attr,
sizet stacksize);
int pthreadattrgetstacksize(pthreadattrt *attr,
sizet *stacksize);
where:
attr A pointer to a thread attributes object, which should
have been initialized by a previous call to
pthreadattrinit().
stacksize For pthreadattrsetstacksize(), the stacksize attribute
for a newly created thread; default = 4096 on DG/UX
systems. For pthreadattrgetstacksize(), a pointer to a
variable to receive the stacksize attribute stored in the
thread attributes object.
DESCRIPTION
The stacksize attribute for threads defines the minimum stack size
(in bytes) with which a thread is created.
pthreadattrsetstacksize() sets the stacksize attribute in the
attribute object pointed to by attr. pthreadattrgetstacksize()
retrieves the value from the attributes object pointed to by attr.
Once specified in a thread attributes object, the stack size does not
take effect until the attributes object is used in a call to
pthreadcreate(), after which the attributes object is no longer
associated with the thread. Refer to pthreadattrinit(3T) for a
more detailed discussion of thread attributes objects.
The operating system may actually allocate a larger stack size than
the minimum specified. The actual stack is not allocated until the
thread is created. If the system cannot allocate the desired stack,
the call to pthreadcreate() will fail.
A thread's stack size may not be changed after the thread has been
created.
DIAGNOSTICS
Returns
If successful, pthreadattrgetstacksize() and
pthreadattrsetstacksize() return 0. Otherwise they return -1 and
set errno to indicate the error. In addition,
pthreadattrgetstacksize() stores the stack size attribute value in
the location pointed to by stacksize if successful.
Errors
For each of the following conditions, pthreadattrsetstacksize() and
pthreadattrgetstacksize() return -1 and set errno to the
corresponding value:
[EINVAL] An invalid attributes object has been specified. This
occurs when DG/UX has detected that the attributes object
pointed to by attr has not been initialized by a previous
call to pthreadattrinit() or has been corrupted.
For each of the following conditions, pthreadattrsetstacksize()
returns -1 and sets errno to the corresponding value:
[EINVAL] The value of stacksize is outside a system-imposed range.
For DG/UX, the minimum size that can be specified is 16
bytes and the maximum is 2^31 bytes.
SEE ALSO
pthreadattrinit(3T), pthreadattrdestroy(3T), pthreadcreate(3T).
NOTES
The DG/UX system defines the {_POSIX_THREAD_ATTR_STACKSIZE} symbol,
indicating that these functions are supported. Note that other
implementations may not necessarily provide support for specifying
thread stack sizes.
Currently, there is no portable way of specifying an extendable stack
size. As a result, the application writer must determine the correct
stack size for a thread through trial-and-error. As an aid, DG/UX
places an invalid page between thread stacks. If a stack overflows
by less than one page, the faulting thread will get a "clean"
SIGSEGV. In this case, the application should be modified to use
less stack space or to specify a larger stack size. Note that, if
the stack overflows by more than a page, another thread's stack could
get corrupted and the failure could be less clean. Typically, that
happens if a thread declares a large structure or array on its stack.
In the future, DG/UX plans to provide extendable thread stacks and
compiler support for ensuring that a thread does not poke beyond the
one-page (or specified) guard area beyond its stack. However, please
note that these conveniences may not be available on other platforms
to which the application is being ported. Until these types of
semantics are incorporated into a standard, most of the
responsibility rests on the application writer.
DG/UX currently allocates at least one page for each thread stack,
regardless of the specified minimum stack size. Furthermore, DG/UX
reserves a fixed-sized area at the base of the stack. This fixed-
sized area, which is planned to never exceed 256 bytes, is included
in the minimum stack size specified by the application. Given that
it is desirable to allocate stacks with page-multiple sizes, an
application should specify a minimum stack sizes in integral
multiples of a page, and should include the 256 potential reserved
bytes in its calculation.
There is a thread-creation performance advantage when all threads in
a process (more specifically in a thread group) have the same stack
size.
Licensed material--property of copyright holder(s)