getitimer.2: Substantial rewrites to various parts of the page

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man2/getitimer.2 b/man2/getitimer.2
index e941d6d9fc1316246ba4be43ee961e712fd5d591..e9694f4a0a8b8dca641fc7dfee88c760a7834754 100644 (file)
--- a/man2/getitimer.2
+++ b/man2/getitimer.2
@@ -1,4 +1,5 @@
 .\" Copyright 7/93 by Darren Senn <sinster@scintilla.santa-clara.ca.us>
+.\" and Copyright (C) 2016, Michael Kerrisk <mtk.manpages@gmail.com>
 .\" Based on a similar page Copyright 1992 by Rick Faith
 .\"
 .\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
@@ -22,31 +23,47 @@ getitimer, setitimer \- get or set value of an interval timer
 .BI "              struct itimerval *" old_value );
 .fi
 .SH DESCRIPTION
-The system provides each process with three interval timers,
-each decrementing in a distinct time domain.
-When a timer expires, a signal is sent to the
-process, and the timer is reset to the specified interval (if nonzero).
+These system calls provide access to interval timers, that is,
+timers that initially expire at some point in the future,
+and (optionally) at regular intervals after that.
+When a timer expires, a signal is generated for the calling process,
+and the timer is reset to the specified interval
+(if the interval is nonzero).
+
+Three types of timers\(emspecified via the
+.IR which
+argument\(emare provided,
+each of which counts against a different clock and
+generates a different signal on timer expiration:
 .TP 1.5i
 .B ITIMER_REAL
-decrements in real time, and delivers
+This timer counts down in real (i.e., wall clock) time.
+At each expiration, a
 .B SIGALRM
-upon expiration.
+signal is generated.
 .TP
 .B ITIMER_VIRTUAL
-decrements only when the process is executing, and delivers
+This timer counts down against the user-mode CPU time consumed by the process.
+(The measurement includes CPU time consumed by all threads in the process.)
+At each expiration, a
 .B SIGVTALRM
-upon expiration.
+signal is generated.
 .TP
 .B ITIMER_PROF
-decrements both when the process executes and when the system is executing
-on behalf of the process.
-Coupled with
-.BR ITIMER_VIRTUAL ,
-this timer is usually used to profile the time spent by the
-application in user and kernel space.
+This timer counts down against the total (i.e., both user and system)
+CPU time consumed by the process.
+(The measurement includes CPU time consumed by all threads in the process.)
+At each expiration, a
 .B SIGPROF
-is delivered upon expiration.
+signal is generated.
+
+In conjunction with
+.BR ITIMER_VIRTUAL ,
+this timer can be used to profile user and system CPU time
+consumed by the process.
 .LP
+A process has only one of each of the three types of timers.
+
 Timer values are defined by the following structures:
 .PD 0
 .in +4n
@@ -64,68 +81,57 @@ struct timeval {
 .fi
 .in
 .PD
-.LP
+.SS getitimer()
 The function
 .BR getitimer ()
-fills the structure pointed to by
-.I curr_value
-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 subfields of the field
-.I it_value
-are set to the amount of time remaining on the timer, or zero if the timer
-is disabled.
+places the curent value of the timer specified by
+.IR which
+in the buffer pointed to by
+.IR curr_value .
+
 The
-.I it_interval
-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.
+.IR it_value
+substructure is populated with the amount of time remaining until
+the next expiration of the specified timer.
+This value changes as the timer counts down, and will be reset to
+.IR it_interval
+when the timer expires.
+If both fields of
+.IR it_value
+are zero, then this timer is currently disarmed (inactive).
 
+The
+.IR it_interval
+substructure is populated with the timer interval.
+If both fields of
+.IR it_interval
+are zero, then this is a single-shot timer (i.e., it expires just once).
+.SS getitimer()
 The function
 .BR setitimer ()
-sets the specified timer to the value in
+arms or disarms the timer specified by
+.IR which ,
+by setting the timer to the value specified by
 .IR new_value .
 If
 .I old_value
-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
-to zero, generate a signal, and reset to
-.IR it_interval .
-A timer which is set to zero
-.RI ( it_value
-is zero or the timer expires and
-.I it_interval
-is zero) stops.
-.LP
-Both
-.I tv_sec
-and
-.I tv_usec
-are significant in determining the duration of a timer.
-.LP
-Timers will never expire before the requested time,
-but may expire some (short) time afterward, which depends
-on the system timer resolution and on the system load; see
-.BR time (7).
-(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 ),
-the signal will be delivered immediately when generated.
-Otherwise, the
-delivery will be offset by a small time dependent on the system loading.
+is non-NULL,
+the buffer it points to is used to return the previous value of the timer
+(i.e., the same information that is returned by
+.BR getitimer ()).
+
+If either field in
+.IR new_value.it_value
+is nonzero,
+then the timer is armed to initially expire at the specified time.
+If both fields in
+.IR new_value.it_value
+are zero, then the timer is disarmed.
+
+The
+.IR new_value.it_interval
+field specifies the new interval for the timer;
+if both of its subfields are zero, the timer is single-shot.
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
@@ -163,6 +169,15 @@ obsolete, recommending the use of the POSIX timers API
 .BR timer_settime (2),
 etc.) instead.
 .SH NOTES
+Timers will never expire before the requested time,
+but may expire some (short) time afterward, which depends
+on the system timer resolution and on the system load; see
+.BR time (7).
+(But see BUGS below.)
+If the timer expires while the process is active (always true for
+.BR ITIMER_VIRTUAL ),
+the signal will be delivered immediately when generated.
+
 A child created via
 .BR fork (2)
 does not inherit its parent's interval timers.