timer_create Subroutine

Edit online

Purpose

Creates a per process timer.

Library

Standard C Library (libc.a)

Syntax

#include <time.h>

int timer_create (clock_id, evp, timerid)
clockid_t clock_id;
struct sigevent *evp;
timer_t *timerid;

Description

The timer_create subroutine creates a per-process timer using the specified clock, clock_id, as the timing base. The timer_create subroutine returns, in the location referenced by timerid, a timer ID of type timer_t used to identify the timer in timer requests. This timer ID is unique within the calling process until the timer is deleted. The particular clock, clock_id, is defined in the time.h file. The timer whose ID is returned is in a disarmed state upon return from the timer_create subroutine.

The evp parameter, if non-NULL, points to a sigevent structure. This structure, allocated by the application, defines the asynchronous notification that will occur when the timer expires. If the evp parameter is NULL, the effect is as if the evp parameter pointed to a sigevent structure with the sigev_notify member having the value SIGEV_SIGNAL, the sigev_signo member having the SIGALARM default signal number, and the sigev_value member having the value of the timer ID.

This system defines a set of clocks that can be used as timing bases for per-process timers. Supported values for the clock_id parameter are the following:
Item Description
CLOCK_REALTIME The system-wide realtime clock.
CLOCK_MONOTONIC The system-wide monotonic clock. The value of this clock represents the amount of time since an unspecified point in the past. It cannot be set through the clock_settime subroutine and cannot have backward clock jumps.
CLOCK_PROCESS_CPUTIME_ID The process CPU-time clock of the calling process. The value of this clock represents the amount of execution time of the process associated with the clock.
CLOCK_THREAD_CPUTIME_ID The thread CPU-time clock of the calling thread. The value of this clock represents the amount of execution time of the thread associated with this clock.
The timer_create subroutine fails if the value defined for the clock_id parameter corresponds to:
  • The CPU-time clock of a process that is different than the process calling the function
  • The thread CPU-time clock of a thread that is different than the thread calling the function.

Parameters

Item Description
clock_id Specifies the clock to be used.
evp Points to a sigevent structure that defines the asynchronous notification.
timerid Points to the location where the timer ID is returned.

Return Values

If the timer_create subroutine succeeds, 0 is returned, and the location referenced by the timerid parameter is updated to a timer_t, which can be passed to the per-process timer calls. If an error occurs, -1 is returned and errno is set to indicate the error.

Error Codes

The timer_create subroutine will fail if:
Item Description
EAGAIN The system lacks sufficient signal queuing resources to honor the request.
EAGAIN The calling process has already created all of the timers it is allowed.
EINVAL The specified clock ID is not defined.
ENOTSUP The implementation does not support the creation of a timer attached to the CPU-time clock that is specified by the clock_id parameter and associated with a process or a thread that is different from the process or thread calling timer_create.
ENOTSUP The function is not supported with checkpoint-restart processes.