NTPFROB(8)

🎀 NAME 🎀

ntpfrob — frob the clock hardware 💅

So this is ntpfrob(8) from the NTPsec manual, and bestie, the entire NAME section is literally just "frob the clock hardware." That's it. That's the job. Iconic behaviour, honestly. 👑

---

✨ SYNOPSIS ✨

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

---

🦋 DESCRIPTION 🦋

ntpfrob frobs your local clock hardware. Like, that's the whole vibe. It collects several small diagnostic functions into one set, and which functions you actually get depends on your platform and on the underlying system calls. Some of these little guys used to be their own whole thing — portions of it formerly traveled as tickadj and some undocumented small utilities. Now they all hang out here together. Found family fr fr. 🫶

---

💅 COMMAND LINE OPTIONS 💅

• -a tick — Set the kernel variable tick to the value tick specifies. Yes, it's a tick setting a tick. We don't make the rules. 🎀
• -A — Display the kernel variable tick. The read-only sibling. 👀
• -b bump — Bump the clock by a specified number of microseconds. Shove it. Gently. In microseconds.
• -c — Compute and display clock jitter.
• -d — display values extracted via adjtimex(2).
• -D — display values extracted via adjtimex(2) forcibly including PPS. Yeah she's forcibly including it, no negotiations. 💀
• -e — Measure clock precision.
• -j — Generate a report in self-describing JSON. For the girlies who pipe things into jq. ✨
• -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 post analysis.
• -? — Print usage and exit.
• -h — Print usage and exit.
• -V — Print the version string and exit.

---

🍓 USAGE 🍓

Real talk: documentation for some of these functions is scanty; this is a problem inherited from ancient days along with their code. So if you suspect you may need to use them, reading the source code may be wise. And if you believe you understand the code in more detail than any of these descriptions — please, please explain it to the NTPsec maintainers. They would love you forever. 🥺

Normally this tool reports in an eyeball-friendly unstructured text format. With the -j option (where applicable) it reports JSON records instead. Note that the -j option should be given before any mode option. Order matters, bestie, don't come crying to me. 🎀

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 of them rely on the adjtimex(2) system call. This mode finishes by reporting the tick value and (if available) the tick adjustment value. Very "here's the receipt" of it all. 🧾

The -j option applies to this mode.

<p each>Tweaking your tick rate is almost never necessary on hardware new enough to have a fully POSIX.1-2001-conformant Unix. So like. Keep that in your pocket before you go changing things. 🫣</p>

🪩 Clock bump

Sometimes it is diagnostically interesting to perturb your clock to watch how ntpd responds and makes corrections. This option does that. You're basically poking the clock with a stick to see what it does. Chaos, but make it science. 🔬

🎧 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. Slay. 🌸

The -j option applies to this mode. With the -r option, write the raw, unsorted clock samples to standard output for post-analysis. And heads up: all but the last -j or -r option before the -c mode flag is ignored. So the others are just there for decoration, I guess. 🙈

📡 Pulse-per-second check

The -p option shows whether the PPS-API (RFC 2783 kernel PPS interface) finds PPS on a specified device. Like a little "hey, is the pulse pulsing?" wellness check for your hardware. 💖

🔬 Measure clock precision

The -e option measure the resolution of the system clock, watching how the current time changes as we read it repeatedly. Over and over and over. Obsessed with her consistency. ✨

The -j option applies to this mode.

---

🌈 EXIT STATUS 🌈

One of the following exit values will be returned:

• 0 (EXIT_SUCCESS) — Successful program execution. She did it, no notes, queen behaviour. 👑
• 1 (EXIT_FAILURE) — The operation failed or the command invocation was not valid. 😭 It's giving user error, lowkey.

---

And that's the whole page, bestie 🎀 — this one's from NTPsec, dated 2026-10-21, and it was a genuine pleasure to frob with you. Go forth and diagnostically perturb something. 💅✨