August 25, 1999 SEMCTL 2

### NAME

semctl - semaphore control operations

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

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

### DESCRIPTION

The semctl(``) system call provides a number of control operations on the semaphore specified by ```semnum` and ```semid`. The operation to be performed is specified in ```cmd` (see below). The fourth argument is optional and depends upon the operation requested. If required, it is a union of the following fields: `

        int     val;            /* value for SETVAL */
        struct  semid_ds *buf;  /* buffer for IPC_{STAT,SET} */
        u_short *array;         /* array for GETALL & SETALL */

`

The semid_ds structure used in the ```IPC_SET` and ```IPC_STAT` commands is defined in <```sys/sem.h`> and contains the following members: ``

        struct ipc_perm sem_perm; /* operation permissions */
        unsigned short sem_nsems; /* number of sems in set */
        time_t sem_otime;         /* last operation time */
        time_t sem_ctime;         /* last change time */

The ipc_perm structure used inside the semid_ds structure is defined in <```sys/ipc.h`> and contains the following members: ``

        uid_t cuid;  /* creator user id */
        gid_t cgid;  /* creator group id */
        uid_t uid;   /* user id */
        gid_t gid;   /* group id */
        mode_t mode; /* permission (lower 9 bits) */

semctl(``) provides the following operations:

```GETVAL`
  Return the value of the semaphore.

```SETVAL`
  Set the value of the semaphore to ```arg.val`, where ```arg` is the fourth argument to semctl(``).

```GETPID`
  Return the pid of the last process that did an operation on this semaphore.

```GETNCNT`
  Return the number of processes waiting to acquire the semaphore.

```GETZCNT`
  Return the number of processes waiting for the value of the semaphore to reach 0.

```GETALL`
  Return the values of all the semaphores associated with ```semid`.

```SETALL`
  Set the values of all the semaphores that are associated with the semaphore identifier ```semid` to the corresponding values in ```arg.array`, where ```arg` is the fourth argument to semctl(``).

```IPC_STAT`
  Gather information about a semaphore and place the information in the structure pointed to by ```arg.buf`, where ```arg` is the fourth argument to semctl(``).

```IPC_SET`
  Set the value of the sem_perm.uid, sem_perm.gid and sem_perm.mode fields in the structure associated with the semaphore. The values are taken from the corresponding fields in the structure pointed to by ```arg.buf`, there ```arg` is the fourth argument to semctl(``). This operation can only be executed by the super-user, or a process that has an effective user id equal to either sem_perm.cuid or sem_perm.uid in the data structure associated with the semaphore.

```IPC_RMID`
  Remove the semaphores associated with ```semid` from the system and destroy the data structures associated with it. Only the super-user or a process with an effective uid equal to the sem_perm.cuid or sem_perm.uid values in the data structure associated with the semaphore can do this.

The permission to read or change a semaphore (see semop(2)) is determined by the sem_perm.mode field in the same way as is done with files (see chmod(2)), but the effective uid can match either the sem_perm.cuid field or the sem_perm.uid field, and the effective gid can match either sem_perm.cgid or sem_perm.gid.

### RETURN VALUES

For the ```GETVAL`, ```GETPID`, ```GETNCNT`, and ```GETZCNT` operations, semctl(``) returns one of the values described above if successful. All other operations will make semctl(``) return 0 if no errors occur. Otherwise -1 is returned and errno set to reflect the error.

### ERRORS

semctl(``) will fail if:

[```EPERM`]
  ```cmd` is equal to ```IPC_SET` or ```IPC_RMID` and the caller is not the super-user, nor does the effective uid match either the sem_perm.uid or sem_perm.cuid fields of the data structure associated with the semaphore.

[```EACCES`]
  The caller has no operation permission for this semaphore.

[```EINVAL`]
  ```semid` is not a valid message semaphore identifier.

  cmd is not a valid command.

[```EFAULT`]
  ```arg.buf` or ```arg.array` specifies an invalid address.

[```ERANGE`]
  ```cmd` is equal to ```SETVAL` or ```SETALL` and the value to be set is greater than the system semaphore maximum value.

### SEE ALSO

semget(2), semop(2)

### STANDARDS

The semctl system call conforms to X/Open System Interfaces and Headers Issue 5 (``XSH5'') .

### HISTORY

Semaphores appeared in the first release of `AT&T` System V `UNIX`.