PTHREAD_M...ETPSHARED(3P)

✨ PTHREAD_M...ETPSHARED 💅 — the POSIX Programmer's Manual page

okay bestie so this is a page out of the POSIX Programmer's Manual (yes, that one, the icon itself). Quick heads up before we get into it: 🫶

⚠️ This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (so go check the corresponding Linux manual page for the tea on Linux behavior), or the interface might not even be implemented on Linux at all. 🙈

---

🌸 NAME 🌸

pthread_mutexattr_getpshared, pthread_mutexattr_setpshared — get and set the process-shared attribute

the way these two are literally just the getter and the setter for one single little attribute?? iconic duo behavior fr fr 💖

---

🎀 SYNOPSIS 🎀

#include <pthread.h>

int pthread_mutexattr_getpshared(const pthread_mutexattr_t
    *restrict attr, int *restrict pshared);
int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr,
    int pshared);

note the restrict keywords, bestie — they're right there in the original and they are staying right there. no cap. ✨

---

💜 DESCRIPTION 💜

so here's the whole vibe:

• pthread_mutexattr_getpshared() shall obtain the value of the process-shared attribute from the attributes object referenced by attr. it's giving "lemme see what you set." 👀
• pthread_mutexattr_setpshared() shall set the process-shared attribute in an initialized attributes object referenced by attr. it's giving "okay setting it now, periodt." 💅

now the actual lore: the process-shared attribute gets set to PTHREAD_PROCESS_SHARED to permit a mutex to be operated upon by any thread that has access to the memory where the mutex is allocated — even if that mutex is allocated in memory that's shared by multiple processes. yes, multiple processes, not just threads. multi-process main character energy. 👑

for further requirements, see Section 2.9.9, Synchronization Object Copies and Alternative Mappings. (yes go read it, iykyk 📖)

the default value of the attribute shall be PTHREAD_PROCESS_PRIVATE. so if you don't touch it, it stays private. shy little default. 🍓

💀 undefined behavior alert 💀 — the behavior is undefined if the value specified by the attr argument to pthread_mutexattr_getpshared() or pthread_mutexattr_setpshared() does not refer to an initialized mutex attributes object. so like… initialize your objects, bestie. don't do crimes. 🚨

---

⭐ RETURN VALUE ⭐

• Upon successful completion, pthread_mutexattr_setpshared() shall return zero; otherwise, an error number shall be returned to indicate the error. zero is the good number, slay. ✨
• Upon successful completion, pthread_mutexattr_getpshared() shall return zero and store the value of the process-shared attribute of attr into the object referenced by the pshared parameter. otherwise, an error number shall be returned to indicate the error. so you get the return code and the value stuffed into pshared. two for one. 🎁

---

🦋 ERRORS 🦋

pthread_mutexattr_setpshared() may fail if:

• EINVAL — the new value specified for the attribute is outside the range of legal values for that attribute. basically you tried to set it to something that isn't a real option. not the move. 😭

also, these functions shall not return an error code of [EINTR]. nope, not a thing here. don't come looking for it. 💀

📌 heads up: the following sections are informative — meaning they're the commentary track, not the actual rules. 🎧

---

🌈 EXAMPLES 🌈

None.

(yeah. literally none. the void. we respect it. 🕳️✨)

---

💖 APPLICATION USAGE 💖

None.

(again, none! consistency queen. 👑)

---

🧚 RATIONALE 🧚

so if an implementation detects that the value specified by the attr argument to pthread_mutexattr_getpshared() or pthread_mutexattr_setpshared() does not refer to an initialized mutex attributes object, it is recommended that the function should fail and report an [EINVAL] error.

that's a recommendation, not a hard requirement — but honestly bestie, it's the polite thing to do. 🫶

---

🔥 FUTURE DIRECTIONS 🔥

None.

(three "None"s deep and we are still thriving. 🌸)

---

💅 SEE ALSO 💅

go check these out, they're all part of the same little friend group:

• pthread_cond_destroy()
• pthread_create()
• pthread_mutex_destroy()
• pthread_mutexattr_destroy()

and from The Base Definitions volume of POSIX.1‐2017: <pthread.h> — the header, the blueprint, the source of truth. 📚

---

👑 COPYRIGHT 👑

okay this part is important and we're keeping every single word, so:

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. (referee = the one that actually decides. respect the referee. 🏁)

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, 2017, and the header up top reads PTHREAD_M...ETPSHARED(3P) (yes, with the little ... in the middle, we love a mystery). go forth, share your mutexes across processes responsibly, and don't forget to initialize your attributes objects. mwah. 💋✨🌸