PTHREAD_GETSPECIFIC(3P)

💖 PTHREAD_GETSPECIFIC(3P) 💖

okay bestie, welcome to the POSIX Programmer's Manual, we're doing thread-specific data management today and honestly? it's giving ✨organized chaos✨

🫶 PROLOG 🫶

so like, this manual page is part of the POSIX Programmer's Manual, periodt. but heads up: the Linux implementation of this interface may differ (so go consult the corresponding Linux manual page for the tea on Linux behavior), or the interface might not even be implemented on Linux at all. 💀 no cap.

---

🌸 NAME 🌸

pthread_getspecific, pthread_setspecific — thread-specific data management, and yes they're besties, they come as a pair 🫶

---

✨ SYNOPSIS ✨

#include <pthread.h>

void *pthread_getspecific(pthread_key_t key);
int pthread_setspecific(pthread_key_t key, const void *value);

---

💅 DESCRIPTION 💅

okay so first up, pthread_getspecific() shall return the value currently bound to the specified key on behalf of the calling thread. that's it, that's the whole job. iconic.

then pthread_setspecific() shall associate a thread-specific value with a key obtained via a previous call to pthread_key_create(). the way different threads may bind different values to the same key?? love that for them 💖 these values are typically pointers to blocks of dynamically allocated memory that have been reserved for use by the calling thread.

now the scary part bestie, pay attention: the effect of calling pthread_getspecific() or pthread_setspecific() with a key value not obtained from pthread_key_create(), or after key has been deleted with pthread_key_delete(), is undefined. undefined. we do not do that. 🙈

both pthread_getspecific() and pthread_setspecific() may be called from a thread-specific data destructor function. a call to pthread_getspecific() for the thread-specific data key being destroyed shall return the value NULL, unless the value is changed (after the destructor starts) by a call to pthread_setspecific(). and calling pthread_setspecific() from a thread-specific data destructor routine may result either in lost storage (after at least PTHREAD_DESTRUCTOR_ITERATIONS attempts at destruction) or in an infinite loop. 😭 yes really. be careful.

also, both functions may be implemented as macros. lowkey sneaky but okay. 🦋

---

🌈 RETURN VALUE 🌈

• pthread_getspecific() shall return the thread-specific data value associated with the given key. if no thread-specific data value is associated with key, then the value NULL shall be returned. simple as that 💜
• pthread_setspecific() — if successful, it shall return zero; otherwise, an error number shall be returned to indicate the error.

---

👑 ERRORS 👑

so pthread_getspecific()? no errors are returned from it. none. she's flawless, she doesn't do errors. 💅

the pthread_setspecific() function shall fail if:

• ENOMEM — insufficient memory exists to associate the non-NULL value with the key. 😭 the storage said no.

also, pthread_setspecific() shall not return an error code of [EINTR]. nope, not happening.

the following sections are informative. (iykyk, they're the vibes section, not the rules section)

---

🎀 EXAMPLES 🎀

None. 😌

---

🦋 APPLICATION USAGE 🦋

None. ✨

---

🧚 RATIONALE 🧚

okay so here's the reasoning bestie: performance and ease-of-use of pthread_getspecific() are critical for functions that rely on maintaining state in thread-specific data. since no errors are required to be detected by it, and since the only error that could be detected is the use of an invalid key, the function to pthread_getspecific() has been designed to favor speed and simplicity over error reporting. she's fast, she's simple, she doesn't snitch. periodt. 🔥

and if an implementation detects that the value specified by the key argument to pthread_setspecific() does not refer to a a key value obtained from pthread_key_create() or refers to a key that has been deleted with pthread_key_delete(), it is recommended that the function should fail and report an [EINVAL] error. (yes, the original says "a a", we are preserving that typo with love 💖)

---

⭐ FUTURE DIRECTIONS ⭐

None. nothing's changing, we're stable, we're at peace 🫶

---

🌸 SEE ALSO 🌸

• pthread_key_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 .

---

and that's the whole page bestie!! 🎀 this one came from IEEE/The Open Group, dated 2017, and it's the PTHREAD_GETSPECIFIC(3P) girlies' official page — thanks for reading, mwah, go forth and manage your thread-specific data responsibly 💖✨🫶