---
name: "semctl"
section: "2"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/semctl"
---

# semctl(2)

control operations on a semaphore set

## 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

The **semctl**() system call performs the operation indicated by *cmd* on the semaphore set indicated by *semid*. A fourth argument, a *union semun arg*, is required for certain values of *cmd*. For the commands that use the *arg* argument, *union semun* must be defined as follows:

```
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*.

Commands are performed as follows:

- IPC\_STAT

  Fetch the semaphore set's *struct semid\_ds*, storing it in the memory pointed to by *arg.buf*.

- IPC\_SET

  Changes the *sem\_perm.uid*, *sem\_perm.gid*, and *sem\_perm.mode* members of the semaphore set's *struct semid\_ds* to match those of the struct pointed to by *arg.buf*. The calling process's effective uid must match either *sem\_perm.uid* or *sem\_perm.cuid*, or it must have superuser privileges.

- IPC\_RMID

  Immediately removes the semaphore set from the system. The calling process's effective uid must equal the semaphore set's *sem\_perm.uid* or *sem\_perm.cuid*, or the process must have superuser privileges.

- 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 pointed to by *arg.array*.

- SETALL

  Set the values of all of the semaphores in the set to the values in the array pointed to by *arg.array*. Outstanding adjust on exit values for all semaphores in this set, in any process are cleared.

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.

## ERRORS

The **semctl**() system call will fail if:

- \[EINVAL\]

  No semaphore set corresponds to *semid*.

- \[EINVAL\]

  The *semnum* argument is not in the range of valid semaphores for given semaphore set.

- \[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 mismatch between operation and mode of semaphore set.

- \[ERANGE\]

  SETVAL or SETALL attempted to set a semaphore outside the allowable range \[0 .. SEMVMX\].

## SEE ALSO

[semget(2)](/semget/2.md), [semop(2)](/semop/2.md)

## BUGS

SETALL may update some semaphore elements before returning an error.