SEM_POST(3P)

💅 SEM_POST(3P) — the POSIX girlies' semaphore unlock 💖

okay bestie, so this one's from the POSIX Programmer's Manual — that's the manual name, we're in SEM_POST(3P) territory, and it's genuinely one of the most iconic little functions in the whole concurrency saga. ✨

⚠️ real talk first: this page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (so like, go check the corresponding Linux manual page for the actual Linux behavior, no cap), and honestly the interface may not be implemented on Linux at all. vibe check accordingly. 🫶

---

🌸 NAME 🌸

sem_post — unlock a semaphore. that's it. that's the whole job. unlock a semaphore. 💅

---

✨ SYNOPSIS ✨

#include <semaphore.h>

int sem_post(sem_t *sem);

---

🦋 DESCRIPTION 🦋

so the sem_post() function shall unlock the semaphore referenced by sem by performing a semaphore unlock operation on that semaphore. slay.

now here's the tea, and it depends entirely on what the semaphore value looks like after the op:

• If the semaphore value resulting from this operation is positive, then literally no threads were blocked waiting for the semaphore to become unlocked — so the semaphore value is simply incremented. easy. no drama. 🌈
• If the value of the semaphore resulting from this operation is zero, then one of the threads blocked waiting for the semaphore shall be allowed to return successfully from its call to sem_wait(). ✨

and okay, which thread gets unblocked? that's where it gets spicy:

• If the Process Scheduling option is supported, the thread to be unblocked shall be chosen in a manner appropriate to the scheduling policies and parameters in effect for the blocked threads.
• In the case of the schedulers SCHED_FIFO and SCHED_RR, the highest priority waiting thread shall be unblocked, and if there is more than one highest priority thread blocked waiting for the semaphore, then the highest priority thread that has been waiting the longest shall be unblocked. periodt, first come first served among the VIPs. 👑
• If the Process Scheduling option is not defined, the choice of a thread to unblock is unspecified. 🙈 (i.e. don't @ me about which one comes back.)

and if the Process Sporadic Server option is supported, and the scheduling policy is SCHED_SPORADIC, the semantics are as per SCHED_FIFO above. 💜

the glow-up detail: sem_post() shall be async-signal-safe and may be invoked from a signal-catching function. yes bestie, you can call it from a signal handler. iconic behavior fr fr. 🔥

---

🎀 RETURN VALUE 🎀

• If successful, sem_post() shall return zero 😌
• Otherwise, the function shall return -1 and set errno to indicate the error 💀

---

💖 ERRORS 💖

The sem_post() function may fail if:

• EINVAL — the sem argument does not refer to a valid semaphore. not a valid semaphore bestie, we can't work with that. 😭

the following sections are informative, so like, they're bonus content. 🍓

---

🌟 EXAMPLES 🌟

See sem_timedwait(). that's the whole section. go look, she's over there. 💫

---

🌈 APPLICATION USAGE 🌈

None.

---

🧚 RATIONALE 🧚

None.

---

⭐ FUTURE DIRECTIONS ⭐

None.

---

💜 SEE ALSO 💜

• semctl()
• semget()
• semop()
• sem_timedwait()
• sem_trywait()

also, from the Base Definitions volume of POSIX.1‐2017: Section 4.12, Memory Synchronization, and <semaphore.h>. go read those, they're giving essential reading. 📚

---

👑 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 came to you courtesy of IEEE/The Open Group, 2017 — that's the source, that's the date, that's the footer, we are not copying it verbatim because we said what we said. 💅✨ go unlock your semaphores responsibly. mwah. 🎀