unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

CLOCK_GETTIME(2)            BSD System Calls Manual           CLOCK_GETTIME(2)

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

SYNOPSIS
     #include <&lt;time.h>&gt;

     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() functions allow the calling
     process to retrieve or set the value used by a clock which is specified
     by clock_id.

     clock_id can be a value from clock_getcpuclockid(3) or
     pthread_getcpuclockid(3) or one of five predefined values:

     CLOCK_REALTIME   time that increments as a wall clock should

     CLOCK_PROCESS_CPUTIME_ID
                      time that increments when the CPU is running in user or
                      kernel mode on behalf of the calling process

     CLOCK_THREAD_CPUTIME_ID
                      time that increments when the CPU is running in user or
                      kernel mode on behalf of the calling thread

     CLOCK_MONOTONIC  time that increments as a wall clock should but whose
                      absolute value is meaningless and cannot jump, providing
                      accurate realtime interval measurement, even across sus-
                      pend and resume

     CLOCK_UPTIME     time whose absolute value is the time the system has
                      been running and not suspended, providing accurate
                      uptime measurement, both absolute and interval

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

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

     Only the CLOCK_REALTIME clock can be set, and only the superuser may do
     so.  If the system securelevel is greater than 1 (see init(8)), the time
     may only be advanced.  This limitation is imposed to prevent a malicious
     superuser from setting arbitrary time stamps on files.  The system time
     can still be adjusted backwards using the adjtime(2) system call even
     when the system is secure.

     The resolution (granularity) of a clock is returned by the clock_getres()
     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
     clock_gettime(), clock_settime(), and clock_getres() will fail if:

     [EINVAL]           clock_id is not a valid value.

     [EFAULT]           The tp argument address referenced invalid memory.

     In addition, clock_settime() may return the following errors:

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

     [EINVAL]           clock_id specifies a clock that isn't settable, tp
                        specifies a nanosecond value less than zero or greater
                        than 1000 million, or a value outside the range of the
                        specified clock.

SEE ALSO
     date(1), adjtime(2), getitimer(2), gettimeofday(2),
     clock_getcpuclockid(3), ctime(3), pthread_getcpuclockid(3)

STANDARDS
     The clock_getres(), clock_gettime(), and clock_settime() functions con-
     form to IEEE Std 1003.1-2008 (``POSIX.1'').

     The CLOCK_UPTIME clock is an extension to that.

HISTORY
     The CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID clocks appeared
     in OpenBSD 5.4.  The CLOCK_UPTIME clock first appeared in FreeBSD 7.0 and
     was added to OpenBSD in OpenBSD 5.5.

BSD                             March 27, 2017                             BSD