semctl

semctl

Control a Semaphore Set

Portability: UNIX compatible

SYNOPSIS
DESCRIPTION
RETURN VALUE
USAGE NOTES
RELATED FUNCTIONS

SYNOPSIS

#include <sys/sem.h>
int semctl(int id, 
           int num, 
           int cmd, argument);

DESCRIPTION

The semctl function is used to perform one of several control operations on an UNIX System Services semaphore set.

Note: See the semget function description in section semget for general information about semaphore sets. [cautionend]

The id argument to semctl specifies a semaphore set id. This argument is an id, such as the id returned by semget , not a semaphore set key, which might be passed as an argument to semget .

The num argument to semctl specifies the index of the specific semaphore to which the control operation applies. Some operations apply to the entire set. For these operations, this argument is ignored.

The cmd argument specifies the operation which is to be performed. The value and type of the fourth argument ( argument ) to semctl , if any, is dependent on the cmd specification. cmd should be specified as one of the following symbolic values:

IPC_RMID - Removes the semaphore set and its id from the system. argument is not used by this operation, and need not be specified.
IPC_SET - Can be used to change the ownership of the semaphore set or the access rules. argument should be a pointer to a struct semid_ds , as described below. The contents of
argument->sem_perm.uid , argument->sem_perm.gid and argument->sem_perm.mode will be copied to the system's semaphore set id data structure.
IPC_STAT - Returns the contents of the semaphore set id data structure (see below). All elements of the data structure are stored in the object addressed by argument , which should be a pointer to a struct semid_ds .
GETVAL - Returns the value in the semaphore specified by the num argument. argument is not used, and may be omitted.
SETVAL - Stores a specified value in the semaphore selected by the num argument. argument specifies the value to be stored, which should be of type int .
Note: Successful use of the SETVAL operation clears any semaphore adjustment information for this semaphore in any process. (See the semop function description in section semop for information on semaphore adjustment.)
GETALL - Stores the value of each semaphore in the set. argument should be a pointer to an array of unsigned shorts in which the values will be stored. The required array size can be determined by using the IPC_STAT command to get the number of semaphores in the set.
SETALL - Stores values in all semaphores of the set. argument should be a pointer to an array of unsigned shorts containing the values to be stored. The required array size can be determined by using the IPC_STAT command.
Note: Successful use of the SETAlL operation clears any semaphore adjustment information for all semaphores in the set in any process. See the semop function description for information on semaphore adjustment.
GETNCNT - Returns the number of callers waiting for the value of the semaphore selected by the num argument to become non-zero. argument is not used, and need not be specified.
GETZCNT - Returns the number of callers waiting for the value of the semaphore selected by the num argument to become zero. argument is not used, and need not be specified.
GETPID - Returns the process id of the process which most recently updated the semaphore selected by the num argument. argument is not used, and need not be specified.

Several of the semctl operations allow you to obtain or access the semaphore set id data structure, which is mapped by the struct semid_ds type defined in

sys/sem.h .

This data structure is defined as follows:

struct semid_ds {
   /* permission information */
   struct ipc_perm sem_perm;

   /* number of semaphores in set */
   unsigned short sem_nsems;

   /* time of last semop call */
   time_t sem_otime;

   /* time of last change by semctl */
   time_t sem_ctime;
};

The ipc_perm structure, which contains security information about the owner and the creator of the semaphore set, is defined as follows:

struct ipc_perm {
   /* owner's effective user ID */
   uid_t uid;

   /* owner's effective group ID */
   gid_t gid;

   /* creator's effective user ID */
   uid_t cuid;

   /* creator's effective group ID */
   gid_t cgid;

   /* read/write permission bits */
   mode_t mode;
};

RETURN VALUE

For operations of GETVAL , GETNCNT , GETZCNT and GETPID , semctl returns the information requested. For all others, it returns 0 if successful. In all cases, it returns -1 if unsuccessful.

USAGE NOTES

The semctl function can only be used with MVS 5.2.2 or a later release.

RELATED FUNCTIONS

semget , semop

Chapter Contents
Previous
Next
Top of Page