PTHREAD_KEY_DELETE(3P)

🌸 PTHREAD_KEY_DELETE(3P) 🌸

okay bestie, welcome to the POSIX Programmer's Manual — that's the manual this page lives in, and yes the title of the page is literally PTHREAD_KEY_DELETE(3P), we're just saying it with our whole chest. 💖

🚨 PROLOG (read this first, fr fr)

This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ — so if you're on Linux, go consult the corresponding Linux manual page for the deets on Linux behavior. Or, plot twist, the interface might not even be implemented on Linux at all. 🙈

---

✨ NAME ✨

pthread_key_delete — thread-specific data key deletion 💅

---

🎀 SYNOPSIS 🎀

#include <pthread.h>

int pthread_key_delete(pthread_key_t key);

---

🦋 DESCRIPTION 🦋

So the pthread_key_delete() function shall delete a thread-specific data key that was previously returned by pthread_key_create(). That's the whole job. Iconic, honestly.

Here's the tea: the thread-specific data values associated with key do not need to be NULL at the time pthread_key_delete() is called. Not a problem. The responsibility of freeing any application storage, or performing any cleanup actions for data structures related to the deleted key or the associated thread-specific data in any threads — that's on the application. You. It's you. And the good news is you can do that cleanup either before or after you call pthread_key_delete(). Your call, bestie.

Any attempt to use key following the call to pthread_key_delete() results in undefined behavior. Not "kinda weird behavior", not "a warning", UNDEFINED. Do not touch it after. Periodt. 💀

Also very important:

• pthread_key_delete() shall be callable from within destructor functions. Yes, from inside a destructor. Slay.
• No destructor functions shall be invoked by pthread_key_delete(). It does not run your destructors for you. Not even one.
• Any destructor function that may have been associated with key shall no longer be called upon thread exit. It's retired. Gone. Off the roster. 🫶

---

⭐ RETURN VALUE ⭐

If it's successful, pthread_key_delete() shall return zero. Otherwise, an error number shall be returned to indicate the error. (Note: an error number, not -1 with errno vibes. We return the number itself, iykyk.)

---

🌈 ERRORS 🌈

The pthread_key_delete() function shall not return an error code of [EINTR]. Nope. Not on the menu.

The following sections are informative. 👑

---

💖 EXAMPLES 💖

None.

---

💜 APPLICATION USAGE 💜

None.

---

👑 RATIONALE 👑

okay so WHY does this function even exist? Let me explain, bestie.

A thread-specific data key deletion function has been included in order to allow the resources associated with an unused thread-specific data key to be freed. And when do unused thread-specific data keys even happen? Among other scenarios: when a dynamically loaded module that allocated a key is unloaded. Poof, key orphaned. 🧚

Conforming applications are responsible for performing any cleanup actions needed for data structures associated with the key to be deleted — and that includes data referenced by thread-specific data values. No such cleanup is done by pthread_key_delete(). In particular, destructor functions are not called. And there are several reasons for this division of responsibility, so let's get into it:

1. The associated destructor functions used to free thread-specific data at thread exit time are only guaranteed to work correctly when called in the thread that allocated the thread-specific data. (Destructors themselves may utilize thread-specific data, so yeah.) Because of that, they cannot be used to free thread-specific data in other threads at key deletion time. And trying to have them called by other threads at key deletion time would require other threads to be asynchronously interrupted. But since interrupted threads could be in an arbitrary state — including holding locks necessary for the destructor to run — this approach would fail. In general, there is no safe mechanism whereby an implementation could free thread-specific data at key deletion time. No cap.
2. Even if there were a means of safely freeing thread-specific data associated with keys to be deleted, doing so would require that implementations be able to enumerate the threads with non-NULL data and potentially keep them from creating more thread-specific data while the key deletion is occurring. And that special case could cause extra synchronization in the normal case, which would otherwise be unnecessary. Not worth it. 🙅

So how does an application know it's safe to delete a key? For an application to know that it is safe to delete a key, it has to know that all the threads that might potentially ever use the key do not attempt to use it again. For example, it could know this if all the client threads have called a cleanup procedure declaring that they are through with the module that is being shut down — perhaps by setting a reference count to zero. Cute and correct. ✨

And one more thing:

If an implementation detects that the value specified by the key argument to pthread_key_delete() 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 key value" — we're keeping that exactly as-is, typo and all, because facts are sacred. 💅)

---

🍓 FUTURE DIRECTIONS 🍓

None.

---

🔥 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 to you from IEEE/The Open Group, 2017, and the page name is PTHREAD_KEY_DELETE(3P) — go free those keys responsibly, and remember: don't touch the key after you delete it. 💖✨