semctl() -- perform semaphore control operations

SYNOPSIS

#include <sys/sem.h>

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

The semctl() function provides a variety of semaphore control operations as specified by cmd. semctl() executes the following commands with respect to the semaphore that semid and semnum specify:

GETVAL: Returns the value of semval. Requires read permission.
SETVAL: Sets the value of semval to arg.val. When this command executes successfully, it clears the semadj value corresponding to the specified semaphore in all processes. Requires alter permission
GETPID: Returns the value of sempid. Required read permission.
GETNCNT: Returns the value of semncnt. Requires read permission.
GETZCNT: Returns the value of semzcnt. Requires read permission.

The following commands operate on each semval in the set of semaphores:

GETALL: Places the semval values into an array that arg.array points to. Requires read permission.
SETALL: Sets the semval values from the array that arg.array points to. When this command executes successfully, it clears the semadj values that correspond to each specified semaphore in all processes. Requires alter permission.

The following commands also are available:

IPC_STAT

Copies the current attributes of the semaphore associated with semid into the structure that arg.buf points to. Requires read permission.

IPC_SET

Sets the attributes of the associated with semid from the values found in the structure that arg.buf points to:

sem_perm.uid
sem_perm.gid
sem_perm.mode   /* only access permission bits */

This command can be executed only by a process that has an effective user ID equal to either that of a super user, sem_perm.cuid, or sem_perm.uid.

IPC_RMID

Removes the semaphore identifier that semid specifies from the system and destroys the set of semaphores. This command can be executed only by a process that has an effective user ID equal to that of super user, sem_perm.cuid, or sem_perm.uid.

PARAMETERS

semid

Is the semaphore identifier.

semnum

Is a semaphore number greater than zero and less than sem_nsems.

cmd

Specifies a variety of semaphore control operations.

The following commands are executed with respect to the semaphore specified by semid and semnum: GETVAL, SETVAL, GETPID, GETNCNT, and GETZCNT.

The following commands return and set, respectively, every semval in the set of semaphores: GETALL and SETALL.

The following commands are also available: IPC_STAT, IPC_SET, and IPC_RMID.

arg

Is an optional argument, and depends upon the operation cmd requested. If used, it is of type union semun, which the application program must explicitly declare:

union semun {
	int val;
	struct semid_ds *buf;
	unsigned short *array;
} arg;

RETURN VALUES

If successful, semctl() returns a value based upon cmd. On failure, semctl() returns a value of -1 and sets errno to one of the following:

EACCES

Permission is denied to the calling process.

EFAULT

arg.buf points to an illegal address.

EINVAL

cmd is IPC_SET and sem_perm.uid or sem_perm.gid is not valid.

cmd is not a valid command.

semid is not a valid semaphore identifier.

semnum is less than zero or greater than sem_nsems.

EPERM

cmd is equal to IPC_RMID or IPC_SET and the effective user ID of the calling process is not equal to that of super user, sem_perm.cuid,or sem_perm.uid in the data structure associated with semid.

ERANGE

cmd is SETVAL or SETALL and the value to which semval is to be set is greater than the system-imposed maximum.

CONFORMANCE

UNIX 98.

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

NuTCRACKER Platform semaphores are not implemented in terms of Win32 semaphores; therefore, they cannot be shared with Win32 applications.

The effective user ID of the super-user account has a value of zero in the NuTCRACKER Platform environment. See Users and Groups under Security in the API-Specific Porting Issues chapter of the PTC MKS Toolkit UNIX to Windows Porting Guide for more information.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

semctl()
perform semaphore control operations

Function