*** UNIX MANUAL PAGE BROWSER ***

CLOCK_GETTIME(2) FreeBSD System Calls Manual CLOCK_GETTIME(2) NAME clock_gettime, clock_settime, clock_getres - get or set the time SYNOPSIS #include <time.h> int clock_gettime(clockid_t clock, struct timespec *now); int clock_settime(clockid_t clock, const struct timespec *now); int clock_getres(clockid_t clock, struct timespec *res); DESCRIPTION The clock_gettime() function reads the given clock and writes its absolute value to now. The clock may be a value returned by clock_getcpuclockid(3) or pthread_getcpuclockid(3), or any of the following constants: CLOCK_REALTIME The Coordinated Universal Time (UTC) clock. Its absolute value is the time elapsed since Jan 1 1970 00:00:00 UTC (the Epoch). The clock normally advances continuously, though it may jump discontinuously if a process calls settimeofday(2) or clock_settime() (see below). CLOCK_MONOTONIC The monotonic clock. Its absolute value is meaningless. The clock begins at an undefined positive point and advances continuously. CLOCK_BOOTTIME The uptime clock. Its absolute value is the time elapsed since the system booted. The clock begins at zero and advances continuously. CLOCK_UPTIME The runtime clock. Its absolute value is the time elapsed since the system booted less any time the system was suspended. The clock begins at zero and advances while the system is not suspended. CLOCK_PROCESS_CPUTIME_ID The process CPU clock. Its absolute value begins at zero and advances while the calling process is running in user or kernel mode. CLOCK_THREAD_CPUTIME_ID The thread CPU clock. Its absolute value begins at zero and advances while the calling thread is running in user or kernel mode. The clock_settime() function sets the given clock to the absolute value now. Only the CLOCK_REALTIME clock may be set and only the superuser may set it. If the system securelevel(7) is 2 or greater, the time may only be advanced. This limitation is imposed to prevent a malicious superuser from setting arbitrary timestamps on files. The clock_getres() function retrieves the resolution of the given clock and writes it to res if res is non-NULL. The clock may be any of the clocks accepted by clock_gettime() as described earlier. The now and res arguments are timespec structures as defined in <sys/time.h>: struct timespec { time_t tv_sec; /* seconds */ long tv_nsec; /* and nanoseconds */ }; RETURN VALUES Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable errno is set to indicate the error. EXAMPLES Use the CLOCK_REALTIME clock to determine the time of day. Its absolute value can be passed to functions like gmtime(3) and strftime(3) to produce a human-readable string: char str[64]; struct timespec now; struct tm *tmbuf; clock_gettime(CLOCK_REALTIME, &now); tmbuf = gmtime(&now.tv_sec); if (tmbuf == NULL) err(1, "gmtime"); if (strftime(str, sizeof(str), "%a %b %e %T %Y %Z", tmbuf) == 0) err(1, "strftime"); printf("%s (%lld.%09ld seconds since the Epoch)\n", str, (long long)now.tv_sec, now.tv_nsec); Use the CLOCK_MONOTONIC clock to measure elapsed time. The timespecsub(3) function simplifies arithmetic operations on timespec structures: struct timespec elapsed, start, stop, timeout; timeout.tv_sec = 2; timeout.tv_nsec = 500000000; clock_gettime(CLOCK_MONOTONIC, &start); nanosleep(&timeout, NULL); clock_gettime(CLOCK_MONOTONIC, &stop); timespecsub(&stop, &start, &elapsed); printf("nanosleep: expected %lld.%09ld actual %lld.%09ld\n", (long long)timeout.tv_sec, timeout.tv_nsec, (long long)elapsed.tv_sec, elapsed.tv_nsec); Use the CLOCK_PROCESS_CPUTIME_ID or CLOCK_THREAD_CPUTIME_ID clocks to measure CPU time instead of elapsed time: struct timespec cputime, start, stop; volatile int i; clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &start); for (i = 0; i < INT_MAX; i++) continue; clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &stop); timespecsub(&stop, &start, &cputime); printf("CPU time: %lld.%09lds\n", (long long)cputime.tv_sec, cputime.tv_nsec); How much time has elapsed since the system booted? Has the system been suspended for any of that time? struct timespec diff, total, running; clock_gettime(CLOCK_BOOTTIME, &total); clock_gettime(CLOCK_UPTIME, &running); timespecsub(&total, &running, &diff); printf("Seconds since boot: %8lld.%09ld\n", (long long)total.tv_sec, total.tv_nsec); printf("Seconds suspended: %8lld.%09ld\n", (long long)diff.tv_sec, diff.tv_nsec); Set the CLOCK_REALTIME clock to Jan 1 00:00:00 2000 UTC: struct tm y2k; struct timespec ts; y2k.tm_year = 100; /* 2000 */ y2k.tm_mon = 0; /* January */ y2k.tm_mday = 1; y2k.tm_hour = 0; y2k.tm_min = 0; y2k.tm_sec = 0; ts.tv_nsec = 0; ts.tv_sec = timegm(&y2k); if (ts.tv_sec == -1) err(1, "timegm"); if (clock_settime(CLOCK_REALTIME, &ts) == -1) err(1, "clock_settime"); ERRORS clock_gettime(), clock_settime(), and clock_getres() will fail if: [EINVAL] The clock is invalid. [EFAULT] now or res reference invalid memory. In addition, clock_settime() may return the following errors: [EPERM] A user other than the superuser attempted to set the time. [EINVAL] The clock is not CLOCK_REALTIME. [EINVAL] now specifies a nanosecond value less than zero or greater than or equal to one billion. [EINVAL] now specifies a value outside the range of the given clock. SEE ALSO date(1), adjtime(2), getitimer(2), gettimeofday(2), clock_getcpuclockid(3), ctime(3), pthread_getcpuclockid(3), strftime(3), time(3), timespecadd(3), securelevel(7) STANDARDS The clock_gettime(), clock_settime(), and clock_getres() functions conform to IEEE Std 1003.1-2008 ("POSIX.1"). The CLOCK_BOOTTIME and CLOCK_UPTIME clocks are extensions to that specification. HISTORY The clock_gettime(), clock_settime(), and clock_getres() functions and the CLOCK_REALTIME clock first appeared in IEEE Std 1003.1b-1993 ("POSIX.1b") and were first available in OpenBSD 2.1. The CLOCK_MONOTONIC clock first appeared in IEEE Std 1003.1j-2000 ("POSIX.1j") and was first available in OpenBSD 3.4. The CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID clocks first appeared in IEEE Std 1003.1d-1999 ("POSIX.1d") and were first available in OpenBSD 5.4. The CLOCK_UPTIME clock first appeared in FreeBSD 7.0 and was first available in OpenBSD 5.5. The CLOCK_BOOTTIME clock first appeared in Linux 2.6.39 and was first available in OpenBSD 6.3. FreeBSD 14.1-RELEASE-p8 March 31, 2022 FreeBSD 14.1-RELEASE-p8