Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 abso-
     lute value	to now.	 The clock may be a value returned by
     clock_getcpuclockid(3) or pthread_getcpuclockid(3), or any	of the follow-
     ing constants:

     CLOCK_REALTIME   The Coordinated Universal	Time (UTC) clock.  Its abso-
		      lute value is the	time elapsed since Jan 1 1970 00:00:00
		      UTC (the Epoch).	The clock normally advances continu-
		      ously, 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 ad-
		      vances 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	pro-
     duce 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	con-
     form to IEEE Std 1003.1-2008 ("POSIX.1").

     The CLOCK_BOOTTIME	and CLOCK_UPTIME clocks	are extensions to that speci-
     fication.

HISTORY
     The clock_gettime(), clock_settime(), and clock_getres() functions	and
     the CLOCK_REALTIME	clock first appeared in	IEEE Std 1003.1b-1993
     ("POSIX.1") 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 ap-
     peared 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	avail-
     able in OpenBSD 5.5.

     The CLOCK_BOOTTIME	clock first appeared in	Linux 2.6.39 and was first
     available in OpenBSD 6.3.

FreeBSD	13.0		       October 25, 2020			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | ERRORS | SEE ALSO | STANDARDS | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=clock_gettime&sektion=2&manpath=OpenBSD+6.9>

home | help