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 .P
  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 .P
  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 .P
  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 .P
  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 .P
  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 ATTRIBUTES
  99 For an explanation of the terms used in this section, see
 100 .BR attributes (7).
 101 .TS
 102 allbox;
 103 lbx lb lb
 104 l l l.
 105 Interface       Attribute       Value
 106 T{
 107 .na
 108 .nh
 109 .BR ntp_gettime (),
 110 .BR ntp_gettimex ()
 111 T}      Thread safety   MT-Safe
 112 .TE
 113 .SH STANDARDS
 114 .TP
 115 .BR ntp_gettime ()
 116 NTP Kernel Application Program Interface.
 117 .TP
 118 .BR ntp_gettimex ()
 119 GNU.
 120 .SH HISTORY
 121 .TP
 122 .BR ntp_gettime ()
 123 glibc 2.1.
 124 .TP
 125 .BR ntp_gettimex ()
 126 glibc 2.12.
 127 .SH SEE ALSO
 128 .BR adjtimex (2),
 129 .BR ntp_adjtime (3),
 130 .BR time (7)
 131 .P
 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