---
name: "ntp_gettime"
section: "2"
platform: "linux"
package: "freebsd-manpages"
version: "6.0-5"
release: "Debian 4.0 (Etch)"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/ntp_gettime"
---

# ntp\_gettime(2)

NTP user application interface

## NAME

**ntp\_gettime** – NTP user application interface

## SYNOPSIS

**#include \<sys/timex.h\>**

*int*\

**ntp\_gettime**(*struct ntptimeval \*ntv*);

## DESCRIPTION

The time returned by **ntp\_gettime**() is in a *timespec* structure, but may be in either microsecond (seconds and microseconds) or nanosecond (seconds and nanoseconds) format. The particular format in use is determined by the STA\_NANO bit of the status word returned by the **ntp\_adjtime**() system call. **ntp\_gettime**() has as argument a pointer to the *ntptimeval* structure with the following members:

```
struct ntptimeval {
	struct timespec time;	/* current time (ns) (ro) */
	long maxerror;		/* maximum error (us) (ro) */
	long esterror;		/* estimated error (us) (ro) */
	long tai;		/* TAI-UTC offset */
	int time_state;		/* time status */
};
```

These are understood as:

- *time*

  Current time (read-only).

- *maxerror*

  Maximum error in microseconds (read-only).

- *esterror*

  Estimated error in microseconds (read-only).

- *tai*

  Offset in seconds between the TAI and UTC time scales. This offset is published twice a year and is an integral number of seconds between TAI (which does not have leap seconds) and UTC (which does). [ntpd(8)](/ntpd/8.md) or some other agent maintains this value. A value of 0 means unknown. As of the date of the manual page, the offset is 32 seconds.

- *time\_state*

  Current time status.

## RETURN VALUES

The **ntp\_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.

Possible states of the clock are:

- TIME\_OK

  Everything okay, no leap second warning.

- TIME\_INS

  Positive leap second warning. At the end of the day, an additional second will be inserted after 23:59:59.

- TIME\_DEL

  Negative leap second warning. At the end of the day, 23:59:59 is skipped.

- TIME\_OOP

  Leap second in progress.

- TIME\_WAIT

  Leap second has occurred.

- TIME\_ERROR

  Clock not synchronized.

## SEE ALSO

[ntp\_adjtime(2)](/ntp_adjtime/2.md), [ntpd(8)](/ntpd/8.md)

- *http://www.bipm.fr/enus/5\_Scientific/c\_time/time\_1.html*

  - *http://www.boulder.nist.gov/timefreq/general/faq.htm*

  - *ftp://time.nist.gov/pub/leap-seconds.list*

  ## AUTHORS

This manual page was written by Tom Rhodes ⟨trhodes@FreeBSD.org⟩.