diff options
Diffstat (limited to 'man2/getitimer.2')
| -rw-r--r-- | man2/getitimer.2 | 278 |
1 files changed, 278 insertions, 0 deletions
diff --git a/man2/getitimer.2 b/man2/getitimer.2 new file mode 100644 index 0000000..422a04e --- /dev/null +++ b/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 2023-05-03 "Linux man-pages 6.05.01" +.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> +.PP +.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). +.PP +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. +.PP +A process has only one of each of the three types of timers. +.PP +Timer values are defined by the following structures: +.PP +.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 . +.PP +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). +.PP +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 ()). +.PP +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. +.PP +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: +.PP +.in +4n +.EX +setitimer(which, NULL, &old_value); +.EE +.in +.PP +Many systems (Solaris, the BSDs, and perhaps others) +treat this as equivalent to: +.PP +.in +4n +.EX +getitimer(which, &old_value); +.EE +.in +.PP +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. +.PP +A child created via +.BR fork (2) +does not inherit its parent's interval timers. +Interval timers are preserved across an +.BR execve (2). +.PP +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. +.PP +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. +.PP +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 +.PP +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) |