Controlling semaphores

This section describes how to use the semctl system call. The accompanying program illustrates its use.

Using semctl

The synopsis found on the semctl(2) manual page is as follows:

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

   int semctl (semid, semnum, cmd, arg)
   int semid, cmd;
   int semnum;
   union semun
   {
           int val;
           struct semid_ds *buf;
           ushort *array;
   } arg;

The semctl system call requires four arguments to be passed to it, and it returns an integer value.

The semid argument must be a valid, non-negative, integer value that has already been created by using the semget system call.

The semnum argument is used to select a semaphore by its number. This relates to sequences of operations (atomically performed) on the set. When a set of semaphores is created, the first semaphore is number 0, and the last semaphore is numbered one less than the total in the set.

The cmd argument can be replaced by one of the following values:

GETVAL

return the value of a single semaphore within a semaphore set

SETVAL

set the value of a single semaphore within a semaphore set

GETPID

return the PID of the process that performed the last operation on the semaphore within a semaphore set

GETNCNT

return the number of processes waiting for the value of a particular semaphore to become greater than its current value

GETZCNT

return the number of processes waiting for the value of a particular semaphore to be equal to zero

GETALL

return the value for all semaphores in a semaphore set

SETALL

set all semaphore values in a semaphore set

IPC_STAT

return the status information contained in the associated data structure for the specified semid, and place it in the data structure pointed to by the buf pointer in the user memory area; arg.buf is the union member that contains pointer

IPC_SET

for the specified semaphore set (semid), set the effective user/group identification and operation permissions

IPC_RMID

remove the specified semaphore set (semid) along with its associated data structure.

To perform an IPC_SET or IPC_RMID control command, a process must have:

• an effective user id of OWNER/CREATOR, or

• an effective user id of root (if the system is running with the SUM privilege module), or

• the P_OWNER privilege,

The remaining control commands require either read or write permission, as appropriate.

The arg argument is used to pass the system call the appropriate union member for the control command to be performed. For some of the control commands, the arg argument is not required and is simply ignored.

• arg.val required: SETVAL

• arg.buf required: IPC_STAT, IPC_SET

• arg.array required: GETALL, SETALL

• arg ignored: GETVAL, GETPID, GETNCNT, GETZCNT, IPC_RMID

The details of this system call are discussed in the following program. If you need more information on the logic manipulations in this program, read ``Using semget''. It goes into more detail than would be practical for every system call.