DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

timer_create(S)


timer_create -- create a per-process timer

Syntax

cc . . . -lsuds
#include <signal.h>
#include <time.h>

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

Description

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

The evp argument, 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 sigev_notify member of evp is SIGEV_SIGNAL, then the structure also contains the signal number and the application-specific data value to be sent to the process when the timer expires. If the sigev_notify member is SIGEV_NONE, no notification is sent.

A set of clocks is defined; these can be used as timing bases for per-process timers, and one or more mechanisms for notifying the process of timer expiration events. A clock ID of CLOCK_REALTIME and signals are supported (see Section 3.3 of IEEE Std 1003.1b-1993 for more details).

If evp points to a sigevent structure that specifies SIGEV_SIGNAL, then the signal number defined in the sigevent structure is sent to the process on timer expiration. If evp is NULL, then a default signal is sent to the process.

If clock_id specifies the CLOCK_REALTIME system clock, then the default signal, when evp is NULL, is SIGALRM.

Per-process timers are not inherited by a child process across a fork(S) and are disarmed and deleted by an exec(S).

Return values

If the call succeeds, timer_create returns zero and updates the location referenced by timerid to a timer_t which can be passed to the per-process timer calls (see Section 14.2.4 of IEEE Std 1003.1b-1993). If an error occurs, the function returns a value of -l and sets errno to indicate the error.

Diagnostics

If any of the following conditions occur, the timer_create function returns -1 and sets errno to the corresponding value:

[EAGAIN]
The system lacks sufficient signal queuing resources to honor the request.

The calling process has already created all of the timers it is allowed.


[EINVAL]
The specified clock ID is not defined.

See also

time(FP), timer_delete(S), timer_gettime(S), timer_settime(S)

Standards conformance

Text reprinted and/or adapted from IEEE Std 1003.1b-1993, IEEE Standard for Information Technology, POSIX Part 1: System Application Program Interface (API) Amendment 1: Realtime Extensions [C Language], copyright © 1993 by the Institute of Electrical and Electronics Engineers, Inc. The IEEE takes no responsibility for and will assume no liability for damages resulting from the reader's misinterpretation of said information resulting from the placement and context in this publication. Information is reproduced with the permission of the IEEE.
© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003