SEMCTL(2)

💅 SEMCTL(2) — the manual page, but make it bestie

ok so this is a system call page from the System Calls Manual, and it's about semctl — the girl who runs the whole semaphore set. sit down, hydrate, we're doing IPC today 🫶

✨ NAME ✨

semctl — control operations on a semaphore set

📚 LIBRARY 📚

Standard C Library (libc, -lc)

🎀 SYNOPSIS 🎀

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>

int
semctl(int semid, int semnum, int cmd, ...);

🌸 DESCRIPTION 🌸

so basically semctl() does the thing that cmd tells it to do, on the semaphore set that semid points at. easy. a fourth argument, a union semun arg, is required for certain values of cmd — like, you literally cannot skip it for those, bestie, it's not optional-optional.

for the commands that use the arg argument, union semun has to be defined like this:

union semun {
        int     val;            /* value for SETVAL */
        struct  semid_ds *buf;  /* buffer for IPC_STAT & IPC_SET */
        u_short *array;         /* array for GETALL & SETALL */
};

non-portable software may define _WANT_SEMUN before including sys/sem.h to use the system definition of union semun. iykyk 💅

commands are performed as follows:

• IPC_STAT — fetch the semaphore set's struct semid_ds and store it in the memory that arg.buf points to. it's giving "let me see your receipts" 📋
• IPC_SET — changes the sem_perm.uid, sem_perm.gid, and sem_perm.mode members of the semaphore set's struct semid_ds so they match the ones in the struct that arg.buf points to. the calling process's effective uid has to match either sem_perm.uid or sem_perm.cuid, or it has to have superuser privileges. no permission, no edit, periodt.
• IPC_RMID — immediately removes the semaphore set from the system. the calling process's effective uid has to equal the semaphore set's sem_perm.uid or sem_perm.cuid, or the process must have superuser privileges. gone. deleted. she left the chat 💀
• GETVAL — return the value of semaphore number semnum.
• SETVAL — set the value of semaphore number semnum to arg.val. outstanding adjust on exit values for this semaphore in any process are cleared.
• GETPID — return the pid of the last process to perform an operation on semaphore number semnum.
• GETNCNT — return the number of processes waiting for semaphore number semnum's value to become greater than its current value.
• GETZCNT — return the number of processes waiting for semaphore number semnum's value to become 0.
• GETALL — fetch the value of all of the semaphores in the set into the array that arg.array points to.
• SETALL — set the values of all of the semaphores in the set to the values in the array that arg.array points to. outstanding adjust on exit values for all semaphores in this set, in any process, are cleared.

and the struct semid_ds is defined as follows:

struct semid_ds {
        struct  ipc_perm sem_perm;      /* operation permission struct */
        u_short sem_nsems;      /* number of sems in set */
        time_t  sem_otime;      /* last operation time */
        time_t  sem_ctime;      /* last change time */
                                /* Times measured in secs since */
                                /* 00:00:00 GMT, Jan. 1, 1970 */
};

🌈 RETURN VALUES 🌈

on success, when cmd is one of GETVAL, GETPID, GETNCNT or GETZCNT, semctl() returns the corresponding value 🎉 — otherwise, 0 is returned. on failure, -1 is returned, and errno is set to indicate the error. (rude of it, honestly.)

👑 ERRORS 👑

the semctl() system call will fail if:

• [EINVAL] — no semaphore set corresponds to semid. girl does not exist. 🫥
• [EINVAL] — the semnum argument is not in the range of valid semaphores for the given semaphore set. wrong number bestie 😭
• [EPERM] — the calling process's effective uid does not match the uid of the semaphore set's owner or creator.
• [EACCES] — permission denied due to a mismatch between the operation and the mode of the semaphore set.
• [ERANGE] — SETVAL or SETALL attempted to set a semaphore outside the allowable range [0 .. SEMVMX]. stay in your lane please 🚧

🔥 SEE ALSO 🔥

• semget(2)
• semop(2)

💀 BUGS 💀

SETALL may update some semaphore elements before returning an error. so like… it can half-do the thing and then bail. not iconic of it, but there it is 🙈

and that's the whole page, bestie — brought to you by Debian, dated July 9, 2020. go forth and manage your semaphores responsibly, mwah 💖✨🎀