PTHREAD...DESTROY(3POSIX)

🌸 PROLOG 🌸

okay bestie, before literally anything else: this manual page is part of the POSIX Programmer's Manual. That's the tea. ☕

But lowkey important — the Linux implementation of this interface may differ, so if you're on Linux, go consult the corresponding Linux manual page for the actual details of Linux behavior. And possibly the interface isn't even implemented on Linux at all. 🙈 So like. vibe check your platform first, fr fr.

---

✨ 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 🦋

So pthread_attr_destroy() shall destroy a thread attributes object. That's the whole job. An implementation may cause pthread_attr_destroy() to set attr to an implementation-defined invalid value — so don't be surprised if it looks weird after, that's allowed.

Here's the part you need to remember, no cap: a destroyed attr attributes object can be reinitialized using pthread_attr_init(). But the results of otherwise referencing the object after it's been destroyed are undefined. 💀 So like, don't touch it. Just don't.

Meanwhile pthread_attr_init() shall initialize a thread attributes object attr with the default value for all of the individual attributes used by a given implementation. Everything starts at default, that's the vibe. ✨

And the resulting attributes object (possibly modified by setting individual attribute values) — when it's used by pthread_create() — defines the attributes of the thread that gets created. Iconic. Also: a single attributes object can be used in multiple simultaneous calls to pthread_create(). Reuse is fine, she's flexible. 🫶

But results are undefined if pthread_attr_init() is called specifying an already initialized attr attributes object. So don't double-init. Not the move. 😭

Also also — 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. So like, garbage in, undefined chaos out. 🙈

---

⭐ RETURN VALUE ⭐

Upon successful completion, pthread_attr_destroy() and pthread_attr_init() shall return a value of 0. Slay. 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. Bestie ran out of memory, it's giving sad girl hours. 😭

And listen: these functions shall not return an error code of [EINTR]. Not a thing here. Periodt. 💅

The following sections are informative. (so everything below is like, bonus lore, not law 📖)

---

🎀 EXAMPLES 🎀

None.

...yeah that's it. Nothing to show, she's mysterious. 🧚

---

🌈 APPLICATION USAGE 🌈

None.

Again — nothing. Truly minimal main character energy. 👑

---

🧠 RATIONALE 🧠

okay this is the long one, sit down, hydrate, let's go. 🍓

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. Forward-thinking queen. 💖

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. One place to edit? Obsessed. ✨

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. Chef's kiss. 👩‍🍳💋

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. Cross-vendor drama avoided, we love to see it. 🫶

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. Efficiency? Iconic. 🔥

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. Problem → solved. 💅

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. Machine-dependent things gonna machine-depend. 🤷

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. Careful, babes. 🎀

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.

The future is... blank. Manifesting nothing. ✨

---

🫶 SEE ALSO 🫶

• pthread_attr_getstacksize()
• pthread_attr_getdetachstate()
• pthread_create()

The Base Definitions volume of POSIX.1-2017, <pthread.h> 📚

---

💖 COPYRIGHT 💖

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

okay that's the whole page bestie, go forth and pthread_attr_init() responsibly 💅✨

IEEE/The Open Group — 2017 🎀 mwah, that's a wrap, drink some water, ilysm 🫶💖