semctl()-Perform Semaphore Control Operations

#include <sys/sem.h>

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

The semctl() function provides semaphore control operations as specified by cmd on the semaphore specified by semnum in the semaphore set specified by semid.

Parameters

semid

(Input) Semaphore set identifier, a positive integer. It is created 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. See below for details.

...

(Input/output) An optional fourth parameter whose type depends on the value of cmd. For a cmd value of SETVAL, this parameter must be an integer. For a cmd value of IPC_STAT or IPC_SET, this parameter must be a pointer to a semid_ds structure. For a cmd value of 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.

Note: Before Version 3 Release 6 of OS/400, the Common Programming APIs (CPA) Toolkit/400 support for semctl() required the use of the semun structure for this fourth parameter. With support for semaphores in OS/400, use of semun is not required and is not recommended when passing an integer value. If the optional fourth parameter is an integer, IPC expects it to directly follow the third parameter in storage. However, if the semun structure is used to pass the integer value, the value is aligned on a 16-byte boundary, which might not directly follow the third parameter. Therefore, the value used by IPC for the fourth parameter might not be the value intended by the caller, and unexpected results could occur.

The cmd parameter can have one of the following values:

GETVAL

Return the semval value in the semaphore_t data structure associated with the specified semaphore. This command requires read permission.

SETVAL

Set the semval value in the semaphore_t data structure associated with the specified semaphore to the integer value found in the fourth parameter and clear the associated per-thread semaphore adjustment value. This command requires write permission.

GETPID

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

GETNCNT

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

GETZCNT

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

GETALL

Return the semval value in the semaphore_t data structure associated with each semaphore in the specified semaphore set. The semval values will be returned in the array pointed to by the fourth parameter, which will be a pointer to an array of type unsigned short. This command requires read permission.

SETALL

Set the semval value in the semaphore_t data structure associated with each semaphore in the specified semaphore set and clear all associated per-thread semaphore-adjustment values. The semval values are 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. This command requires write permission.

IPC_STAT

Place the current value of each member of the semid_ds data structure associated with semid into the structure pointed to by the fourth parameter, which is a pointer to a semid_ds structure. This command requires read permission.

IPC_SET

Set the value of the following members of the semid_ds data structure associated with semid to the corresponding value found in the structure pointed to by the fourth parameter, which is a pointer to a semid_ds structure:

• sem_perm.uid

• sem_perm.gid

• sem_perm.mode

IPC_SET can be performed only by a thread with appropriate privileges or one that has an effective user ID equal to the value of sem_perm.cuid or sem_perm.uid in the semid_ds data structure associated with semid.

IPC_RMID

Remove the semaphore identifier specified by semid from the system and destroy the set of semaphores and semid_ds data structure associated with it. IPC_RMID can be performed only by a thread with appropriate privileges or one that has an effective user ID equal to the value of sem_perm.cuid or sem_perm.uid in the semid_ds data structure associated with semid.

Authorities

Figure 1-11. Authorization Required for semctl()

Object Referred to	Authority Required	errno
Semaphore, get the value of (cmd = GETVAL)	Read	EACCES
Semaphore, set the value of (cmd = SETVAL)	Write	EACCES
Semaphore, get last process to operate on (cmd = GETPID)	Read	EACCES
Semaphore, get number of threads waiting for value to increase (cmd = GETNCNT)	Read	EACCES
Semaphore, get number of threads waiting for value to reach zero (cmd = GETZCNT)	Read	EACCES
Semaphore set, get value of each semaphore (cmd = GETALL)	Read	EACCES
Semaphore set, set value of each semaphore (cmd = SETALL)	Write	EACCES
Semaphore set, retrieve state information (cmd = IPC_STAT)	Read	EACCES
Semaphore set, set state information (cmd = IPC_SET)	See Note	EPERM
Semaphore set, remove (cmd = IPC_RMID)	See Note	EPERM
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

value

semctl() was successful. Depending on the control operation specified in cmd, semctl() returns the following values:

GETVAL

The value of the specified semaphore.

GETPID

The process ID of the last thread that performed a semaphore operation on the specified semaphore.

GETNCNT

The number of threads waiting for the value of the specified semaphore to increase.

GETZCNT

The number of threads waiting for the value of the specified semaphore to reach zero.

For all other values of cmd:

The value is 0.

-1

semctl() was not successful. The errno variable is set to indicate the error.

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.

If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems.

Operation permission is denied to the calling thread.

[EDAMAGE]

A damaged object was encountered.

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

The value of semid corresponds to a semaphore set that has been marked as 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.

[ERROR_INVALID_PARAMETER]

An invalid parameter was found.

A parameter passed to this function is not valid.

One of the following has occurred:

• The value of semid is not a valid semaphore identifier.

• The value of semnum is less than zero or greater than or equal to sem_nsems.

• The value of cmd 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 parameter cmd is equal to 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 value of sem_perm.cuid or sem_perm.uid in the data structure associated with semid.

[ERANGE]

A range error occurred.

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

The parameter cmd is equal to 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.

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 Using Semaphores and Shared Memory in Appendix A, Examples.