// This is the body of the manual page for ntpfrob.
// It's included in two places: once for the docs/ HTML
// tree, and once to make an individual man page.

[[synop]]
== Synopsis ==

+ntpfrob+ [+-A+] [+-b+ 'bump'] [+-a+ 'tick'] [+-p+ 'ppsdev'] [+-c+] [+-e+] [+-r+] [+-?+] [+-h+]

[[descr]]
== Description ==

The ntpfrob program frobs the local clock hardware.  It collects
several small diagnostic functions into a set that will differ
depending on your platform and underlying system calls.  Portions of
it formerly traveled as +tickadj+ and some undocumented small
utilities.

[[cmd]]
== Command Line Options ==

+-a+ 'tick'::
  Set the kernel variable +tick+ to the value _tick_ specifies.
+-A+::
  Display the kernel variable +tick+.
+-b+ 'bump'::
  Bump the clock by a specified number of microseconds.
+-c+::
  Compute and display clock jitter.
+-e+::
  Measure clock precision.
+-j+::
  Report in self-describing JSON.
+-p+ 'ppsdev'::
  Look for PPS pulses on a specified device
+-r+::
  Raw mode.  Only applies to the jitter mode, and means the raw
  clock samples should be emitted to stdout for postanalysis.
+-?+::
  Print usage and exit.
+-h+::
  Print usage and exit.

[[usage]]
== Usage ==

Documentation for some of these functions is scanty; this is a problem
inherited from ancient days along with their code. If you suspect you
may need to use them, reading the source code may be wise. If you
believe you understand the code in more detail than any of these
descriptions, please explain it to the NTPsec maintainers.

Normally this tool reports in an eyeball-friendly unstructured text
format. With the -j option (where applicable) it reports JSON records.
Note that the -j option should be given before any mode option.

The reporting formats of this tool should be considered unstable;
they may change as diagnostics are added or improved.  JSON
reports will be kept forward-compatible through changes.

=== Clock tick adjustment ===

The -A function reads your clock's tick rate in microseconds.  The -a
function sets it. Both rely on the adjtimex(2) system call.  This
mode finishes by reporting the tick value and (if available) the
tick adjustment value.

The -j option is applicable to this mode.

Tweaking your tick rate is almost never necessary on hardware new
enough to have a fully POSIX.1-2001-conformant Unix.

=== Clock bump ===

Sometimes it is diagnostically interesting to perturb your clock in
order to watch how ntpd responds and makes corrections. This
option does that.

=== Clock jitter measurement ===

The -c option can be used to determine the timing jitter due to the
operating system in a gettimeofday() call.  For most systems the
dominant contribution to the jitter budget is the period of the
hardware interrupt, usually in the range between 10 us and 1 ms. For
those systems with microsecond counters the jitter is dominated
only by the operating system.

The -j option is applicable to this mode.  With the -r option, write
the raw unsorted clock samples to standard output for post-analysis.
All but the last -j or -r option before the -c mode flag is ignored.

=== Pulse-per-second check ===

The -p option shows whether the  PPS-API (RFC 2783 kernel
PPS interface) finds PPS on a specified device.

=== Measure clock precision ===

The -e option measure the resolution of the system clock, watching how
the current time changes as we read it repeatedly.

The -j option is applicable to this mode.

// end
