draft/man2/timer_settime.2

   1 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\"*******************************************************************
  24 .\"
  25 .\" This file was generated with po4a. Translate the source file.
  26 .\"
  27 .\"*******************************************************************
  28 .TH TIMER_SETTIME 2 2009\-02\-20 Linux "Linux Programmer's Manual"
  29 .SH 名前
  30 timer_settime, timer_gettime \- arm/disarm and fetch state of POSIX
  31 per\-process timer
  32 .SH 書式
  33 .nf
  34 \fB#include <time.h>\fP
  35
  36 \fBint timer_settime(timer_t \fP\fItimerid\fP\fB, int \fP\fIflags\fP\fB,\fP
  37 \fB                  const struct itimerspec *\fP\fInew_value\fP\fB,\fP
  38 \fB                  struct itimerspec * \fP\fIold_value\fP\fB);\fP
  39 \fBint timer_gettime(timer_t \fP\fItimerid\fP\fB, struct itimerspec *\fP\fIcurr_value\fP\fB);\fP
  40 .fi
  41
  42 Link with \fI\-lrt\fP.
  43 .sp
  44 .in -4n
  45 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  46 .in
  47 .sp
  48 \fBtimer_settime\fP(), \fBtimer_gettime\fP(): _POSIX_C_SOURCE\ >=\ 199309L
  49 .SH 説明
  50 \fBtimer_settime\fP()  arms or disarms the timer identified by \fItimerid\fP.  The
  51 \fInew_value\fP argument is an \fIitimerspec\fP structure that specifies the new
  52 initial value and the new interval for the timer.  The \fIitimerspec\fP
  53 structure is defined as follows:
  54
  55 .in +4n
  56 .nf
  57 struct timespec {
  58     time_t tv_sec;                /* Seconds */
  59     long   tv_nsec;               /* Nanoseconds */
  60 };
  61
  62 struct itimerspec {
  63     struct timespec it_interval;  /* Timer interval */
  64     struct timespec it_value;     /* Initial expiration */
  65 };
  66 .fi
  67 .in
  68
  69 Each of the substructures of the \fIitimerspec\fP structure is a \fItimespec\fP
  70 structure that allows a time value to be specified in seconds and
  71 nanoseconds.  These time values are measured according to the clock that was
  72 specified when the timer was created by \fBtimer_create\fP(2)
  73
  74 If \fInew_value\->it_value\fP specifies a nonzero value (i.e., either
  75 subfield is nonzero), then \fBtimer_settime\fP()  arms (starts) the timer,
  76 setting it to initially expire at the given time.  (If the timer was already
  77 armed, then the previous settings are overwritten.)  If
  78 \fInew_value\->it_value\fP specifies a zero value (i.e., both subfields are
  79 zero), then the timer is disarmed.
  80
  81 The \fInew_value\->it_interval\fP field specifies the period of the timer,
  82 in seconds and nanoseconds.  If this field is nonzero, then each time that
  83 an armed timer expires, the timer is reloaded from the value specified in
  84 \fInew_value\->it_interval\fP.  If \fInew_value\->it_interval\fP specifies a
  85 zero value then the timer expires just once, at the time specified by
  86 \fIit_value\fP.
  87
  88 .\" By experiment: the overrun count is set correctly, for CLOCK_REALTIME.
  89 By default, the initial expiration time specified in
  90 \fInew_value\->it_value\fP is interpreted relative to the current time on
  91 the timer's clock at the time of the call.  This can be modified by
  92 specifying \fBTIMER_ABSTIME\fP in \fIflags\fP, in which case
  93 \fInew_value\->it_value\fP is interpreted as an absolute value as measured
  94 on the timer's clock; that is, the timer will expire when the clock value
  95 reaches the value specified by \fInew_value\->it_value\fP.  If the specified
  96 absolute time has already passed, then the timer expires immediately, and
  97 the overrun count (see \fBtimer_getoverrun\fP(2))  will be set correctly.
  98
  99 .\" Similar remarks might apply with respect to process and thread CPU time
 100 .\" clocks, but these clocks are not currently (2.6.28) settable on Linux.
 101 If the value of the \fBCLOCK_REALTIME\fP clock is adjusted while an absolute
 102 timer based on that clock is armed, then the expiration of the timer will be
 103 appropriately adjusted.  Adjustments to the \fBCLOCK_REALTIME\fP clock have no
 104 effect on relative timers based on that clock.
 105
 106 If \fIold_value\fP is not NULL, then it returns the previous interval of the
 107 timer (in \fIold_value\->it_interval\fP)  and the amount of time until the
 108 timer would previously have next expired (in \fIold_value\->it_value\fP).
 109
 110 \fBtimer_gettime\fP()  returns the time until next expiration, and the
 111 interval, for the timer specified by \fItimerid\fP, in the buffer pointed to by
 112 \fIcurr_value\fP.  The time remaining until the next timer expiration is
 113 returned in \fIcurr_value\->it_value\fP; this is always a relative value,
 114 regardless of whether the \fBTIMER_ABSTIME\fP flag was used when arming the
 115 timer.  If the value returned in \fIcurr_value\->it_value\fP is zero, then
 116 the timer is currently disarmed.  The timer interval is returned in
 117 \fIcurr_value\->it_interval\fP.  If the value returned in
 118 \fIcurr_value\->it_interval\fP is zero, then this is a "one\-shot" timer.
 119 .SH 返り値
 120 On success, \fBtimer_settime\fP()  and \fBtimer_gettime\fP()  return 0.  On error,
 121 \-1 is returned, and \fIerrno\fP is set to indicate the error.
 122 .SH エラー
 123 These functions may fail with the following errors:
 124 .TP
 125 \fBEFAULT\fP
 126 \fInew_value\fP, \fIold_value\fP, or \fIcurr_value\fP is not a valid pointer.
 127 .TP
 128 \fBEINVAL\fP
 129 .\" FIXME . eventually: invalid value in flags
 130 \fItimerid\fP is invalid.
 131 .PP
 132 \fBtimer_settime\fP()  may fail with the following errors:
 133 .TP
 134 \fBEINVAL\fP
 135 \fInew_value.it_value\fP is negative; or \fInew_value.it_value.tv_nsec\fP is
 136 negative or greater than 999,999,999.
 137 .SH バージョン
 138 These system calls are available since Linux 2.6.
 139 .SH 準拠
 140 POSIX.1\-2001.
 141 .SH 例
 142 See \fBtimer_create\fP(2).
 143 .SH 関連項目
 144 \fBtimer_create\fP(2), \fBtimer_getoverrun\fP(2), \fBtime\fP(7)
 145 .SH この文書について
 146 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部
 147 である。プロジェクトの説明とバグ報告に関する情報は
 148 http://www.kernel.org/doc/man\-pages/ に書かれている。