SEM_INIT(3P)

💖 SEM_INIT(3P) — the POSIX Programmer's Manual era 💖

okay bestie, welcome to the POSIX Programmer's Manual section of the lore 🫶 this is SEM_INIT(3P) and she's here to set up an unnamed semaphore for you. slay.

---

⚠️ PROLOG ⚠️

so before we even get into it — this manual page is part of the POSIX Programmer's Manual. the Linux implementation of this interface may differ (so like, lowkey go read the corresponding Linux manual page for the deets on Linux behavior), or honestly the interface might not even be implemented on Linux at all. 💀 vibe check your platform first, fr fr.

---

✨ NAME ✨

sem_init — initialize an unnamed semaphore

like, she's the birth of a semaphore. the origin story. the main character's first scene. 👑

---

🎀 SYNOPSIS 🎀

#include <semaphore.h>

int sem_init(sem_t *sem, int pshared, unsigned value);

three args, one little include, and you're off. 🦋

---

💅 DESCRIPTION 💅

okay so the sem_init() function shall initialize the unnamed semaphore referred to by sem. and the value of the initialized semaphore? that's gonna be value. that's it. that's the whole vibe. ✨

following a successful call to sem_init(), the semaphore may be used in subsequent calls to sem_wait(), sem_timedwait(), sem_trywait(), sem_post(), and sem_destroy(). and this semaphore shall remain usable until the semaphore is destroyed — so like, she stays iconic until you say goodbye. no cap.

now the pshared tea ☕ :

• if the pshared argument has a non-zero value, then the semaphore is shared between processes; in this case, any process that can access the semaphore sem can use sem for performing sem_wait(), sem_timedwait(), sem_trywait(), sem_post(), and sem_destroy() operations. so like, cross-process besties. 🌈
• if the pshared argument is zero, then the semaphore is shared between threads of the process; any thread in this process can use sem for performing sem_wait(), sem_timedwait(), sem_trywait(), sem_post(), and sem_destroy() operations. so like, in-house besties only. 🫶

also, see Section 2.9.9, Synchronization Object Copies and Alternative Mappings for further requirements. iykyk, go read it, she's important. 📖

🚨 okay this next bit is the serious one: attempting to initialize an already initialized semaphore results in undefined behavior. not "it'll probably be fine" behavior. not "just try it" behavior. undefined. behavior. do not do this. not me warning you twice. 💀

---

🌸 RETURN VALUE 🌸

upon successful completion, the sem_init() function shall initialize the semaphore in sem and return 0.

otherwise, it shall return -1 and set errno to indicate the error. 😭 classic.

---

🔥 ERRORS 🔥

the sem_init() function shall fail if:

• EINVAL — the value argument exceeds {SEM_VALUE_MAX}. bestie you overshot the ceiling. 🎈
• ENOSPC — a resource required to initialize the semaphore has been exhausted, or the limit on semaphores ({SEM_NSEMS_MAX}) has been reached. the semaphore budget said no more. 💀
• EPERM — the process lacks appropriate privileges to initialize the semaphore. she said who authorized this. 🙈

and then: the following sections are informative. so like, they're the bonus content, not the rules. 💜

---

🧚 EXAMPLES 🧚

None.

(that's it. that's the section. she's mysterious. she's giving nothing and everything. ⭐)

---

🍓 APPLICATION USAGE 🍓

None.

(again. nothing. rest era. 💅)

---

🌈 RATIONALE 🌈

None.

(they really said no thoughts, head empty for all three of these. iconic honestly. 👑)

---

⭐ FUTURE DIRECTIONS ⭐

None.

(the future is wide open and unspecified, bestie. 🦋)

---

💜 SEE ALSO 💜

• sem_destroy()
• sem_post()
• sem_timedwait()
• sem_trywait()

and also, from The Base Definitions volume of POSIX.1‐2017: <semaphore.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. (she's the final boss, the one who decides who wins the argument, periodt.) 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, we ate and left no crumbs. 🫶 this has been IEEE/The Open Group, 2017 — signing off, SEM_INIT(3P), mwah 💅✨