man3/ntp_gettime.3

   1 .\" Copyright (c) 2016 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH NTP_GETTIME 3 2021-03-22 "Linux" "Linux Programmer's Manual"
   6 .SH NAME
   7 ntp_gettime, ntp_gettimex  \- get time parameters (NTP daemon interface)
   8 .SH LIBRARY
   9 Standard C library
  10 .RI ( libc ", " \-lc )
  11 .SH SYNOPSIS
  12 .nf
  13 .B #include <sys/timex.h>
  14 .PP
  15 .BI "int ntp_gettime(struct ntptimeval *" ntv );
  16 .BI "int ntp_gettimex(struct ntptimeval *" ntv );
  17 .fi
  18 .SH DESCRIPTION
  19 Both of these APIs return information to the caller via the
  20 .I ntv
  21 argument, a structure of the following type:
  22 .PP
  23 .in +4n
  24 .EX
  25 struct ntptimeval {
  26     struct timeval time;    /* Current time */
  27     long maxerror;          /* Maximum error */
  28     long esterror;          /* Estimated error */
  29     long tai;               /* TAI offset */
  30
  31     /* Further padding bytes allowing for future expansion */
  32 };
  33 .EE
  34 .in
  35 .PP
  36 The fields of this structure are as follows:
  37 .TP
  38 .I time
  39 The current time, expressed as a
  40 .I timeval
  41 structure:
  42 .IP
  43 .in +4n
  44 .EX
  45 struct timeval {
  46     time_t      tv_sec;   /* Seconds since the Epoch */
  47     suseconds_t tv_usec;  /* Microseconds */
  48 };
  49 .EE
  50 .in
  51 .TP
  52 .I maxerror
  53 Maximum error, in microseconds.
  54 This value can be initialized by
  55 .BR ntp_adjtime (3),
  56 and is increased periodically (on Linux: each second),
  57 but is clamped to an upper limit (the kernel constant
  58 .BR NTP_PHASE_MAX ,
  59 with a value of 16,000).
  60 .TP
  61 .I esterror
  62 Estimated error, in microseconds.
  63 This value can be set via
  64 .BR ntp_adjtime (3)
  65 to contain an estimate of the difference between the system clock
  66 and the true time.
  67 This value is not used inside the kernel.
  68 .TP
  69 .I tai
  70 TAI (Atomic International Time) offset.
  71 .PP
  72 .BR ntp_gettime ()
  73 returns an
  74 .I ntptimeval
  75 structure in which the
  76 .IR time ,
  77 .IR maxerror ,
  78 and
  79 .IR esterror
  80 fields are filled in.
  81 .PP
  82 .BR ntp_gettimex ()
  83 performs the same task as
  84 .BR ntp_gettime (),
  85 but also returns information in the
  86 .I tai
  87 field.
  88 .SH RETURN VALUE
  89 The return values for
  90 .BR ntp_gettime ()
  91 and
  92 .BR ntp_gettimex ()
  93 are as for
  94 .BR adjtimex (2).
  95 Given a correct pointer argument, these functions always succeed.
  96 .\" FIXME . the info page incorrectly describes the return values.
  97 .SH VERSIONS
  98 The
  99 .BR ntp_gettime ()
 100 function is available since glibc 2.1.
 101 The
 102 .BR ntp_gettimex ()
 103 function is available since glibc 2.12.
 104 .SH ATTRIBUTES
 105 For an explanation of the terms used in this section, see
 106 .BR attributes (7).
 107 .ad l
 108 .nh
 109 .TS
 110 allbox;
 111 lbx lb lb
 112 l l l.
 113 Interface       Attribute       Value
 114 T{
 115 .BR ntp_gettime (),
 116 .BR ntp_gettimex ()
 117 T}      Thread safety   MT-Safe
 118 .TE
 119 .hy
 120 .ad
 121 .sp 1
 122 .SH CONFORMING TO
 123 .BR ntp_gettime ()
 124 is described in the NTP Kernel Application Program Interface.
 125 .BR ntp_gettimex ()
 126 is a GNU extension.
 127 .SH SEE ALSO
 128 .BR adjtimex (2),
 129 .BR ntp_adjtime (3),
 130 .BR time (7)
 131 .PP
 132 .ad l
 133 .UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm
 134 NTP "Kernel Application Program Interface"
 135 .UE