Kernel+LibC: Add adjtime(2)

Most systems (Linux, OpenBSD) adjust 0.5 ms per second, or 0.5 us per
1 ms tick. That is, the clock is sped up or slowed down by at most
0.05%.  This means adjusting the clock by 1 s takes 2000 s, and the
clock an be adjusted by at most 1.8 s per hour.

FreeBSD adjusts 5 ms per second if the remaining time adjustment is
>= 1 s (0.5%) , else it adjusts by 0.5 ms as well. This allows adjusting
by (almost) 18 s per hour.

Since Serenity OS can lose more than 22 s per hour (#3429), this
picks an adjustment rate up to 1% for now. This allows us to
adjust up to 36s per hour, which should be sufficient to adjust
the clock fast enough to keep up with how much time the clock
currently loses. Once we have a fancier NTP implementation that can
adjust tick rate in addition to offset, we can think about reducing
this.

adjtime is a bit old-school and most current POSIX-y OSs instead
implement adjtimex/ntp_adjtime, but a) we have to start somewhere
b) ntp_adjtime() is a fairly gnarly API. OpenBSD's adjfreq looks
like it might provide similar functionality with a nicer API. But
before worrying about all this, it's probably a good idea to get
to a place where the kernel APIs are (barely) good enough so that
we can write an ntp service, and once we have that we should write
a way to automatically evaluate how well it keeps the time adjusted,
and only then should we add improvements ot the adjustment mechanism.

1 files changed, 33 insertions, 0 deletions

diff --git a/Base/usr/share/man/man2/adjtime.md b/Base/usr/share/man/man2/adjtime.md
new file mode 100644
index 0000000000..29b315426a
--- /dev/null
+++ b/Base/usr/share/man/man2/adjtime.md
@@ -0,0 +1,33 @@
+## Name
+
+adjtime - gradually adjust system clock
+
+## Synopsis
+
+```**c++
+#include <sys/time.h>
+
+int adjtime(const struct timeval* delta, struct timeval* old_delta);
+```
+
+## Description
+
+`adjtime()` gradually increments the system time by `delta`, if it is non-null.
+
+Serenity OS slows down or speeds up the system clock by at most 1%, so adjusting the time by N seconds takes 100 * n seconds to complete.
+
+Calling `settimeofday()` or `clock_settime()` cancels in-progress time adjustments done by `adjtime`.
+
+If `delta` is not null, `adjtime` can only called by the superuser.
+
+If `old_delta` is not null, it returns the currently remaining time adjustment. Querying the remaining time adjustment does not need special permissions.
+
+## Pledge
+
+In pledged programs, the `settime` promise is required when `delta` is not null.
+
+## Errors
+
+* `EFAULT`: `delta` and/or `old_delta` are not null and not in readable memory.
+* `EINVAL`: `delta` is not null and has a `tv_nsec` field that's less than 0 or larger or equal to `10^6`. Negative deltas should have a negative `tv_sec` field but a `tv_nsec` that's larger or equal zero. For example, a delta of -0.5 s is represented by `{-1, 500'000}`.
+* `EPERM`: `delta` is not null but geteuid() is not 0.