summaryrefslogtreecommitdiffstats
path: root/man2/getitimer.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/getitimer.2')
-rw-r--r--man2/getitimer.2278
1 files changed, 0 insertions, 278 deletions
diff --git a/man2/getitimer.2 b/man2/getitimer.2
deleted file mode 100644
index 6674117..0000000
--- a/man2/getitimer.2
+++ /dev/null
@@ -1,278 +0,0 @@
-.\" 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 2023-10-31 "Linux man-pages 6.7"
-.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)