semctl(2) [freebsd man page]
SEMCTL(2) BSD System Calls Manual SEMCTL(2) 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 is 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 */ }; 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 */ struct sem *sem_base; /* pointer to first semaphore in set */ 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), semop(2) BUGS
SETALL may update some semaphore elements before returning an error. BSD
September 12, 1995 BSD
Check Out this Related Man Page
semctl(2) System Calls Manual semctl(2) NAME
semctl - Performs semaphore control operations SYNOPSIS
#include <sys/sem.h> int semctl( int semid, int semnum, int cmd, ...); Application developers may want to specify #include statements for <sys/types.h> and <sys/ipc.h> before the one for <sys/sem.h> if programs are being developed for multiple platforms. The additional #include statements are not required on Tru64 UNIX systems or by ISO or X/Open standards, but may be required on other vendors' systems that conform to these standards. STANDARDS
Interfaces documented on this reference page conform to industry standards as follows: semctl(): XSH4.2 Refer to the standards(5) reference page for more information about industry standards and associated tags. PARAMETERS
Specifies the ID of the semaphore set. Specifies the number of the semaphore to be processed. Specifies the type of command. See the DESCRIPTION section for a list of available commands. The fourth argument is optional and depends on the operation requested. If required, it is of the type union semun, which the application program must explicitly declare as follows: union semun { int val; struct semid_ds *buf; u_short *array; } arg ); The members of this structure are described as follows: Contains the semaphore value to which semval is set when the SETVAL command is performed. Points to a structure of type semid_ds. (For information about this structure, semid_ds(4).) When you specify the IPC_STAT command, semctl() copies the contents of the semid_ds struc- ture identified by semid into arg.buf. When you specify the IPC_SET command, semctl() copies the contents of the arg.buf parameter into the semid_ds structure identified by the semid parameter. Points to an array of semval values. These semval values are returned by the GETALL command and set by the SETALL command. DESCRIPTION
The semctl() function allows a process to perform various operations on an individual semaphore within a semaphore set, on all semaphores within a semaphore set, and on the semid_ds structure associated with the semaphore set. It also allows a process to remove the semaphore set's ID and its associated semid_ds structure. The cmd value determines which operation is performed. The following commands operate on the specified semaphore (that is, the one speci- fied by the semnum parameter) within the semaphore set identified by semid: Returns the value of semval. This command requires read permission. Sets the value of semval to arg.val. When this command successfully executes, the kernel clears the semaphore's adjust-on-exit value in all processes. This command requires modify permission. Returns the value of sempid. This command requires read permission. Returns the value of semncnt. This command requires read permission. Returns the value of semzcnt. This command requires read permission. The following commands operate on all the semaphores in the semaphore set: Returns all the semval values and places them in the array pointed to by arg.array. This command requires read permission. Sets all the semval values according to the array pointed to by arg.array. When this command successfully executes, the kernel clears the semaphore's adjust-on-exit value in all processes. This command requires modify permission. You can also use the following IPC commands: Queries the semaphore ID by copying the contents of its associated semid_ds structure into the structure pointed to by arg.buf. This com- mand requires read permission. Sets the semaphore set by copying the values in the arg.buf structure into corresponding fields in the semid_ds structure associated with the semaphore ID. This operation is restricted. The effective user ID of the calling process must have superuser privilege or must be equal to the value of sem_perm.cuid or sem_perm.uid in the structure associated with the semaphore ID. The fields are set as follows: The sem_perm.uid field is set to the owner's user ID. The sem_perm.gid field is set to the owner's group ID. The sem_perm.mode field is set to the access modes for the semaphore set. Only the low-order nine bits are set. Removes the semaphore ID and destroys the set of semaphores and the semid_ds data structure associated with it. This operation is restricted. The effective user ID of the calling process must have superuser privilege or equal to the value of sem_perm.cuid or sem_perm.uid in the associated semid_ds structure. RETURN VALUES
Upon successful completion, the value returned depends on the cmd parameter as follows: Returns the value of semval. Returns the value of sempid. Returns the value of semncnt. Returns the value of semzcnt. All other commands return a value of 0 (zero). If the semctl() function fails, it returns a value of -1 and sets errno to indicate the error. ERRORS
The semctl() function sets errno to the specified values for the following conditions: The calling process does not have the required per- mission. [Tru64 UNIX] The cmd parameter is IPC_STAT or IPC_SET and an error occurred in accessing the arg structure. The semid parameter is not a valid semaphore ID; the value of semnum is less than 0 (zero) or greater than sem_nsems; or cmd is not a valid command. [Tru64 UNIX] The system does not have enough memory to complete the function. Either the cmd parameter is equal to IPC_RMID and the effective user ID of the calling process does not have appropriate privilege, or the cmd parameter is equal to IPC_SET and the effective user ID of the calling process is not equal to the value of sem_perm.cuid or sem_perm.uid in the semid_ds structure associated with the semaphore ID. The cmd parameter is SETVAL or SETALL and the value to which semval is to be set is greater than the system-defined maximum. RELATED INFORMATION
Functions: semget(2), semop(2) Data structures: semid_ds(4) Standards: standards(5) delim off semctl(2)