semctl

Provides semaphore control operations.

Syntax

   #include <sys/types.h> 

   #include <sys/ipc.h>

   #include <sys/sem.h>



   int semctl (int semid, int semnum, int cmd,

               semun semarg);

Parameters

semid

Passes a semaphore identifier returned by a call to semget().

semnum

Passes a value indicating a particular semaphore in the semaphore set certain commands specified in cmd will apply to, if applicable.

cmd

Passes a command defining the control operation to perform. Valid commands are defined in the "Description" section below.

semarg

Passes an argument containing information about the semaphore set. Operations using semarg are defined by cmd. Refer to the "Description" section below. The argument passed must be of type union semun, having the following structure:

   union semun {

                  int val;

                  struct semid_ds *buf;

                  ushort *array;

               }semarg;

Return Values

>=0: Success. The value returned depends on the command passed in cmd. Refer to the list below of possible return values and their meanings.
-1: An error occurred, and errno is set to indicate the error condition.

Upon successful completion, the semctl() function returns one of the following values depending on the command passed in cmd:

Command: Return Value
GETVAL: The semaphore value of the semaphore specified by semid and semnum.
GETNCNT: The number of processes waiting for the semaphore value of the semaphore specified by semid and semnum to become greater than 0.
GETZCNT: The number of processes waiting for the semaphore value of the semaphore specified by semid and semnum to become 0.
GETPID: The PID of the process that last modified the semaphore specified by semid and semnum.
All others: 0

Description

The semctl() function provides semaphore control operations on the semaphore set and data structure associated with the semaphore identifier passed in semid. Control operations are defined by cmd. Following are valid commands to be passed in cmd and the resulting operations:

Command

Operation

IPC_RMID

Deallocate the semaphore identifier specified by semid and purge the semaphore set and data structure associated with it. The calling process must have either MPE/iX SM capability or an effective user ID equal to the value of either the sem_perm.uid or sem_perm.cuid fields in the data structure associated with semid.

IPC_SET

Copy data from the following fields of the semid_ds structure (defined in the <sys/sem.h> header) pointed to by semarg.buf to the corresponding fields in the data structure associated with semid:

sem_perm.uid (owner user ID)
sem_perm.gid (owner group ID)
Low order 9 bits of sem_perm.mode

The calling process must have either MPE/iX SM capability or an effective user ID equal to the value of either the sem_perm.uid or sem_perm.cuid fields in the data structure associated with semid.

IPC_STAT

Copy all data from the data structure associated with semid to the data structure pointed to by semarg.buf. The structure semid_ds is defined in the <sys/sem.h> header. The calling process must have read permission.

GETVAL

Return the semaphore value of the semaphore specified by semid and semnum. The calling process must have read permission.

SETVAL

Set the semaphore value of the semaphore specified by semid and semnum to semarg.val (must be>=0). This command clears in all processes the semaphore adjust value corresponding to the specified semaphore. The calling process must have write permission.

GETPID

Return the PID of the process that last modified the semaphore specified by semid and semnum. The calling process must have read permission.

GETNCNT

Return the number of processes waiting for the semaphore value of the semaphore specified by semid and semnum to become greater than zero. The calling process must have read permission.

GETZCNT

Return the number of processes waiting for the semaphore value of the semaphore specified by semid and semnum to become 0. The calling process must have read permission.

GETALL

Copy the semaphore values of all semaphores associated with semid to the array pointed to by semarg.array. The calling process must have read permission.

SETALL

Set the semaphore values of all semaphores to the values specified in the array pointed to by arg.array (must be >=0). This command clears in all processes the semaphore adjust value corresponding to the specified semaphore. The calling process must have write permission.

Implementation Considerations

None.

Errors

If an error occurs, errno is set to one of the following values.

`EACCES`	CAUSE	The calling process does not have permission.
	ACTION	Ensure that the process has the required permissions to perform the specified `cmd`.
`EFAULT`	CAUSE	The system detected a NULL or bad address in attempting to use either the `semarg.buf` or `semarg.array` arguments.
	ACTION	Check the `semarg` parameter and make sure it is properly defined.
`EINVAL`	CAUSE	`semid` is not a valid semaphore identifier, or `cmd` is not a valid command, or `semnum` is less than zero or greater than or equal to the value stored in the `sem_nsems` field in the data structure associated with `semid`, or the values of `SETVAL` or `SETALL` are out of range.
	ACTION	Check the parameters to make sure a valid `semid` was specified and the semaphore set was not removed from the system, a valid `cmd` was specified, `semnum` references a semaphore that exists in this semaphore set, or `SETVAL` and `SETALL` values are in range.
`EPERM`	CAUSE	`cmd` specifies `IPC_RMID` or `IPC_SET` and the calling process does not have either MPE/iX SM capability or an effective user ID equal to the value of either the `sem_perm.uid` or `sem_perm.cuid` fields in the data structure associated with `semid`.
	ACTION	Ensure that the calling process has the appropriate effective user ID or the appropriate capabilities to perform the specified `cmd`.
`ERANGE`	CAUSE	`cmd` specifies either `SETVAL` or `SETALL` and the resulting semaphore value would be greater than the system-defined limit.
	ACTION	Ensure that the semaphore value(s) specified are within the system-defined range.
`ESYSERR`	CAUSE	An operating system error occurred that does not map directly to any of the above errors.
	ACTION	Examine the MPE/iX process error stack for the type of system error.

semctl

Technical documentation

» Table of Contents

» Index