NTPSHMMON(1)

💖 NTPSHMMON(1) 💖

okay bestie, welcome to the ntpshmmon page, part of the GPSD Documentation era. she's giving ✨ time-monitoring icon ✨ and honestly? obsessed.

---

🌸 NAME 🌸

ntpshmmon — capture samples from gpsd or other ntpd refclock sources 🫶

---

✨ SYNOPSIS ✨

ntpshmmon [OPTIONS]

ntpshmmon -h

ntpshmmon -V

---

🦋 DESCRIPTION 🦋

okay so, this program monitors the shared-memory segments that gpsd 8 updates, and possibly other refclock sources too. it's basically how they gossip with ntpd, the Network Time Protocol daemon 💅 and listen — ntpshmmon reads these segments in exactly the way an ntpd instance does. so you can run it right alongside ntpd with zero drama, no interfering with ntpd's normal operation. the way that works? iconic.

heads up tho: ntpshmmon needs root privileges to access the root-only NTP0 and NTP1. if you're running as a normal user you only get access to NTP2 and NTP3. cause loss of functionality. 😭

this program runs forever, or until a termination option is matched, or until it gets interrupted, generating sample reports to standard output. every line is just whitespace-separated textual fields. no cap.

here's an example of the beginning of a report file:

ntpshmmon version 3.18
#      Name   Seen@                Clock                Real               L Pre
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

the output always kicks off with a header line expressing the version of the output format — that version line starts with "ntpshmmon version" and then a numeric version field follows it. slay.

the rest of the file is either comments or sample lines. a comment line begins with a # and programs that interpret this format should just ignore it, fr fr 🙈

the fields of a sample line are as follows:

1. the keyword "sample"
2. the NTP unit from which it was collected.
3. collection time of day, seconds.
4. receiver time of day, seconds.
5. clock time of day, seconds.
6. leap-second notification status.
7. source precision (log(2) of source jitter).

in these fields, "clock time" is the high-precision system clock time measured by the source, and "receiver time" comes from the receiver. both times are in UTC 🕰️ and it's totally 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.

if you use the -o option, the "Seen@" column gets swapped out for the "Offset" column. the "Offset" is the difference between "Clock" and "Real" times. periodt.

---

🎀 OPTIONS 🎀

• -?, -h, --help — display program usage and exit.
• -n COUNT, --count COUNT — set the maximum number of samples to collect to COUNT.
• -o, --offset — replace the "Seen@" column with the "Offset" column. the "Offset" is the difference between "Clock" and "Real" times.
• -s, --rmshm — remove all SHM segments used by GPSD. this option will normally only be of interest to GPSD developers, iykyk.
• -t SECONDS, --seconds SECONDS — set the maximum time to collect samples in seconds to SECONDS.
• -v, --verbose — enable verbose status messages.
• -V, --version — display program version and exit.

---

🌈 RETURN VALUES 🌈

• 0 — on success 🥳
• 1 — on failure 💀

---

👑 SEE ALSO 👑

gpsd(8), gps(1)

---

🧚 RESOURCES 🧚

Project web site: https://gpsd.io/

---

💜 COPYING 💜

This file is Copyright 2013 by the GPSD project SPDX-License-Identifier: BSD-2-clause

---

⭐ AUTHOR ⭐

Eric S. Raymond

---

and that's the whole page bestie 💅 GPSD, Version 3.27.5, dated 2025-11-04 — thanks for reading, love u, bye!! 🫶💖✨