👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for timer_settime (linux section 3posix)

TIMER_GETOVERRUN(P)		    POSIX Programmer's Manual		      TIMER_GETOVERRUN(P)

NAME
       timer_getoverrun, timer_gettime, timer_settime - per-process timers (REALTIME)

SYNOPSIS
       #include <time.h>

       int timer_getoverrun(timer_t timerid);
       int timer_gettime(timer_t timerid, struct itimerspec *value);
       int timer_settime(timer_t timerid, int flags,
	      const struct itimerspec *restrict value,
	      struct itimerspec *restrict ovalue);

DESCRIPTION
       The  timer_gettime()  function  shall  store the amount of time until the specified timer,
       timerid, expires and the reload value of the timer into the space pointed to by the  value
       argument.  The  it_value  member of this structure shall contain the amount of time before
       the timer expires, or zero if the timer is disarmed. This value is returned as the  inter-
       val  until timer expiration, even if the timer was armed with absolute time. The it_inter-
       val member of value shall contain the reload value last set by timer_settime().

       The timer_settime() function shall set the time until the next  expiration  of  the  timer
       specified  by  timerid from the it_value member of the value argument and arm the timer if
       the it_value member of value is non-zero. If the specified timer was  already  armed  when
       timer_settime()	is  called,  this  call shall reset the time until next expiration to the
       value specified. If the it_value member of value is zero, the timer shall be disarmed. The
       effect of disarming or resetting a timer with pending expiration notifications is unspeci-
       fied.

       If the flag TIMER_ABSTIME is not set in the argument flags, timer_settime()  shall  behave
       as  if  the time until next expiration is set to be equal to the interval specified by the
       it_value member of value. That is, the timer shall expire  in  it_value	nanoseconds  from
       when  the call is made. If the flag TIMER_ABSTIME is set in the argument flags, timer_set-
       time() shall behave as if the time until next expiration is set to be equal to the differ-
       ence  between  the absolute time specified by the it_value member of value and the current
       value of the clock associated with timerid.  That is, the  timer  shall	expire	when  the
       clock  reaches  the value specified by the it_value member of value. If the specified time
       has already passed, the function shall succeed and the expiration  notification	shall  be
       made.

       The  reload value of the timer shall be set to the value specified by the it_interval mem-
       ber of value. When a timer is armed with a non-zero it_interval, a  periodic  (or  repeti-
       tive) timer is specified.

       Time values that are between two consecutive non-negative integer multiples of the resolu-
       tion of the specified timer shall be rounded up to the larger multiple of the  resolution.
       Quantization  error  shall  not	cause  the  timer to expire earlier than the rounded time
       value.

       If the argument ovalue is not NULL, the timer_settime() function shall store, in the loca-
       tion  referenced  by  ovalue,  a value representing the previous amount of time before the
       timer would have expired, or zero if the timer was disarmed, together  with  the  previous
       timer reload value. Timers shall not expire before their scheduled time.

       Only  a	single	signal	shall  be queued to the process for a given timer at any point in
       time. When a timer for which a signal is still pending expires, no signal shall be queued,
       and  a  timer  overrun  shall  occur.	When a timer expiration signal is delivered to or
       accepted by a process, if the implementation supports the Realtime Signals Extension,  the
       timer_getoverrun() function shall return the timer expiration overrun count for the speci-
       fied timer. The overrun count returned contains the number of extra timer expirations that
       occurred  between  the time the signal was generated (queued) and when it was delivered or
       accepted, up to but not including an implementation-defined maximum  of	{DELAYTIMER_MAX}.
       If the number of such extra expirations is greater than or equal to {DELAYTIMER_MAX}, then
       the overrun count shall be set to {DELAYTIMER_MAX}. The value returned  by  timer_getover-
       run()  shall  apply  to	the  most recent expiration signal delivery or acceptance for the
       timer.  If no expiration signal has been delivered for the timer, or if the Realtime  Sig-
       nals Extension is not supported, the return value of timer_getoverrun() is unspecified.

RETURN VALUE
       If  the timer_getoverrun() function succeeds, it shall return the timer expiration overrun
       count as explained above.

       If the timer_gettime() or timer_settime()  functions  succeed,  a  value  of  0	shall  be
       returned.

       If  an  error occurs for any of these functions, the value -1 shall be returned, and errno
       set to indicate the error.

ERRORS
       The timer_getoverrun(), timer_gettime(), and timer_settime() functions shall fail if:

       EINVAL The timerid argument does not correspond to an ID returned  by  timer_create()  but
	      not yet deleted by timer_delete().

       The timer_settime() function shall fail if:

       EINVAL A  value	structure  specified a nanosecond value less than zero or greater than or
	      equal to 1000 million, and the it_value member of that structure	did  not  specify
	      zero seconds and nanoseconds.

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       None.

RATIONALE
       Practical  clocks tick at a finite rate, with rates of 100 hertz and 1000 hertz being com-
       mon. The inverse of this tick rate is the clock resolution, also called the  clock  granu-
       larity,	which in either case is expressed as a time duration, being 10 milliseconds and 1
       millisecond respectively for these common rates.   The  granularity  of	practical  clocks
       implies	that  if  one reads a given clock twice in rapid succession, one may get the same
       time value twice; and that timers must wait for the next clock tick after the  theoretical
       expiration  time, to ensure that a timer never returns too soon. Note also that the granu-
       larity of the clock may be significantly coarser than the resolution of	the  data  format
       used  to  set  and  get	time and interval values. Also note that some implementations may
       choose to adjust time and/or interval values to exactly match the ticks of the  underlying
       clock.

       This  volume of IEEE Std 1003.1-2001 defines functions that allow an application to deter-
       mine the implementation-supported resolution for the clocks and requires an implementation
       to  document  the  resolution supported for timers and nanosleep() if they differ from the
       supported clock resolution.  This is more of a procurement issue than a	runtime  applica-
       tion issue.

FUTURE DIRECTIONS
       None.

SEE ALSO
       clock_getres()  ,  timer_create()  ,  the Base Definitions volume of IEEE Std 1003.1-2001,
       <time.h>

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003			      TIMER_GETOVERRUN(P)


All times are GMT -4. The time now is 01:30 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password