summaryrefslogtreecommitdiff
path: root/ntpshmmon.xml
blob: 396f1ab69124785deb100898556668a1fd59068d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
This file is Copyright (c) 2010 by the GPSD project
BSD terms apply: see the file COPYING in the distribution root for details.
-->
<!DOCTYPE refentry PUBLIC
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id='ntpshmmon.1'>
<refentryinfo><date>25 Jan 2015</date></refentryinfo>
<refmeta>
<refentrytitle>ntpshmmon</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">The GPSD Project</refmiscinfo>
<refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>ntpshmmon</refname>
<refpurpose>capture samples from GPS or other ntpd refclock sources</refpurpose>
</refnamediv>
<refsynopsisdiv id='synopsis'>

<cmdsynopsis>
  <command>ntpshmmon</command>
      <arg choice='opt'>-h </arg>
      <arg choice='opt'>-n <replaceable>nsamples</replaceable></arg>
      <arg choice='opt'>-s </arg>
      <arg choice='opt'>-t <replaceable>seconds</replaceable></arg>
      <arg choice='opt'>-v </arg>
      <arg choice='opt'>-V </arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1 id='description'><title>DESCRIPTION</title>

<para>This program monitors the shared-memory segments updated by
<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
(and possibly other refclock sources) as a way of communicating with
ntpd, the Network Time Protocol daemon. It reads these in exactly the way an
ntpd instance does. It can be run concurrently with ntpd without
interfering with ntpd's normal operation.</para>

<para>This program runs forever, or until a termination option is
matched, or until interrupted, generating sample reports to standard
output.  Each line consists of whitespace-separated textual
fields.</para>

<para>Here is an example of the beginning of a report file:

<literallayout>
ntpshmmon version 1
#      Name   Seen@                Clock                Real               L Prec
sample NTP2 1424926256.443030206 1424926256.115869233 1424926256.000000000 0  -1
sample NTP3 1424926256.443060517 1424926255.995430821 1424926256.000000000 0 -20
sample NTP3 1424926256.995747347 1424926256.995422728 1424926257.000000000 0 -20
sample NTP2 1424926257.112433572 1424926257.111936726 1424926257.000000000 0  -1
sample NTP3 1424926257.996221153 1424926257.995410232 1424926258.000000000 0 -20
sample NTP2 1424926258.107769409 1424926258.107451006 1424926258.000000000 0  -1
sample NTP3 1424926258.995647636 1424926258.995406476 1424926259.000000000 0 -20
</literallayout></para>

<para>The output always begins with a header line expressing the
version of the output format; the version line begins with "ntpshmmon
version" and is followed by a numeric version field.</para>

<para>The remainder of the file is either commments or sample lines. A
comment line begins with a # and should ignored by programs that
interpret this format. This program never generates such lines
itself.</para>

<para>The fields of a sample line are as follows:

<orderedlist>
<listitem><para>The keyword "sample"</para></listitem>

<listitem><para>The NTP unit from which it was collected.</para></listitem>

<listitem><para>Collection time of day, seconds.</para></listitem>

<listitem><para>Receiver time of day, seconds.</para></listitem>

<listitem><para>Clock time of day, seconds.</para></listitem>

<listitem><para>Leap-second notification status.</para></listitem>

<listitem><para>Source precision (log(2) of source jitter).</para></listitem>
</orderedlist>
</para>

<para>In these fields, "clock time" is the high-precision time
measured by the source and "receiver time" is Unix UTC time at the
receiver. It is normal for the seconds part of receiver time to
coincide with the seconds part of collection time and for the
nanoseconds part of receiver time to be zero.</para>

<variablelist>
<varlistentry>
<term>-v</term>
<listitem>
<para>Enable verbose status messages.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-c</term>
<listitem>
<para>Device poll interval in fractional seconds - defaults to 1.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-n</term>
<listitem>
<para>Set maximum number of samples to collect.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-s</term>
<listitem>
<para>Remove all SHM segments used by GPSD. This
option will normally only be of interest to GPSD developers.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-t</term>
<listitem>
<para>Set maximum time to collect samples in seconds.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-h</term>
<listitem>
<para>Display program usage and exit.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-V</term>
<listitem>
<para>Display program version and exit.</para>
</listitem>
</varlistentry>
</variablelist>

</refsect1>

<refsect1 id='see_also'><title>SEE ALSO</title>
<para>
<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsdctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>
</refsect1>

<refsect1 id='maintainer'><title>AUTHOR</title>

<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para>
</refsect1>
</refentry>