sem_wait_np()-Wait for Semaphore with Timeout

#include <semaphore.h>

int sem_wait_np(sem_t * sem,
                sem_wait_options_np_t * options);

The sem_wait_np() function attempts to decrement by one the value of the semaphore. The semaphore will be decremented by one when its value is greater than zero. If the value of the semaphore is zero, then the current thread will block until the semaphore's value becomes greater than zero or until the timeout period specified on the options parameter has ended. If the semaphore is not decremented before the timeout ends, sem_wait_np() will return with an error, setting errno to [ETIMEDOUT].

Parameters

sem

(Input) A pointer to an initialized unnamed semaphore or opened named semaphore.

options

(Input) A pointer to a semaphore wait (sem_wait_options_np_t) structure. The members of the sem_wait_options_np_t structure are as follows:

unsigned int reserved1[2]

A reserved field that must be set to zero.

struct sem_timeout_t timeout

The time, in MI time, that sem_wait_np() should wait for the semaphore. If the timeout is zero, sem_wait_np() will return immediately with errno set to [ETIMEDOUT] if the semaphore cannot be decremented. If a timeout value of 0xFFFFFFFF FFFFFFFF is specified, then sem_wait_np() will wait indefinitely. The maximum timeout that may be specified is 281 272 976 710 655 (2 ** 48 -1) microseconds. Any value larger than this, other than 0xFFFFFFFF FFFFFFFF, will cause sem_wait_np() to wait for the maximum timeout (281 272 976 710 655 microseconds). The Qp0zCvtToMITime() may be used to convert a timeval structure to the corresponding MI time.

Authorities

None

Return Value

0

sem_wait_np() was successful.

-1

sem_wait_np() was not successful. The errno variable is set to indicate the error.

Error Conditions

If sem_wait_np() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

[ECANCEL]

Operation canceled.

[EDESTROYED]

The semaphore was destroyed.

[EINTR]

Interrupted function call.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL.

[ETIMEDOUT]

A remote host did not respond within the timeout period.

Error Messages

None.

Related Information

• The <semaphore.h> file (see Header Files for UNIX-Type Functions)

• sem_close()-Close Named Semaphore

• sem_destroy()-Destroy Unnamed Semaphore

• sem_getvalue()-Get Semaphore Value

• sem_init()-Initialize Unnamed Semaphore

• sem_init_np()-Initialize Unnamed Semaphore with Maximum Value

• sem_open()-Open Named Semaphore

• sem_open_np()-Open Named Semaphore with Maximum Value

• sem_post()-Post to Semaphore

• sem_post_np()-Post Value to Semaphore

• sem_trywait()-Try to Decrement Semaphore

• sem_unlink()-Unlink Named Semaphore

• sem_wait_np()-Wait for Semaphore with Timeout

Example

The following example creates a semaphore with an initial value of 1. The value is decremented using sem_wait(). The program then attempts to decrement the semaphore using sem_wait_np() with a timeout of 2 seconds. This will fail with ETIMEDOUT because the semaphore's value is currently zero.

#include <stdio.h>
#include <errno.h>
#include <semaphore.h>
#include <time.h>
#include <qp0z1170.h>

main() {
  sem_t my_semaphore;
  int value;
  sem_wait_options_np_t options;
  int rc;
  struct timeval waittime;
  time_t start_time;
  time_t end_time;

  sem_init(&my_semaphore, 0, 1);
  sem_getvalue(&my_semaphore, &value);
  printf("The initial value of the semaphore is %d\n", value);
  sem_wait(&my_semaphore);
  sem_getvalue(&my_semaphore, &value);
  printf("The value of the semaphore after the wait is %d\n", value);
  memset(&options, 0, sizeof(options));
  waittime.tv_sec = 2;
  waittime.tv_usec = 0;
  Qp0zCvtToMITime((unsigned char *) &options.timeout,
                  wait_time,
                  QP0Z_CVTTIME_TO_OFFSET);
  time(&start_time);
  rc = sem_wait_np(&my_semaphore, &options);
  time(&end_time);
  if ((rc == -1) && (errno == ETIMEDOUT)) {
     printf("sem_wait_np timed out after %d seconds\n",
            end_time - start_time);
  }
}

Output:

The initial value of the semaphore is 1
The value of the semaphore after the wait is 0
sem_wait_np timed out after 2 seconds