---
name: "clock_settime"
section: "2freebsd"
platform: "linux"
package: "freebsd-manpages"
version: "12.2-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/clock_getres/2freebsd"
---

# clock\_settime(2freebsd)

get/set/calibrate date and time

Part of [clock\_getres(2freebsd)](/clock_getres/2freebsd.md).

## 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 a value obtained from [clock\_getcpuclockid(3)](/clock_getcpuclockid/3.md) or [pthread\_getcpuclockid(3)](/pthread_getcpuclockid/3.md) as well as the following values:

- CLOCK\_REALTIME

  - CLOCK\_REALTIME\_PRECISE

  - CLOCK\_REALTIME\_FAST

  Increments as a wall clock should.

- CLOCK\_MONOTONIC

  - CLOCK\_MONOTONIC\_PRECISE

  - CLOCK\_MONOTONIC\_FAST

  Increments in SI seconds.

- CLOCK\_UPTIME

  - CLOCK\_UPTIME\_PRECISE

  - CLOCK\_UPTIME\_FAST

  Starts at zero when the kernel boots and increments monotonically in SI seconds while the machine is running.

- CLOCK\_VIRTUAL

  Increments only when the CPU is running in user mode on behalf of the calling process.

- CLOCK\_PROF

  Increments when the CPU is running in user or kernel mode.

- CLOCK\_SECOND

  Returns the current second without performing a full time counter query, using an in-kernel cached value of the current second.

- CLOCK\_PROCESS\_CPUTIME\_ID

  Returns the execution time of the calling process.

- CLOCK\_THREAD\_CPUTIME\_ID

  Returns the execution time of the calling thread.

The clock IDs *CLOCK\_REALTIME\_FAST*, *CLOCK\_MONOTONIC\_FAST*, *CLOCK\_UPTIME\_FAST* are analogs of corresponding IDs without \_FAST suffix but do not perform a full time counter query, so their accuracy is one timer tick. Similarly, *CLOCK\_REALTIME\_PRECISE*, *CLOCK\_MONOTONIC\_PRECISE*, *CLOCK\_UPTIME\_PRECISE* are used to get the most exact value as possible, at the expense of execution time.

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, using only *CLOCK\_REALTIME*. If the system securelevel is greater than 1 (see [init(8)](/init/8.md)), the time may only be advanced. This limitation is imposed to prevent a malicious super-user from setting arbitrary time stamps on files. The system time can still be adjusted backwards using the [adjtime(2)](/adjtime/2.md) 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

The **clock\_gettime()** function returns the value 0 if successful; 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* or *timespec* argument was not a valid value.

- \[EPERM\]

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

## SEE ALSO

[date(1)](/date/1.md), [adjtime(2)](/adjtime/2.md), [clock\_getcpuclockid(3)](/clock_getcpuclockid/3.md), [ctime(3)](/ctime/3.md), [pthread\_getcpuclockid(3)](/pthread_getcpuclockid/3.md), timed(8)

## STANDARDS

The **clock\_gettime**(), **clock\_settime**(), and **clock\_getres**() system calls conform to IEEE Std 1003.1b-1993 (“POSIX.1b”). The clock IDs *CLOCK\_REALTIME\_FAST*, *CLOCK\_REALTIME\_PRECISE*, *CLOCK\_MONOTONIC\_FAST*, *CLOCK\_MONOTONIC\_PRECISE*, *CLOCK\_UPTIME*, *CLOCK\_UPTIME\_FAST*, *CLOCK\_UPTIME\_PRECISE*, *CLOCK\_SECOND* are FreeBSD extensions to the POSIX interface.

## HISTORY

The **clock\_gettime**(), **clock\_settime**(), and **clock\_getres**() system calls first appeared in FreeBSD 3.0.