---
name: "clock_gettime"
section: "3"
platform: "macos"
package: "Libc"
version: "1752.120.2"
release: "macOS 26.5"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/clock_gettime/3"
---

# clock\_gettime(3)

get/set date and time

## NAME

**clock\_gettime**, **clock\_settime**, **clock\_getres**, **clock\_gettime\_nsec\_np** – get/set date and time

## 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*);

*uint64\_t*\

**clock\_gettime\_nsec\_np**(*clockid\_t clock\_id*);

## 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 one of 8 predefined values:

- CLOCK\_REALTIME

  the system's real time (i.e. wall time) clock, expressed as the amount of time since the Epoch. This is the same as the value returned by [gettimeofday(2)](/gettimeofday/2.md).

- CLOCK\_MONOTONIC

  clock that increments monotonically, tracking the time since an arbitrary point, and will continue to increment while the system is asleep.

- CLOCK\_MONOTONIC\_RAW

  clock that increments monotonically, tracking the time since an arbitrary point like CLOCK\_MONOTONIC.  However, this clock is unaffected by frequency or time adjustments.  It should not be compared to other system time sources.

- CLOCK\_MONOTONIC\_RAW\_APPROX

  like CLOCK\_MONOTONIC\_RAW, but reads a value cached by the system at context switch.  This can be read faster, but at a loss of accuracy as it may return values that are milliseconds old.

- CLOCK\_UPTIME\_RAW

  clock that increments monotonically, in the same manner as CLOCK\_MONOTONIC\_RAW, but that does not increment while the system is asleep. The returned value is identical to the result of **mach\_absolute\_time**() after the appropriate mach\_timebase conversion is applied.

- CLOCK\_UPTIME\_RAW\_APPROX

  like CLOCK\_UPTIME\_RAW, but reads a value cached by the system at context switch.  This can be read faster, but at a loss of accuracy as it may return values that are milliseconds old.

- CLOCK\_PROCESS\_CPUTIME\_ID

  clock that tracks the amount of CPU (in user- or kernel-mode) used by the calling process.

- CLOCK\_THREAD\_CPUTIME\_ID

  clock that tracks the amount of CPU (in user- or kernel-mode) used by the calling thread.

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.

The resolution of a clock is returned by the **clock\_getres**() call. This value is placed in a (non-null) *\*tp*. This value may be smaller than the actual precision of the underlying clock, but represents a lower bound on the resolution.

As a non-portable extension, the **clock\_gettime\_nsec\_np**() function will return the clock value in 64-bit nanoseconds.

## RETURN VALUES

A 0 return value indicates that the call succeeded. A -1 return value indicates an error occurred, and in this case an error code is stored into the global variable *errno*. For **clock\_gettime\_nsec\_np**() a return value of non-0 indicates success.  A 0 return value indicates an error occurred and an error code is stored in *errno*.

## ERRORS

**clock\_gettime**(), **clock\_settime**(), **clock\_getres**(), and **clock\_gettime\_nsec\_np**() 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)](/date/1.md), [getitimer(2)](/getitimer/2.md), [gettimeofday(2)](/gettimeofday/2.md),

## HISTORY

These functions first appeared in Mac OSX 10.12

## STANDARDS

The **clock\_gettime**(), **clock\_settime**(), and **clock\_getres**() system calls conform to IEEE Std 1003.1b-1993 (“POSIX.1b”). **clock\_gettime\_nsec\_np**() is a non-portable Darwin extension. The clock IDs *CLOCK\_MONOTONIC\_RAW* and *CLOCK\_UPTIME\_RAW* are extensions to the POSIX interface.