[PATCH v1] man/man2/adjtimex.2: Add include, macro and error for clock_adjtime

[Georg Sauthoff <mail@gms.tf>]

GNU libc declares clock_adjtime() when including time.h, and not when
just sys/timex.h is included, iff support for GNU features is requested.

Verification:

    $ for i in BLAH _GNU_SOURCE; do for j in sys/timex.h time.h; do echo -n "Testing $i and $j ... "; echo -e '#define '"$i"'\n#include <'"$j"'>\nvoid f(){clock_adjtime;}' | gcc  -xc - -o /dev/null -c 2>/dev/null && echo OK || echo FAIL; done; done
    Testing BLAH and sys/timex.h ... FAIL
    Testing BLAH and time.h ... FAIL
    Testing _GNU_SOURCE and sys/timex.h ... FAIL
    Testing _GNU_SOURCE and time.h ... OK

(Test output is from a Fedora 43 system)

The ERANGE error can be verified either via trying to adjust the
frequency of a PHC by a value that is outside of [-X,X],
where X=`cat /sys/class/ptp/ptpX/max_adjustment`,
or via checking the kernel source code:

<https://elixir.bootlin.com/linux/v7.2.2/source/drivers/ptp/ptp_clock.c#L164>

Signed-off-by: Georg Sauthoff <mail@gms.tf>
---
 man/man2/adjtimex.2 | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/man/man2/adjtimex.2 b/man/man2/adjtimex.2
index f12d9413e..528fd3a6f 100644
--- a/man/man2/adjtimex.2
+++ b/man/man2/adjtimex.2
@@ -17,9 +17,21 @@ .SH SYNOPSIS
 .P
 .BI "int adjtimex(struct timex *" "buf" );
 .P
-.BI "int clock_adjtime(clockid_t " clk_id, " struct timex *" "buf" );
-.P
 .BI "int ntp_adjtime(struct timex *" buf );
+.P
+.BR #include <time.h>
+.P
+.BI "int clock_adjtime(clockid_t " clk_id, " struct timex *" "buf" );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR clock_adjtime ():
+.nf
+    _GNU_SOURCE
 .fi
 .SH DESCRIPTION
 Linux uses David L.\& Mills' clock adjustment algorithm (see RFC\ 5905).
@@ -534,6 +546,12 @@ .SH ERRORS
 Under Linux, the
 .B CAP_SYS_TIME
 capability is required.
+.TP
+.B ERANGE
+The frequency offset supplied with
+.BR clock_adjtime ()
+is outside of the range clock clk_id supports.
+See also /sys/class/ptp/ptpX/max_adjustment when adjusting a PTP hardware clock.
 .SH ATTRIBUTES
 For an explanation of the terms used in this section, see
 .BR attributes (7).
-- 
2.55.0