HP 3000 Manuals HP 3000 Manuals
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 [REV BEG]MPE/iX
SM capability[REV END] 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 [REV BEG]MPE/iX SM
capability[REV END] 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 [REV BEG]MPE/iX SM
capability[REV END] 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.
See Also
semget(), semop(), SVID2 (Section 12)