LDP: Update original to LDP v3.79

[linuxjm/LDP_man-pages.git] / original / man2 / getitimer.2

diff --git a/original/man2/getitimer.2 b/original/man2/getitimer.2
index cf0a579..7d687ef 100644 (file)
--- a/original/man2/getitimer.2
+++ b/original/man2/getitimer.2
@@ -1,10 +1,15 @@
 .\" Copyright 7/93 by Darren Senn <sinster@scintilla.santa-clara.ca.us>
 .\" Based on a similar page Copyright 1992 by Rick Faith
+.\"
+.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
 .\" May be freely distributed
+.\" %%%LICENSE_END
+.\"
 .\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
 .\" 2005-04-06 mtk, Matthias Lang <matthias@corelatus.se>
 .\"    Noted MAX_SEC_IN_JIFFIES ceiling
-.TH GETITIMER 2 2009-03-15 "Linux" "Linux Programmer's Manual"
+.\"
+.TH GETITIMER 2 2014-07-08 "Linux" "Linux Programmer's Manual"
 .SH NAME
 getitimer, setitimer \- get or set value of an interval timer
 .SH SYNOPSIS
@@ -19,8 +24,8 @@ getitimer, setitimer \- get or set value of an interval timer
 .SH DESCRIPTION
 The system provides each process with three interval timers,
 each decrementing in a distinct time domain.
-When any timer expires, a signal is sent to the
-process, and the timer (potentially) restarts.
+When a timer expires, a signal is sent to the
+process, and the timer is reset to the specified interval (if nonzero).
 .TP 1.5i
 .B ITIMER_REAL
 decrements in real time, and delivers
@@ -48,13 +53,13 @@ Timer values are defined by the following structures:
 .nf
 
 struct itimerval {
-    struct timeval it_interval; /* next value */
-    struct timeval it_value;    /* current value */
+    struct timeval it_interval; /* Interval for periodic timer */
+    struct timeval it_value;    /* Time until next expiration */
 };
 
 struct timeval {
-    long tv_sec;                /* seconds */
-    long tv_usec;               /* microseconds */
+    time_t      tv_sec;         /* seconds */
+    suseconds_t tv_usec;        /* microseconds */
 };
 .fi
 .in
@@ -64,20 +69,24 @@ The function
 .BR getitimer ()
 fills the structure pointed to by
 .I curr_value
-with the current setting for the timer specified by
+with the current value
+(i.e., the amount of time remaining until the next expiration)
+of the timer specified by
 .I which
 (one of
 .BR ITIMER_REAL ,
 .BR ITIMER_VIRTUAL ,
 or
 .BR ITIMER_PROF ).
-The element
+The subfields of the field
 .I it_value
-is set to the amount of time remaining on the timer, or zero if the timer
+are set to the amount of time remaining on the timer, or zero if the timer
 is disabled.
-Similarly,
+The
 .I it_interval
-is set to the reset value.
+field is set to the timer interval (period);
+a value of zero returned in (both subfields of) this field indicates
+that this is a single-shot timer.
 
 The function
 .BR setitimer ()
@@ -85,7 +94,10 @@ sets the specified timer to the value in
 .IR new_value .
 If
 .I old_value
-is non-NULL, the old value of the timer is stored there.
+is non-NULL, the old value of the timer
+(i.e., the same information as returned by
+.BR getitimer ())
+is stored there.
 .LP
 Timers decrement from
 .I it_value
@@ -110,11 +122,11 @@ on the system timer resolution and on the system load; see
 (But see BUGS below.)
 Upon expiration, a signal will be generated and the timer reset.
 If the timer expires while the process is active (always true for
-.BR ITIMER_VIRTUAL )
+.BR ITIMER_VIRTUAL ),
 the signal will be delivered immediately when generated.
-Otherwise the
+Otherwise, the
 delivery will be offset by a small time dependent on the system loading.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
 .I errno
@@ -140,7 +152,7 @@ or (since Linux 2.6.22) one of the
 fields in the structure pointed to by
 .I new_value
 contains a value outside the range 0 to 999999.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
 POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD).
 POSIX.1-2008 marks
 .BR getitimer ()
@@ -166,6 +178,21 @@ and the three interfaces
 and
 .BR usleep (3)
 unspecified.
+
+The standards are silent on the meaning of the call:
+
+    setitimer(which, NULL, &old_value);
+
+Many systems (Solaris, the BSDs, and perhaps others)
+treat this as equivalent to:
+
+    getitimer(which, &old_value);
+
+In Linux, this is treated as being equivalent to a call in which the
+.I new_value
+fields are zero; that is, the timer is disabled.
+.IR "Don't use this Linux misfeature" :
+it is nonportable and unnecessary.
 .SH BUGS
 The generation and delivery of a signal are distinct, and
 only one instance of each of the signals listed above may be pending
@@ -216,10 +243,19 @@ error.
 .\" Bugzilla report 25 Apr 2006:
 .\" http://bugzilla.kernel.org/show_bug.cgi?id=6443
 .\" "setitimer() should reject noncanonical arguments"
-.SH "SEE ALSO"
+.SH SEE ALSO
 .BR gettimeofday (2),
 .BR sigaction (2),
 .BR signal (2),
 .BR timer_create (2),
 .BR timerfd_create (2),
 .BR time (7)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.