COHERENT manpages
This page displays the COHERENT manpage for semctl() [Control semaphore operations].
List of available manpages
Index
semctl() -- General Function (libc) Control semaphore operations #include <sys/types.h> #include <sys/ipc.h> #include <sys/sem.h> int semctl(id, number, command, arg) int id, command, number; union semun { int value; struct semid_ds *buffer; unsigned short array[]; } arg; The function semctl() controls the COHERENT system's semaphore facility. A set of semaphores consists of a copy of structure semid_ds, which is defined in header file <sys/sem.h>. This structure points to the set of semaphores, notes how many semaphores are in the set, and gives information on who can manipulate it, and how. The semaphores themselves consist of an array of structures of type sem, which is also defined in sem.h. When the function semget() creates a set of semaphores, it assigns to that set an identification number and returns that number to the calling process. For details on this process, see the Lexicon entry for semget() id identifies the set of semaphores to be manipulated. This value must have been returned by a call to semget(). number gives the offset within the set identified by id of the semaphore that interests you. arg gives information to be passed to, or received from, the semaphore in question. command names the operation that you want semctl() to perform. The following commands manipulate semaphore number within the set identified by id: GETVAL Return the value of semval, which is the field in structure sem that gives the address of the semaphore's text map. SETVAL Set semval to arg.value. If an ``adjust value'' had been created for this semaphore (by changing or setting a semaphore through semop() with the flag SEM_UNDO set), it is erased. GETPID Return the value of sempid, which is the field in sem that identifies the last process to have manipulated this semaphore. GETNCNT Return the value of semncnt, which gives the number of processes that await an increase in field sem.semval. GETZCNT Return the value of semzcnt, which gives the number of processes that are waiting for the value of sem.semval to become zero. The following commands return or set field semval within every semaphore in the set identified by id: GETALL Write every semval into arg.array. SETALL Initialize every semval to the corresponding value within arg.array. All ``adjust values'' for this semaphores are erased. semctl() also recognizes the following commands: IPC_STAT Copy the value of each semaphore in the set identified by id into the structure pointed to by arg.buffer. IPC_SET Copy fields sem_perm.uid, sem_perm.gid, and sem_perm.mode (low nine bits only) from the ipc_perm associated with id into that pointed to arg.buffer. Only the superuser root or the user whose effective user ID matches the value of field uid in the data structure identified by id can invoke this command. IPC_RMID Destroy the semid_ds structure identified by id, plus its array of semaphores. Only the superuser root or the user whose effective user ID matches the value of field uid can invoke this command. semctl() fails if one or more of the following is true: -> id is not a valid semaphore identifier. semctl() sets the global variable errno to EINVAL. -> number is less than zero or greater than field sem_nsems in structure semid_ds, which gives the number of semaphores in the set identified by id (EINVAL). -> command is not a valid command (EINVAL). -> The calling process is denied operation permission (EACCES). -> command is SETVAL or SETALL, but the value of semval exceeds the system- imposed maximum (ERANGE). -> command is IPC_RMID or IPC_SET, but the calling process is owned neither by root nor by the user who created the set of semaphores being manipulated (EPERM). -> arg.buffer points to an illegal address (EFAULT). semctl() returns the following values upon successful completion of their following commands: Command Return Value GETVAL Value of semval GETPID Value of sempid GETNCNT Value of semncnt GETZCNT Value of semzcnt For all other commands, semctl() returns zero to indicate successful completion. If it could not execute a command successfully, semctl() returns -1 and sets errno to an appropriate value. Files /usr/include/sys/ipc.h /usr/include/sys/sem.h See Also libc, semget(), semop() Notes For information on other methods of interprocess communication, see the Lexicon entries for msgctl() and shmctl().