home | help
CLOCK_GETTIME(2)	       System Calls Manual		CLOCK_GETTIME(2)

NAME
     clock_gettime,  clock_settime,  clock_getres  -- get/set/calibrate date and
     time

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <time.h>

     int
     clock_gettime(clockid_t clock_id, struct timespec *tp);

     int
     clock_settime(clockid_t clock_id, const struct timespec *tp);

     int
     clock_getres(clockid_t clock_id, struct timespec *tp);

DESCRIPTION
     The clock_gettime() and clock_settime()  system  calls  allow  the  calling
     process  to retrieve or set the value used by a clock which is specified by
     clock_id.

     The clock_id argument can be one of five values:  CLOCK_REALTIME  for  time
     that increments as a wall clock should, CLOCK_MONOTONIC which increments in
     SI seconds, CLOCK_UPTIME which starts at zero when the kernel boots and in-
     crements  monotonically  in  SI  seconds  while  the  machine  is	running,
     CLOCK_VIRTUAL for time that increments only when the CPU is running in user
     mode on behalf of the calling process, or CLOCK_PROF for time  that  incre-
     ments when the CPU is running in user or kernel mode.

     The structure pointed to by tp is defined in <sys/timespec.h> as:

     struct timespec {
	     time_t  tv_sec;	     /* seconds */
	     long    tv_nsec;	     /* and nanoseconds */
     };

     Only  the super-user may set the time of day.  If the system securelevel is
     greater than 1 (see init(8)), the time may only be advanced.  This  limita-
     tion  is  imposed	to prevent a malicious super-user from setting arbitrary
     time stamps on files.  The system time can still be adjusted backwards  us-
     ing the adjtime(2) system call even when the system is secure.

     The  resolution  (granularity) of a clock is returned by the clock_getres()
     system call.  This value is placed in a (non-NULL) *tp.

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.

ERRORS
     The following error codes may be set in errno:

     [EINVAL]		The clock_id argument was not a valid value.

     [EFAULT]		The *tp argument address referenced invalid memory.

     [EPERM]		A user other than the super-user attempted  to	set  the
			time.

SEE ALSO
     date(1), adjtime(2), ctime(3), timed(8)

STANDARDS
     The  clock_gettime(), clock_settime(), and clock_getres() system calls con-
     form to IEEE Std 1003.1b-1993 ("POSIX.1").

FreeBSD 7.1			November 4, 2006		CLOCK_GETTIME(2)

home | help