1 files changed, 278 insertions, 0 deletions
diff --git a/man/man2/getitimer.2 b/man/man2/getitimer.2
new file mode 100644
index 000000000..b0a97c68f
--- /dev/null
+++ b/man/man2/getitimer.2
@@ -0,0 +1,278 @@
+.\" 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)
+.\" May be freely distributed and modified
+.\" %%%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 (date) "Linux man-pages (unreleased)"
+.SH NAME
+getitimer, setitimer \- get or set value of an interval timer
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/time.h>
+.P
+.BI "int getitimer(int " which ", struct itimerval *" curr_value );
+.BI "int setitimer(int " which ", const struct itimerval *restrict " new_value ,
+.BI "              struct itimerval *_Nullable restrict " old_value );
+.fi
+.SH DESCRIPTION
+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).
+.P
+Three types of timers\[em]specified via the
+.I which
+argument\[em]are provided,
+each of which counts against a different clock and
+generates a different signal on timer expiration:
+.TP
+.B ITIMER_REAL
+This timer counts down in real (i.e., wall clock) time.
+At each expiration, a
+.B SIGALRM
+signal is generated.
+.TP
+.B ITIMER_VIRTUAL
+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
+signal is generated.
+.TP
+.B ITIMER_PROF
+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
+signal is generated.
+.IP
+In conjunction with
+.BR ITIMER_VIRTUAL ,
+this timer can be used to profile user and system CPU time
+consumed by the process.
+.P
+A process has only one of each of the three types of timers.
+.P
+Timer values are defined by the following structures:
+.P
+.in +4n
+.EX
+struct itimerval {
+    struct timeval it_interval; /* Interval for periodic timer */
+    struct timeval it_value;    /* Time until next expiration */
+};
+\&
+struct timeval {
+    time_t      tv_sec;         /* seconds */
+    suseconds_t tv_usec;        /* microseconds */
+};
+.EE
+.in
+.\"
+.SS getitimer()
+The function
+.BR getitimer ()
+places the current value of the timer specified by
+.I which
+in the buffer pointed to by
+.IR curr_value .
+.P
+The
+.I 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
+.I it_interval
+when the timer expires.
+If both fields of
+.I it_value
+are zero, then this timer is currently disarmed (inactive).
+.P
+The
+.I it_interval
+substructure is populated with the timer interval.
+If both fields of
+.I it_interval
+are zero, then this is a single-shot timer (i.e., it expires just once).
+.SS setitimer()
+The function
+.BR setitimer ()
+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 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 ()).
+.P
+If either field in
+.I new_value.it_value
+is nonzero,
+then the timer is armed to initially expire at the specified time.
+If both fields in
+.I new_value.it_value
+are zero, then the timer is disarmed.
+.P
+The
+.I 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
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EFAULT
+.IR new_value ,
+.IR old_value ,
+or
+.I curr_value
+is not valid a pointer.
+.TP
+.B EINVAL
+.I which
+is not one of
+.BR ITIMER_REAL ,
+.BR ITIMER_VIRTUAL ,
+or
+.BR ITIMER_PROF ;
+or (since Linux 2.6.22) one of the
+.I tv_usec
+fields in the structure pointed to by
+.I new_value
+contains a value outside the range [0, 999999].
+.SH VERSIONS
+The standards are silent on the meaning of the call:
+.P
+.in +4n
+.EX
+setitimer(which, NULL, &old_value);
+.EE
+.in
+.P
+Many systems (Solaris, the BSDs, and perhaps others)
+treat this as equivalent to:
+.P
+.in +4n
+.EX
+getitimer(which, &old_value);
+.EE
+.in
+.P
+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 STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD).
+POSIX.1-2008 marks
+.BR getitimer ()
+and
+.BR setitimer ()
+obsolete, recommending the use of the POSIX timers API
+.RB ( timer_gettime (2),
+.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.
+.P
+A child created via
+.BR fork (2)
+does not inherit its parent's interval timers.
+Interval timers are preserved across an
+.BR execve (2).
+.P
+POSIX.1 leaves the
+interaction between
+.BR setitimer ()
+and the three interfaces
+.BR alarm (2),
+.BR sleep (3),
+and
+.BR usleep (3)
+unspecified.
+.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
+for a process.
+Under very heavy loading, an
+.B ITIMER_REAL
+timer may expire before the signal from a previous expiration
+has been delivered.
+The second signal in such an event will be lost.
+.P
+Before Linux 2.6.16, timer values are represented in jiffies.
+If a request is made set a timer with a value whose jiffies
+representation exceeds
+.B MAX_SEC_IN_JIFFIES
+(defined in
+.IR include/linux/jiffies.h ),
+then the timer is silently truncated to this ceiling value.
+On Linux/i386 (where, since Linux 2.6.13,
+the default jiffy is 0.004 seconds),
+this means that the ceiling value for a timer is
+approximately 99.42 days.
+Since Linux 2.6.16,
+the kernel uses a different internal representation for times,
+and this ceiling is removed.
+.P
+On certain systems (including i386),
+Linux kernels before Linux 2.6.12 have a bug which will produce
+premature timer expirations of up to one jiffy under some circumstances.
+This bug is fixed in Linux 2.6.12.
+.\" 4 Jul 2005: It looks like this bug may remain in Linux 2.4.x.
+.\"	http://lkml.org/lkml/2005/7/1/165
+.P
+POSIX.1-2001 says that
+.BR setitimer ()
+should fail if a
+.I tv_usec
+value is specified that is outside of the range [0, 999999].
+However, up to and including Linux 2.6.21,
+Linux does not give an error, but instead silently
+adjusts the corresponding seconds value for the timer.
+From Linux 2.6.22 onward,
+this nonconformance has been repaired:
+an improper
+.I tv_usec
+value results in an
+.B EINVAL
+error.
+.\" Bugzilla report 25 Apr 2006:
+.\" http://bugzilla.kernel.org/show_bug.cgi?id=6443
+.\" "setitimer() should reject noncanonical arguments"
+.SH SEE ALSO
+.BR gettimeofday (2),
+.BR sigaction (2),
+.BR signal (2),
+.BR timer_create (2),
+.BR timerfd_create (2),
+.BR time (7)