Gets the value of a specified semaphore.

Format

#include <semaphore.h>

int sem_getvalue (sem_t *sem, int *sval);

Argument

sem

The semaphore for which a value is to be returned.

sval

The location to be updated with the value of the semaphore indicated by the sem argument.

Description

The sem_getvalue function updates a location referenced by the sval argument with the value of semaphore sem. The updated value represents an actual semaphore value that occurred during the call, but may not be the actual value of the semaphore at the time that the value is returned to the calling process.

If the semaphore is locked, the value returned will either be zero or a negative number indicating the number of processes waiting for the semaphore at some time during the call.

Return Values

0	Successful completion.
- 1	Indicates an error. The function sets errno to one of the following values: EINVAL -- The sem argument is not a valid semaphore. EVMSERR -- OpenVMS specific nontranslatable error code.

Initializes an unnamed semaphore.

Format

#include <semaphore.h>

int sem_init (sem_t *sem, int pshared, unsigned int value );

Argument

sem

The location to receive the descriptor of the initialized semaphore.

pshared

A value indicating whether the semaphore should be sharable between the creating process and its descendants (nonzero value) or not (zero).

Note The value for pshared must be zero between threads because this release does not support unnamed semaphores to be shared across processes.

value

The initial value to be given to the semaphore.

Description

The sem_init function creates a new counting semaphore with a specific value. A semaphore is used to limit access to a critical resource. When a process requires access to the resource without interference from other processes, it attempts to establish a connection with the associated semaphore. If the semaphore value is greater than zero, the connection is established and the semaphore value is decremented by one. If the semaphore value is less than or equal to zero, the process attempting to access the resource is blocked and must wait for another process to release the semaphore and increment the semaphore value.

The sem_init function establishes a connection between an unnamed semaphore and a process; the sem_wait and sem_trywait functions lock the semaphore; and the sem_post function unlocks the semaphore. Use the sem_destroy function to deallocate system resources allocated to the process for use with the semaphore. You can use the sem_getvalue function to obtain the value of a semaphore.

A semaphore created by a call to the sem_init function remains valid until the semaphore is removed by a call to the sem_destroy function.

Return Values

0	Successful completion.
- 1	Indicates an error. The function sets errno to one of the following values: EINVAL -- The value argument exceeds {SEM_VALUE_MAX}. ENOSYS -- The function is not implemented. EVMSERR -- OpenVMS specific nontranslatable error code.

Opens/creates a named semaphore for use by a process.

Format

#include <semaphore.h>

sem_t *sem_open (const char *name, int ooption...)

;

Argument

name

a string naming the semaphore object.

ooption

Specifies whether the semaphore is to be created (O_CREAT option bit set) or only opened (O_CREAT option bit clear). If O_CREAT is set, the O_EXCL option bit may additionally be set to specify that the call should fail if a semaphore of the same name already exists. The O_CREAT and O_EXCL options are defined in the <fcntl.h> header file.

mode

The semaphore's permission bits. This argument is used only when the semaphore is being created.

value

The initial value to be given to the semaphore. This argument is used only when the semaphore is being created.

Description

Use the sem_open function to establish the connection between a named semaphore and a process. Subsequently, the calling process can reference the semaphore by using the address returned from the call. The semaphore is available in subsequent calls to sem_wait , sem_trywait , sem_post , and sem_getvalue functions. The semaphore remains usable by the process until the semaphore is closed by a successful call to the sem_close function.

The O_CREAT option bit in the ooption parameter controls whether the semaphore is created or only opened by the call to sem_open .

A created semaphore's user ID is set to the user ID of the calling process and its group ID is set to a system default group or to the group ID of the process. The semaphore's permission bits are set to the value of the mode argument, except for those set in the file mode creation mask of the process.

After a semaphore is created, other processes can open the semaphore by calling sem_open with the same value for the name argument.

Return Values

sem

Successful completion. The function opens the semaphore and returns the semaphore's descriptor.

sem_failed

Indicates an error. The function sets errno to one of the following values: EACCES---The named semaphore exists and the permissions specified by ooption are denied, or the named semaphore does not exist and the permissions specified by ooption are denied. EEXIST---O_CREAT and O_EXCL are set, and the named semaphore already exists. EINVAL---The sem_open operation is not supported for the given name. Or, O_CREAT was specified in ooption and value was greater than {SEM_VALUE_MAX}. EMFILE---Too many semaphore descriptors or file descriptors are currently in use by this process. ENAMETOOLONG---The length of the name string exceeds {PATH_MAX}, or a pathname component is longer than {NAME_MAX} while {_POSIX_NO_TRUNC} is in effect. ENFILE---Too many semaphores are currently open in the system. ENOENT O_CREAT is not set, and the named semaphore does not exist. ENOSPC---Insufficient space exists for the creation of a new named semaphore. EVMSERR---OpenVMS specific nontranslatable error code.

Performs operations on semaphores in a semaphore set.

Format

#include <sem.h>

int semop (int semid, struct sembuf *sops, size_t nsops);

Argument

semid

Semaphore set identifier.

sops

Pointer to a user-defined array of semaphore operation ( sembuf ) structures.

nsops

Number of sembuf structures in the sops array.

Description

The semop function performs operations on semaphores in the semaphore set specified by semid. These operations are supplied in a user-defined array of semaphore operation sembuf structures specified by sops. Each sembuf structure includes the following member variables:

struct sembuf { /* semaphore operation structure */ unsigned short sem_num; /* semaphore number */ short sem_op; /* semaphore operation */ short sem_flg; /* operation flags SEM_UNDO and IPC_NOWAIT */

Each semaphore operation specified by the sem_op variable is performed on the corresponding semaphore specified by the semid function argument and the sem_num variable.

The sem_op variable specifies one of three semaphore operations:

1. If sem_op is a negative integer and the calling process has change permission, one of the following occurs:
   • If semval (see <sem.h> ) is greater than or equal to the absolute value of sem_op, the absolute value of sem_op is subtracted from semval. Also, if (sem_flg &SEM_UNDO) is non-zero, the absolute value of sem_op is added to the calling process' semadj value for the specified semaphore.
   • If semval is less than the absolute value of sem_op and (sem_flg &IPC_NOWAIT) is nonzero, semop returns immediately.
   • If semval is less than the absolute value of sem_op and (sem_flg &IPC_NOWAIT) is 0, semop increments the semncnt associated with the specified semaphore and suspends execution of the calling thread until one of the following conditions occurs:
     • The value of semval becomes greater than or equal to the absolute value of sem_op. When this occurs, the value of semncnt associated with the specified semaphore is decremented, the absolute value of sem_op is subtracted from semval and, if (sem_flg &SEM_UNDO) is nonzero, the absolute value of sem_op is added to the calling process' semadj value for the specified semaphore.
     • The semid for which the calling thread is awaiting action is removed from the system. When this occurs, errno is set equal to EIDRM and - 1 is returned.
     • The calling thread receives a signal that is to be intercepted. When this occurs, the value of semncnt associated with the specified semaphore is decremented, and the calling thread is resumes execution in the manner prescribed in sigaction .
2. If sem_op is a positive integer and the calling process has change permission, the value of sem_op is added to semval and, if (sem_flg &SEM_UNDO) is nonzero, the value of sem_op is subtracted from the calling process' semadj value for the specified semaphore.
3. If sem_op is 0 and the calling process has read permission, one of the following occurs:
   • If semval is 0, semop returns immediately.
   • If semval is nonzero and (sem_flg &IPC_NOWAIT) is nonzero, semop returns immediately.
   • If semval is nonzero and (sem_flg &IPC_NOWAIT) is 0, semop increments the semzcnt associated with the specified semaphore and suspends execution of the calling thread until one of the following occurs:
     • The value of semval becomes 0, at which time the value of semzcnt associated with the specified semaphore is decremented.
     • The semid for which the calling thread is awaiting action is removed from the system. When this occurs, errno is set equal to EIDRM and - 1 is returned.
     • The calling thread receives a signal that is to be intercepted. When this occurs, the value of semzcnt associated with the specified semaphore is decremented, and the calling thread resumes execution in the manner prescribed in sigaction .

On successful completion, the value of sempid for each semaphore specified in the array pointed to by sops is set equal to the process ID of the calling process.

Return Values

0

Successful completion.

- 1

Indicates an error. The function sets errno to one of the following values: E2BIG -- The value of nsops is greater than the system-imposed maximum. EACCES -- Operation permission is denied to the calling process. EAGAIN -- The operation would result in suspension of the calling process but ( sem_flg &IPC_NOWAIT) is nonzero. EFAULT -- The arguments passed to the function are not accessible. EFBIG -- The value of sem_num is less than 0 or greater than or equal to the number of semaphores in the set associated with semid. EIDRM -- The semaphore identifier semid is removed from the system. EINVAL -- The value of semid is not a valid semaphore identifier, or the number of individual semaphores for which the calling process requests a SEM_UNDO would exceed the system-imposed limit. EVMSERR -- OpenVMS specific nontranslatable error code.

Unlocks a semaphore.

Format

#include <semaphore.h>

int sem_post (sem_t *sem);

Argument

sem

The semaphore to be unlocked.

Description

The sem_post function unlocks the specified semaphore by performing the semaphore unlock operation on that semaphore. The appropriate function ( sem_open for named semaphores or sem_init for unnamed semaphores) must be called for a semaphore before you can call the locking and unlocking functions, sem_wait , sem_trywait , and sem_post .

If the semaphore value after a sem_post function is positive, no processes were blocked waiting for the semaphore to be unlocked; the semaphore value is incremented. If the semaphore value after a sem_post function is zero, one of the processes blocked waiting for the semaphore is allowed to return successfully from its call to sem_wait .

If more than one process is blocked while waiting for the semaphore, only one process is unblocked and the state of the semaphore remains unchanged when the sem_post function returns. The process to be unblocked is selected according to the scheduling policies and priorities of all blocked processes. If the scheduling policy is SCHED_FIFO or SCHED_RR, the highest-priority waiting process is unblocked. If more than one process of that priority is blocked, then the process that has waited the longest is unblocked.

The sem_post function can be called from a signal-catching function.

Return Values

0	Successful completion. The sem_post function performs a semaphore unlock operation, unblocking a process.
- 1	Indicates an error. The function sets errno to one of the following values: EINVAL -- The sem argument is not a valid semaphore. EVMSERR -- OpenVMS specific nontranslatable error code.

Performs a semaphore lock.

Format

#include <semaphore.h>

#include <time.h>

int sem_timedwait (sem_t *sem, const struct timespec *abs_timeout);

Argument

sem

The semaphore to be locked.

abs_timeout

The absolute time after which the timeout expires.

Description

The sem_timedwait function locks the semaphore referenced by sem as in the sem_wait function. But if the semaphore cannot be locked without waiting for another process or thread to unlock the semaphore by performing a sem_post function, this wait terminates when the specified timeout expires.

The timeout expires when the absolute time specified by abs_timeout passes, as measured by the clock on which timeouts are based (that is, when the value of that clock equals or exceeds abs_timeout, or if the absolute time specified by abs_timeout has already been passed at the time of the call.

The function will not fail with a timeout if the semaphore can be locked immediately. The validity of abs_timeout does not need to be checked if the semaphore can be locked immediately.

Return Values

0

Successful completion. The function executes the semaphore lock operation.

- 1

Indicates an error. The function sets errno to one of the following values: ETIMEDOUT -- The semaphore could not be locked before the specified timeout expired. EINVAL -- The sem argument does not refer to a valid semaphore. Or the process or thread would have blocked, and the abs_timeout parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million. EVMSERR -- OpenVMS specific nontranslatable error code.

Conditionally performs a semaphore lock.

Format

#include <semaphore.h>

int sem_trywait (sem_t *sem);

Argument

sem

The semaphore to be locked.

Description

The sem_trywait function locks a semaphore only if the semaphore is currently not locked. If the semaphore value is zero, the sem_trywait function returns without locking the semaphore.

The sem_wait and sem_trywait functions help ensure that the resource associated with the semaphore cannot be accessed by other processes. The semaphore remains locked until the process unlocks it with a call to the sem_post function.

Use the sem_wait function instead of the sem_trywait function if the process should wait for access to the semaphore.

Return Values

0	Successful completion. The function executes the semaphore lock operation.
- 1	Indicates an error. The function sets errno to one of the following values: EAGAIN -- The semaphore was already locked and cannot be locked by the sem_trywait operation. EINVAL -- The sem argument does not refer to a valid semaphore. EVMSERR -- OpenVMS specific nontranslatable error code.

Removes the specified named semaphore.

Format

#include <semaphore.h>

int sem_unlink (const char *name);

Argument

name

The name of the semaphore to remove.

Description

The sem_unlink function removes a semaphore named by the name string. If the semaphore is referenced by other processes, sem_unlink does not change the state of the semaphore.

If other processes have the semaphore open when sem_unlink is called, the semaphore is not destroyed until all references to the semaphore have been destroyed by calls to sem_close . The sem_unlink function returns immediately; it does not wait until all references have been destroyed.

Calls to sem_open to recreate or reconnect to the semaphore refer to a new semaphore after sem_unlink is called.

Return Values

0	Successful completion. The function executes the semaphore unlink operation.
- 1	Indicates an error. The function sets errno to one of the following values: EACCESS -- Permission is denied to unlink the named semaphore. ENAMETOOLONG -- The length of the path name exceeds PSEM_MAX_PATHNAME defined in semaphore.h. ENOENT -- The named semaphore does not exist. EVMSERR -- OpenVMS specific nontranslatable error code.

Performs a semaphore lock.

Format

#include <semaphore.h>

int sem_wait (sem_t *sem);

Argument

sem

The semaphore to be locked.

Description

The sem_wait function locks the semaphore referenced by sem by performing a semaphore lock operation on it. If the semaphore value is zero, the sem_wait function blocks until it either locks the semaphore or is interrupted by a signal.

The sem_wait and sem_trywait functions help ensure that the resource associated with the semaphore cannot be accessed by other processes. The semaphore remains locked until the process unlocks it with a call to the sem_post function.

Use the sem_wait function instead of the sem_trywait function if the process should wait for access to the semaphore.

Return Values

0	Successful completion. The function executes the semaphore lock operation.
- 1	Indicates an error. The function sets errno to one of the following values: EINTR -- A signal interrupted this function. EVMSERR -- OpenVMS specific nontranslatable error code.