HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |STANDARDS |HISTORY |EXAMPLES |SEE ALSO |COLOPHON | |
timer_settime(2) System Calls Manualtimer_settime(2)timer_settime, timer_gettime - arm/disarm and fetch state of POSIX per-process timer
Real-time library (librt,-lrt)
#include <time.h>int timer_gettime(timer_ttimerid, struct itimerspec *curr_value);int timer_settime(timer_ttimerid, intflags,const struct itimerspec *restrictnew_value,struct itimerspec *_Nullable restrictold_value); Feature Test Macro Requirements for glibc (seefeature_test_macros(7)):timer_settime(),timer_gettime(): _POSIX_C_SOURCE >= 199309L
timer_settime() arms or disarms the timer identified bytimerid. Thenew_value argument is pointer to anitimerspec structure that specifies the new initial value and the new interval for the timer. Theitimerspec structure is described initimerspec(3type). Each of the substructures of theitimerspec structure is atimespec(3) structure that allows a time value to be specified in seconds and nanoseconds. These time values are measured according to the clock that was specified when the timer was created bytimer_create(2). Ifnew_value->it_value specifies a nonzero value (i.e., either subfield is nonzero), thentimer_settime() arms (starts) the timer, setting it to initially expire at the given time. (If the timer was already armed, then the previous settings are overwritten.) Ifnew_value->it_value specifies a zero value (i.e., both subfields are zero), then the timer is disarmed. Thenew_value->it_interval field specifies the period of the timer, in seconds and nanoseconds. If this field is nonzero, then each time that an armed timer expires, the timer is reloaded from the value specified innew_value->it_interval. Ifnew_value->it_interval specifies a zero value, then the timer expires just once, at the time specified byit_value. By default, the initial expiration time specified innew_value->it_value is interpreted relative to the current time on the timer's clock at the time of the call. This can be modified by specifyingTIMER_ABSTIMEinflags, in which casenew_value->it_value is interpreted as an absolute value as measured on the timer's clock; that is, the timer will expire when the clock value reaches the value specified bynew_value->it_value. If the specified absolute time has already passed, then the timer expires immediately, and the overrun count (seetimer_getoverrun(2)) will be set correctly. If the value of theCLOCK_REALTIMEclock is adjusted while an absolute timer based on that clock is armed, then the expiration of the timer will be appropriately adjusted. Adjustments to theCLOCK_REALTIMEclock have no effect on relative timers based on that clock. Ifold_value is not NULL, then it points to a buffer that is used to return the previous interval of the timer (inold_value->it_interval) and the amount of time until the timer would previously have next expired (inold_value->it_value).timer_gettime() returns the time until next expiration, and the interval, for the timer specified bytimerid, in the buffer pointed to bycurr_value. The time remaining until the next timer expiration is returned incurr_value->it_value; this is always a relative value, regardless of whether theTIMER_ABSTIMEflag was used when arming the timer. If the value returned incurr_value->it_value is zero, then the timer is currently disarmed. The timer interval is returned incurr_value->it_interval. If the value returned incurr_value->it_interval is zero, then this is a "one-shot" timer.
On success,timer_settime() andtimer_gettime() return 0. On error, -1 is returned, anderrno is set to indicate the error.
These functions may fail with the following errors:EFAULTnew_value,old_value, orcurr_value is not a valid pointer.EINVALtimerid is invalid.timer_settime() may fail with the following errors:EINVALnew_value.it_value is negative; ornew_value.it_value.tv_nsec is negative or greater than 999,999,999.
POSIX.1-2008.
Linux 2.6. POSIX.1-2001.
Seetimer_create(2).
timer_create(2),timer_getoverrun(2),timespec(3),time(7)
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-05-17timer_settime(2)Pages that refer to this page:getitimer(2), syscalls(2), timer_create(2), timer_delete(2), timerfd_create(2), timer_getoverrun(2), itimerspec(3type), timer_t(3type), timespec(3type), ualarm(3), usleep(3), signal-safety(7), time_namespaces(7)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |