PPSCHECK(8)

💖 PPSCHECK(8) — the ppscheck manual page, bestie edition 💖

okay so this is a page from the GPSD Documentation set, and it's all about a tiny little detective called ppscheck. pull up a chair. 🫶

---

✨ NAME ✨

ppscheck — a whole tool whose entire job is checking a serial port for PPS 💅

---

✨ SYNOPSIS ✨

ppscheck [-?] [--help] [-p] [--pps] [--version] [-h] [-V]

ppscheck [-m] device

---

✨ DESCRIPTION ✨

so ppscheck sits there watching a serial port you picked, waiting for transitions that might be PPS. like, it's stalking the handshake lines CD, CTS, DSR, and RI, and it does that by running ioctl(...., TIOCMIWAIT, ...) in a loop, forever, like a girl refreshing her messages. 🔁 the second it catches a state change, it spits out a timestamped line dumping the state of the handshake signals. extremely useful if you're trying to figure out whether a device is even emitting PPS, no cap.

ngl, ppscheck can run as a normal user — but that user must have permissions to read the target device. running under sudo may, or may not, work. running as root will always work. 👑

to check the first serial port, do this:

# ppscheck /dev/ttyS0

and here's the side effect that's lowkey iconic: ppscheck will try to create the matching /dev/ppsX by setting the tty line discipline (ldisc) to N_PPS (18). after that you should have a device /dev/pps0. ⚠️ but heads up bestie — not all serial devices support ldisc N_PPS. it's giving "some of y'all are not gonna make it".

now you can use ppscheck to see if the KPPS (RFC 2783) interface is actually working:

# ppscheck /dev/pps0

ppscheck is not meant for routine use, okay? it's a diagnostic tool, main character energy only in emergencies. once you've verified a particular device can output PPS signals, you will never need to use it again on that device. periodt. 🎀

---

✨ OPTIONS ✨

the program accepts the following options:

• -?, -h, --help — print the help message, then exit. 🦋
• -m, --match — find the PPS device that matches device.
• -p, --pps — print active PPS devices, then exit.
• -V, --version — dump the version, then exit.
• -x SEC, --seconds SEC — exit after a delay of SEC seconds.

---

✨ ARGUMENTS ✨

the device argument should be the pathname of a device. like /dev/ttyS0 or /dev/pps0. that's the one that gets monitored. 👀

for a tty device, each output line is the second and nanosecond parts of a timestamp, followed by the names of the handshake signals then asserted. off transitions may generate lines with no signals asserted — that's normal, don't panic. 🫶

for a pps device, each output line will contain the assert and clear times last detected by KPPS.

if you don't see output within a second, use cgps, xgps, or some other equivalent tool to check that your device has a satellite lock and is getting 3D fixes before you give up on the possibility of PPS. like, don't just assume it's broken, check first. 🛰️

also — check your cable. cheap DB9 to DB9 cables, such as those issued with UPSes, often carry TXD/RXD/GND only, omitting handshake lines such as CD. suspect this especially if the cable jacket looks too skinny to hold more than three leads! 💀

and finally: most GPS that have built in USB do not support PPS. when in doubt, contact the vendor for confirmation that your device does supply PPS. fr fr, just ask them.

---

✨ RETURN VALUES ✨

• 0 — OK ✨
• 1 — if the device could not be opened, or some other failure 😭

---

✨ SEE ALSO ✨

cgps(1), xgps(1), gpsd(8) — go read those too, bestie 🌸

---

✨ 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 💜

---

okay that's the whole page!! this is from GPSD, Version 3.27.5, dated 2025-11-04, and honestly? iconic of it. go check your ports bestie, ily, bye!! 👑✨🦋