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

[Alejandro Colomar <alx+linux-man@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 3179 bytes --]

Hi Georg,

> Date: 2026-10-25 13:56:56+0100
> From: Georg Sauthoff <mail@gms.tf>
> Subject: [PATCH v1] man/man2/adjtimex.2: Add include, macro and error for clock_adjtime

Please separate this into two patches, each of which does only one
thing.  The error seems unrelated to the include.

I've CCed a few people that have worked in this manual page, in case
they have feedback (and also libc-alpha@).

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

Agree.  I wonder if this use of a different header is intentional and
why.

> (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>

BR is for alternating bold and roman, so this seems wrong.  You probably
want just B (see the include above).

BTW, I would use

	.B #define _GNU_SOURCE
	.B #include <time.h>

and then remove the Feature Test Macro text below.


Have a lovely night!
Alex

> +.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
> 
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]