semctl()--Perform Semaphore Control Operations

 #include <sys/sem.h>

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

The semctl() function allows the caller to control the semaphore set specified by the semid parameter.

A semaphore set is controlled by setting the cmd parameter to one of the following values:

IPC_RMID (0x00000000)

Remove the semaphore set identifier semid from the system and destroy the set of semaphores. Any threads that are waiting in semop() are woken up and semop() returns with a return value of -1 and errno set to EIDRM.

The IPC_RMID command can be run only by a thread with appropriate privileges or one that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the semaphore set.

IPC_SET (0x00000001)

Set the user ID of the owner, the group ID of the owner, and the permissions for the semaphore set to the values in the sem_perm.uid, sem_perm.gid, and sem_perm.mode members of the semid_ds data structure pointed to by the fourth parameter.

The IPC_SET command can be run only by a thread with appropriate privileges or one that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the semaphore set.

IPC_STAT (0x00000002)

Store the current value of each member of the semid_ds data structure into the structure pointed to by the fourth parameter. The IPC_STAT command requires read permission to the semaphore set.

GETNCNT (0x00000003)

Return the number of threads waiting for the value of semaphore semnum to increase. This value is the semncnt value in the semaphore_t data structure associated with the specified semaphore. The GETNCNT command requires read permission to the semaphore set.

GETPID (0x00000004)

Return the process ID of the last thread to operate on semaphore semnum. This value is the sempid value in the semaphore_t data structure associated with the specified semaphore. The GETPID command requires read permission to the semaphore set.

GETVAL (0x00000005)

Return the current value of semaphore semnum. This value is the semval value in the semaphore_t data structure associated with the specified semaphore. The GETVAL command requires read permission to the semaphore set.

GETALL (0x00000006)

Return the values of each semaphore in the semaphore set into the array pointed to by the fourth parameter, which is a pointer to an array of type unsigned short. The values are the semval value in the semaphore_t data structure associated with each semaphore in the semaphore set. The GETALL command requires read permission to the semaphore set.

GETZCNT (0x00000007)

Return the number of threads waiting for the value of semaphore semnum to reach zero. This value is the semzcnt value in the semaphore_t data structure associated with the specified semaphore. The GETZCNT command requires read permission to the semaphore set.

SETVAL (0x00000008)

Set the value of semaphore semnum to the integer value of type int specified in the fourth parameter and clear the associated per-thread semaphore adjustment value. The SETVAL command requires write permission to the semaphore set.

SETALL (0x00000009)

Set the values of each semaphore in the semaphore set to the values contained in the array pointed to by the fourth parameter, which is a pointer to an array of type unsigned short. In addition, the associated per-thread semaphore-adjustment value is cleared for each semaphore. The SETALL command requires write permission to the semaphore set.

Parameters

semid

(Input) Semaphore set identifier, a positive integer. It is returned by the semget() function and used to identify the semaphore set on which to perform the control operation.

semnum

(Input) Semaphore number, a non-negative integer. It identifies a semaphore within the semaphore set on which to perform the control operation.

cmd

(Input) Command, the control operation to perform on the semaphore set. Valid values are listed above.

...

(Input/output) An optional fourth parameter whose type depends on the value of cmd. For the cmd SETVAL, this parameter must be an integer of type int. For the cmd IPC_STAT or IPC_SET, this parameter must be a pointer to a semid_ds structure. For the cmd GETALL or SETALL, this parameter must be a pointer to an array of type unsigned short. For all other values of cmd, this parameter is not required.

The members of the semid_ds structure are as follows:

Authorities

Authorization Required for semctl()

Note: To set semaphore set information or to remove a semaphore set, the thread must be the owner or creator of the semaphore set, or have appropriate privileges.

Return Value

Error Conditions

If semctl() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

[EACCES]

Permission denied.

An attempt was made to access an object in a way forbidden by its object access permissions.

The thread does not have access to the specified file, directory, component, or path.

The cmd parameter is IPC_STAT, GETVAL, GETPID, GETNCNT, GETZCNT, or GETALL and the calling thread does not have read permission to the semaphore set.

The cmd parameter is SETVAL, or SETALL and the calling thread does not have write permission to the semaphore set.

[EDAMAGE]

A damaged object was encountered.

A referenced object is damaged. The object cannot be used.

The semaphore set has been damaged by a previous semaphore operation.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL.

One of the following has occurred:

• The semid parameter is not a valid semaphore identifier.
• The semnum parameter is less than zero or greater than or equal to sem_nsems.
• The cmd parameter is not a valid command.

[EPERM]

Operation not permitted.

You must have appropriate privileges or be the owner of the object or other resource to do the requested operation.

The cmd parameter is IPC_RMID or IPC_SET and both of the following are true:

• the calling thread does not have appropriate privileges.
• the effective user ID of the calling thread is not equal to the user ID of the owner or the user ID of the creator of the semaphore set.

[ERANGE]

A range error occurred.

The value of an argument is too small, or a result too large.

The cmd parameter is SETVAL, and the value to which semval is to be set is greater than the system-imposed maximum.

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

Error Messages

None.

Usage Notes

1. "Appropriate privileges" is defined to be *ALLOBJ special authority. If the user profile under which the thread is running does not have *ALLOBJ special authority, the thread does not have appropriate privileges.

2. Take care when using a union for the optional fourth parameter. If the optional fourth parameter is an integer, semctl() expects it to directly follow the third parameter in storage. But a union that contains a pointer is aligned on a 16-byte boundary, which might not directly follow the third parameter. Therefore, the value used by semctl() for the fourth parameter might not be the value intended by the caller, and unexpected results could occur.

Related Information

• The <sys/sem.h> file (see Header Files for UNIX^®-Type Functions)
  
  
• semget()--Get Semaphore Set with Key
  
  
• semop()--Perform Semaphore Operations on Semaphore Set

Example

For an example of using this function, see Example: Using semaphore set and shared memory functions.

[ Back to top | UNIX-Type APIs | APIs by category ]