man3/ntp_gettime.3

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