__semop_timed() — Semaphore operations with timeout

Standards

Standards / Extensions C or C++ Dependencies
z/OS® UNIX both

OS/390 V2R10

Format

#define _OPEN_SYS_TIMED_EXT 1
#include <time.h>
#include <sys/sem.h>

int __semop_timed(int semid, struct sembuf *sops, size_t nsops,
                  struct timespec *set)

General description

Performs semaphore operations atomically on a set of semaphores associated with argument semid. The argument sops is a pointer to an array of sembuf data structures. The argument nsops is the number of sembuf structures in the array. The argument set the structure timespec with the timeout values.

The structure sembuf is defined as follows:

    short    sem_num    Semaphore number in the range 0 to (nsems - 1)
    short    sem_op     Semaphore operation
    short    sem_flg    Operation flags

Each semaphore in the semaphore set, identified by sem_num, is represented by the following anonymous data structure. This data structure for all semaphores is updated automatically when semop() returns successfully:
unsigned short int semval Semaphore value
pid_t sempid Process ID of last operation
unsigned sort int semcnt Number of processes waiting for semval to become greater than current value
unsigned short int semzcnt Number of processes waiting for semval to become zero

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

The variable sem_op specifies one of three semaphore operations:
  1. If sem_op is a negative integer and the calling process has alter permission, one of the following will occur:
    • If semval, see <sys/sem.h>, is greater than or equal to the absolute value of sem_op, the absolute value of sem_op is subtracted from semval.
    • If semval is less than the absolute value of sem_op and (sem_flg & IPC_NOWAIT) is nonzero, semop() will return immediately.
    • If semval is less than the absolute value of sem_op and (sem_flg & IPC_NOWAIT) is zero, semop() will increment the semncnt associated with the specified semaphore and suspend execution of the calling process 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.
      • The semid for which the calling process is awaiting action is removed from the system. When this occurs, errno is set equal to EIDRM and -1 is returned.
      • The calling process receives a signal that is to be caught. When this occurs, the value of semncnt associated with the specified semaphore is decremented, and the calling process resumes execution in the manner prescribed in sigaction().
  2. If sem_op is a positive integer and the calling process has alter permission, the value of sem_op is added to semval.
  3. If sem_op is zero and the calling process has read permission, one of the following will occur:
    • If semval is zero, semop() will return immediately.
    • If semval is nonzero and (sem_flg&IPC_NOWAIT) is nonzero, semop() will return immediately.
    • If semval is nonzero and (sem_flg&IPC_NOWAIT) is 0, semop() will increment the semzcnt associated with the specified semaphore and suspend 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 process is awaiting action is removed from the system. When this occurs, errno is set equal to EIDRM and -1 is returned.
      • The calling process receives a signal that is to be caught. When this occurs, the value of semzcnt associated with the specified semaphore is decremented, and the calling process resumes execution in the manner prescribed in sigaction().
      • Upon 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.
The variable, set, gives the timeout specification.
  • If the __semop_timed() function finds that none of the semaphores specified by semid are received, it waits for the time interval specified in the timespec structure referenced by set. If the timespec structure pointed to by set is zero-valued and if none of the semaphores specified by semid are received, then __semop_timed() returns immediately with EAGAIN. A timespec with the tv_sec field set with INT_MAX, as defined in <limits.h>, will cause the __semop_timed() service to wait until a semaphore is received. If set is the NULL pointer, it will be treated the same as when timespec structure was supplied with with the tv_sec field set with INT_MAX.

Returned value

If successful, __semop_timed() returns 0. Also the semid parameter value for each semaphore that is operated upon is set to the process ID of the calling process.

If unsuccessful, __semop_timed() returns -1 and sets errno to one of the following values:

Error Code
Description
E2BIG
The value nsops is greater than the system limit.
EACCES
Operation permission is denied to the calling process. Read access is required when sem_op is zero. Write access is required when sem_op is not zero.
EAGAIN
The operation would result in suspension of the calling process but IPC_NOWAIT in sem_flg was specified. This would result if the timeout specified expires before a semop is posted.
EFBIG
sem_num is less than zero or greater or equal to the number of semaphores in the set specified on in semget() argument nsems.
EIDRM
semid was removed from the system while the invoker was waiting.
EINTR
__semop_timed() was interrupted by a signal.
EINVAL
The value of argument semid is not a valid semaphore identifier.
ENOSPC
The limit on the number of individual processes requesting a SEM_UNDO would be exceeded.
ERANGE
An operation would cause semval or semadj to overflow the system limit as defined in <sys/sem.h>.

Related information

Parent topic: Library functions