huschi.net

PTHREAD_ATTR_GETSTACK(3P)  POSIX Programmer's Manual PTHREAD_ATTR_GETSTACK(3P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
NAME
       pthread_attr_getstack,  pthread_attr_setstack  -  get  and  set   stack
       attributes
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 *attr, void *stackaddr,
              size_t stacksize);


DESCRIPTION
       The   pthread_attr_getstack()  and  pthread_attr_setstack()  functions,
       respectively, shall get and set the thread  creation  stack  attributes
       stackaddr and stacksize in the attr object.
       The  stack  attributes  specify  the area of storage to be used for the
       created thread's stack. The base (lowest addressable byte) of the stor-
       age  shall be stackaddr, and the size of the storage shall be stacksize
       bytes. The stacksize shall be at least {PTHREAD_STACK_MIN}. The  stack-
       addr shall be aligned appropriately to be used as a stack; for example,
       pthread_attr_setstack() may fail with [EINVAL] if ( stackaddr & 0x7) is
       not  0. All pages within the stack described by stackaddr and stacksize
       shall be both readable and writable by the thread.
RETURN VALUE
       Upon successful completion, these functions shall return a value of  0;
       otherwise, an error number shall be returned to indicate the error.
       The  pthread_attr_getstack()  function  shall store the stack attribute
       values in stackaddr and stacksize if successful.
ERRORS
       The pthread_attr_setstack() function shall fail if:
       EINVAL The value of  stacksize  is  less  than  {PTHREAD_STACK_MIN}  or
              exceeds an implementation-defined limit.

       The pthread_attr_setstack() function may fail if:
       EINVAL The value of stackaddr does not have proper alignment to be used
              as a stack, or if ( stackaddr + stacksize) lacks  proper  align-
              ment.
       EACCES The  stack  page(s) described by stackaddr and stacksize are not
              both readable and writable by the thread.

       These functions shall not return an error code of [EINTR].
       The following sections are informative.
EXAMPLES
       None.
APPLICATION USAGE
       These functions are appropriate for use by applications in an  environ-
       ment  where  the  stack  for a thread must be placed in some particular
       region of memory.
       While it might seem that an application could detect stack overflow  by
       providing  a  protected  page  outside the specified stack region, this
       cannot be done portably. Implementations are free to place the thread's
       initial  stack pointer anywhere within the specified region to accommo-
       date the machine's stack pointer behavior and allocation  requirements.
       Furthermore, on some architectures, such as the IA-64, "overflow" might
       mean that two separate stack pointers allocated within the region  will
       overlap somewhere in the middle of the region.
RATIONALE
       None.
FUTURE DIRECTIONS
       None.
SEE ALSO
       pthread_attr_init(),  pthread_attr_setdetachstate(),  pthread_attr_set-
       stacksize(),  pthread_create(),  the   Base   Definitions   volume   of
       IEEE Std 1003.1-2001, <limits.h>, <pthread.h>
COPYRIGHT
       Portions  of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE and
       The  Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be  obtained  online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003            PTHREAD_ATTR_GETSTACK(3P)