1timer_settime(3C)        Standard C Library Functions        timer_settime(3C)
2
3
4

NAME

6       timer_settime, timer_gettime, timer_getoverrun - per-process timers
7

SYNOPSIS

9       #include <time.h>
10
11       int timer_settime(timer_t timerid, int flags,
12            const struct itimerspec *restrict value,
13            struct itimerspec *restrict ovalue);
14
15
16       int timer_gettime(timer_t timerid, struct itimerspec *value);
17
18
19       int timer_getoverrun(timer_t timerid);
20
21

DESCRIPTION

23       The timer_settime() function sets the time until the next expiration of
24       the timer specified by timerid from the it_value member  of  the  value
25       argument and arm the timer if the it_value member of value is non-zero.
26       If the specified  timer  was  already  armed  when  timer_settime()  is
27       called,  this  call  resets the time until next expiration to the value
28       specified. If the it_value member of value is 0, the timer is disarmed.
29       The  effect  of  disarming  or  resetting a timer on pending expiration
30       notifications is unspecified.
31
32
33       If the flag TIMER_ABSTIME is not set in the argument flags,  timer_set‐
34       time()  behaves as if the time until next expiration is set to be equal
35       to the interval specified by the it_value member of value. That is, the
36       timer  expires  in  it_value nanoseconds from when the call is made. If
37       the flag TIMER_ABSTIME is set in the  argument  flags,  timer_settime()
38       behaves  as if the time until next expiration is set to be equal to the
39       difference between the absolute time specified by the  it_value  member
40       of  value  and  the current value of the clock associated with timerid.
41       That is, the timer expires when the clock reaches the  value  specified
42       by  the  it_value  member  of  value. If the specified time has already
43       passed, the function succeeds and the expiration notification is made.
44
45
46       The reload value of the timer is set to  the  value  specified  by  the
47       it_interval  member  of  value.  When  a timer is armed with a non-zero
48       it_interval, a periodic (or repetitive) timer is specified.
49
50
51       Time values that are between two consecutive non-negative integer  mul‐
52       tiples  of  the resolution of the specified timer will be rounded up to
53       the larger multiple of the  resolution.  Quantization  error  will  not
54       cause the timer to expire earlier than the rounded time value.
55
56
57       If  the  argument  ovalue  is  not  NULL,  the function timer_settime()
58       stores, in the location referenced by ovalue, a value representing  the
59       previous amount of time before the timer would have expired or 0 if the
60       timer was disarmed, together with the previous timer reload value.  The
61       members  of ovalue are subject to the resolution of the timer, and they
62       are the same values that would be returned by a timer_gettime() call at
63       that point in time.
64
65
66       The timer_gettime() function stores the amount of time until the speci‐
67       fied timer, timerid, expires and the reload value of the timer into the
68       space  pointed  to  by  the value argument. The it_value member of this
69       structure contains the amount of time before the timer expires, or 0 if
70       the  timer  is  disarmed.  This value is returned as the interval until
71       timer expiration, even if the timer was armed with absolute  time.  The
72       it_interval  member  of  value  contains  the  reload value last set by
73       timer_settime().
74
75
76       Only a single signal will be queued to the process for a given timer at
77       any  point  in  time.  When a timer for which a signal is still pending
78       expires, no signal will be queued, and a timer overrun occurs.  When  a
79       timer  expiration  signal is delivered to or accepted by a process, the
80       timer_getoverrun() function returns the timer expiration overrun  count
81       for the specified timer. The overrun count returned contains the number
82       of extra timer expirations that occurred between the  time  the  signal
83       was generated (queued) and when it was delivered or accepted, up to but
84       not including an implementation-dependent maximum of DELAYTIMER_MAX. If
85       the number of such extra expirations is greater than or equal to DELAY‐
86       TIMER_MAX, then the overrun count will be set  to  DELAYTIMER_MAX.  The
87       value returned by timer_getoverrun() applies to the most recent expira‐
88       tion signal delivery or acceptance for the timer. If no expiration sig‐
89       nal  has been delivered for the timer, the meaning of the overrun count
90       returned is undefined.
91

RETURN VALUES

93       If the timer_settime()  or  timer_gettime()  functions  succeed,  0  is
94       returned.  If  an  error  occurs  for  either of these functions, −1 is
95       returned, and errno is set to indicate the error. If the timer_getover‐
96       run()  function succeeds, it returns the timer expiration overrun count
97       as explained above.
98

ERRORS

100       The timer_settime(), timer_gettime() and  timer_getoverrun()  functions
101       will fail if:
102
103       EINVAL     The timerid argument does not correspond to a timer returned
104                  by timer_create(3C) but not yet deleted by timer_delete(3C).
105
106
107       ENOSYS     The timer_settime(), timer_gettime(), and timer_getoverrun()
108                  functions  are  not  supported by the system. The timer_set‐
109                  time() function will fail if:
110
111
112       EINVAL     A value structure specified a  nanosecond  value  less  than
113                  zero or greater than or equal to 1000 million.
114
115

ATTRIBUTES

117       See attributes(5) for descriptions of the following attributes:
118
119
120
121
122       ┌─────────────────────────────┬─────────────────────────────┐
123       │ATTRIBUTE TYPE               │ATTRIBUTE VALUE              │
124       ├─────────────────────────────┼─────────────────────────────┤
125       │Interface Stability          │Committed                    │
126       ├─────────────────────────────┼─────────────────────────────┤
127       │MT-Level                     │Async-Signal-Safe            │
128       ├─────────────────────────────┼─────────────────────────────┤
129       │Standard                     │See standards(5).            │
130       └─────────────────────────────┴─────────────────────────────┘
131

SEE ALSO

133       time.h(3HEAD),  clock_settime(3C),  timer_create(3C), timer_delete(3C),
134       attributes(5), standards(5)
135
136
137
138SunOS 5.11                        5 Feb 2008                 timer_settime(3C)
Impressum