semctl(2) semctl(2) NAME semctl - semaphore control operations SYNOPSIS #include <sys/sem.h> int semctl(int semid, int semnum, int cmd, ... /* arg */ ); Remarks The ANSI C ", ... " construct denotes a variable length argument list whose optional [or required] members are given in the associated comment (/* */). DESCRIPTION The semctl() system call provides a variety of semaphore control operations as specified by cmd. For the meaning of unspecified variables, see semaphore identifier in glossary(9). The following values for cmd are executed with respect to the semaphore specified by semid and semnum: GETVAL Return the value of semval. Requires semaphore Read permission. SETVAL Set the value of semval to arg, where arg is the fourth argument of semctl() taken as an int. When this cmd is successfully executed, the semadj value corresponding to the specified semaphore in all processes is cleared. Requires semaphore Alter permission. GETPID Return the value of sempid. Requires semaphore Read permission. GETNCNT Return the value of semncnt. Requires semaphore Read permission. GETZCNT Return the value of semzcnt. Requires semaphore Read permission. The following values for cmd return and set, respectively, every semval in the set of semaphores. GETALL Place semvals into array pointed to by arg, where arg is the fourth argument of semctl() taken as a pointer to unsigned short int. Requires semaphore Read permission. Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 semctl(2) semctl(2) SETALL Set semvals according to the array pointed to by arg, where arg is the fourth argument of semctl() taken as a pointer to unsigned short int. When this cmd is successfully executed, the semadj values corresponding to each specified semaphore in all processes are cleared. Requires semaphore Alter permission. The following values for cmd are also available: IPC_STAT Place the current value of each member of the data structure associated with semid into the structure pointed to by arg, where arg is the fourth argument of semctl() taken as a pointer to struct semid_ds. The contents of this structure are defined in glossary(9). Requires semaphore Read permission. IPC_SET Set the value of the following members of the data structure associated with semid to the corresponding value found in the structure pointed to by arg, where arg is the fourth argument of semctl() taken as a pointer to struct semid_ds: sem_perm.uid sem_perm.gid sem_perm.mode /* only low 9 bits */ This cmd can only be executed by a process that has an effective user ID equal to either that of superuser or to the value of either sem_perm.uid or sem_perm.cuid in the data structure associated with semid. IPC_RMID Remove the semaphore identifier specified by semid from the system and destroy the set of semaphores and data structure associated with it. This cmd can only be executed by a process that has an effective user ID equal to either that of superuser or to the value of either sem_perm.uid or sem_perm.cuid in the data structure associated with semid. RETURN VALUE Upon successful completion, semctl() returns a value based on cmd as follows: GETVAL The value of semval. GETNCNT The value of semncnt. GETZCNT The value of semzcnt. Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 semctl(2) semctl(2) GETPID The value of sempid. All others return 0. If it fails, it returns -1 and sets errno to indicate the error. ERRORS If semctl() fails, it sets errno to one of the following values: [EACCES] Operation permission is denied to the calling process (see semaphore operation permissions in glossary(9). [EFAULT] cmd is SETVAL, GETALL, SETALL, IPC_SET, or IPC_STAT, and arg is an invalid pointer. [EINVAL] semid is not a valid semaphore identifier. [EINVAL] semnum is less than zero or greater than or equal sem_nsems. [EINVAL] cmd is not a valid command, or the command contains invalid parameters. [EPERM] cmd is equal to IPC_RMID or IPC_SET and the process does not have an effective user ID equal to either that of superuser or to the value of either sem_perm.uid or sem_perm.cuid in the data structure associated with semid. [ERANGE] cmd is SETVAL or SETALL and the value to which semval is to be set is greater than the system imposed maximum. EXAMPLES The following call to semctl() initializes the set of 4 semaphores to the values 0, 1, 0, and 1 respectively. This example assumes the process has a valid semid representing a set of 4 semaphores as shown in the semget(2) manual entry. For an example of performing "P" and "V" operations on the semaphores below, refer to semop(2). ushort semarray[4]; semarray[0] = 0; semarray[1] = 1; semarray[2] = 0; semarray[3] = 1; semctl (mysemid, 0, SETALL, semarray); Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 semctl(2) semctl(2) SEE ALSO ipcrm(1), ipcs(1), semget(2), semop(2), stdipc(3C), glossary(9). STANDARDS CONFORMANCE semctl(): SVID2, SVID3, XPG2, XPG3, XPG4 Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996