# pthread_attr_destroy

## 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_destroy, pthread_attr_init — destroy and initialize
           the thread attributes object
    


## SYNOPSIS



           #include <pthread.h>
    
           int pthread_attr_destroy(pthread_attr_t *_attr_);
           int pthread_attr_init(pthread_attr_t *_attr_);
    


## DESCRIPTION



           The _pthread_attr_destroy_() function shall destroy a thread
           attributes object. An implementation may cause
           _pthread_attr_destroy_() to set _attr_ to an implementation-defined
           invalid value. A destroyed _attr_ attributes object can be
           reinitialized using _pthread_attr_init_(); the results of otherwise
           referencing the object after it has been destroyed are undefined.
    
           The _pthread_attr_init_() function shall initialize a thread
           attributes object _attr_ with the default value for all of the
           individual attributes used by a given implementation.
    
           The resulting attributes object (possibly modified by setting
           individual attribute values) when used by _pthread_create_() defines
           the attributes of the thread created. A single attributes object
           can be used in multiple simultaneous calls to _pthread_create_().
           Results are undefined if _pthread_attr_init_() is called specifying
           an already initialized _attr_ attributes object.
    
           The behavior is undefined if the value specified by the _attr_
           argument to _pthread_attr_destroy_() does not refer to an
           initialized thread attributes object.
    


## RETURN VALUE



           Upon successful completion, _pthread_attr_destroy_() and
           _pthread_attr_init_() shall return a value of 0; otherwise, an error
           number shall be returned to indicate the error.
    


## ERRORS



           The _pthread_attr_init_() function shall fail if:
    
           **ENOMEM** Insufficient memory exists to initialize the thread
                  attributes object.
    
           These functions shall not return an error code of **[EINTR]**.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           Attributes objects are provided for threads, mutexes, and
           condition variables as a mechanism to support probable future
           standardization in these areas without requiring that the function
           itself be changed.
    
           Attributes objects provide clean isolation of the configurable
           aspects of threads. For example, ``stack size'' is an important
           attribute of a thread, but it cannot be expressed portably. When
           porting a threaded program, stack sizes often need to be adjusted.
           The use of attributes objects can help by allowing the changes to
           be isolated in a single place, rather than being spread across
           every instance of thread creation.
    
           Attributes objects can be used to set up ``classes' of threads
           with similar attributes; for example, ``threads with large stacks
           and high priority'' or ``threads with minimal stacks''. These
           classes can be defined in a single place and then referenced
           wherever threads need to be created. Changes to ``class''
           decisions become straightforward, and detailed analysis of each
           _pthread_create_() call is not required.
    
           The attributes objects are defined as opaque types as an aid to
           extensibility. If these objects had been specified as structures,
           adding new attributes would force recompilation of all multi-
           threaded programs when the attributes objects are extended; this
           might not be possible if different program components were
           supplied by different vendors.
    
           Additionally, opaque attributes objects present opportunities for
           improving performance. Argument validity can be checked once when
           attributes are set, rather than each time a thread is created.
           Implementations often need to cache kernel objects that are
           expensive to create. Opaque attributes objects provide an
           efficient mechanism to detect when cached objects become invalid
           due to attribute changes.
    
           Since assignment is not necessarily defined on a given opaque
           type, implementation-defined default values cannot be defined in a
           portable way. The solution to this problem is to allow attributes
           objects to be initialized dynamically by attributes object
           initialization functions, so that default values can be supplied
           automatically by the implementation.
    
           The following proposal was provided as a suggested alternative to
           the supplied attributes:
    
            1. Maintain the style of passing a parameter formed by the
               bitwise-inclusive OR of flags to the initialization routines
               (_pthread_create_(), _pthread_mutex_init_(), _pthread_cond_init_()).
               The parameter containing the flags should be an opaque type
               for extensibility. If no flags are set in the parameter, then
               the objects are created with default characteristics. An
               implementation may specify implementation-defined flag values
               and associated behavior.
    
            2. If further specialization of mutexes and condition variables
               is necessary, implementations may specify additional
               procedures that operate on the **pthread_mutex_t** and
               **pthread_cond_t** objects (instead of on attributes objects).
    
           The difficulties with this solution are:
    
            1. A bitmask is not opaque if bits have to be set into bitvector
               attributes objects using explicitly-coded bitwise-inclusive OR
               operations. If the set of options exceeds an **int** , application
               programmers need to know the location of each bit. If bits are
               set or read by encapsulation (that is, get and set functions),
               then the bitmask is merely an implementation of attributes
               objects as currently defined and should not be exposed to the
               programmer.
    
            2. Many attributes are not Boolean or very small integral values.
               For example, scheduling policy may be placed in 3-bit or
               4-bit, but priority requires 5-bit or more, thereby taking up
               at least 8 bits out of a possible 16 bits on machines with
               16-bit integers. Because of this, the bitmask can only
               reasonably control whether particular attributes are set or
               not, and it cannot serve as the repository of the value
               itself. The value needs to be specified as a function
               parameter (which is non-extensible), or by setting a structure
               field (which is non-opaque), or by get and set functions
               (making the bitmask a redundant addition to the attributes
               objects).
    
           Stack size is defined as an optional attribute because the very
           notion of a stack is inherently machine-dependent. Some
           implementations may not be able to change the size of the stack,
           for example, and others may not need to because stack pages may be
           discontiguous and can be allocated and released on demand.
    
           The attribute mechanism has been designed in large measure for
           extensibility. Future extensions to the attribute mechanism or to
           any attributes object defined in this volume of POSIX.1‐2017 has
           to be done with care so as not to affect binary-compatibility.
    
           Attributes objects, even if allocated by means of dynamic
           allocation functions such as _malloc_(), may have their size fixed
           at compile time. This means, for example, a _pthread_create_() in an
           implementation with extensions to **pthread_attr_t** cannot look
           beyond the area that the binary application assumes is valid. This
           suggests that implementations should maintain a size field in the
           attributes object, as well as possibly version information, if
           extensions in different directions (possibly by different vendors)
           are to be accommodated.
    
           If an implementation detects that the value specified by the _attr_
           argument to _pthread_attr_destroy_() does not refer to an
           initialized thread attributes object, it is recommended that the
           function should fail and report an **[EINVAL]** error.
    
           If an implementation detects that the value specified by the _attr_
           argument to _pthread_attr_init_() refers to an already initialized
           thread attributes object, it is recommended that the function
           should fail and report an **[EBUSY]** error.
    


## FUTURE DIRECTIONS



           None.
    


* * *