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

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

[Georg Sauthoff]

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

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

[Alejandro Colomar]

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

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

[Georg Sauthoff]

Hello,

On Sun, Oct 25, 2026 at 07:49:32PM +0100, Alejandro Colomar wrote:
> 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.

Ok. Yes, it's unrelated. It wasn't my intention to imply that both hunks
are related.

I'll split it and send both as version 2.


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

FWIW, I copy and pasted the BR from another man page I picked as
template which already references _GNU_SOURCE, cf.

    $ grep '^\.BR #include' . -r | wc -l
    23

Ok, I change it to B. Also for consistency.


> BTW, I would use
> 
> 	.B #define _GNU_SOURCE
> 	.B #include <time.h>
> 
> and then remove the Feature Test Macro text below.

Ok, no problem. Again, I just copied that style from another man page:

    $ grep '^\.BR feature_test_macros' . -r -A50 | grep '\<_GNU' | wc -l
    62

The define style seems to be more popular, though:

    $ grep '#define _GNU_SOURCE' . -r | wc -l
    153

Plus special space variant:

    $ grep '#define\\~_GNU_SOURCE' . -r | wc -l
    2

I don't really have a preference between these styles and thus follow
your suggestion.

Best regards,
Georg

[PATCH v2 0/2] man/man2/adjtimex.2: Fix include+add error

[Georg Sauthoff]

Hello,

this series fixes the include instructions for clock_adjtime() 
and documents another error its invocation may yield.

Changes v1 -> v2:
- split patch into series
- use define-style feature macro instead of extra section
- fix font style macro usage

Best regards,
Georg

Georg Sauthoff (2):
  man/man2/adjtimex.2: Add include and macro for clock_adjtime
  man/man2/adjtimex.2: Add error for clock_adjtime

 man/man2/adjtimex.2 | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

Range-diff against v1:
1:  ddd4886f0 ! 1:  1f6278005 man/man2/adjtimex.2: Add include, macro and error for clock_adjtime
    @@ Metadata
     Author: Georg Sauthoff <mail@gms.tf>
     
      ## Commit message ##
    -    man/man2/adjtimex.2: Add include, macro and error for clock_adjtime
    +    man/man2/adjtimex.2: Add include and macro for clock_adjtime
     
         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.
    @@ Commit message
     
         (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>
    -
      ## man/man2/adjtimex.2 ##
     @@ man/man2/adjtimex.2: .SH SYNOPSIS
      .P
    @@ man/man2/adjtimex.2: .SH SYNOPSIS
     -.P
      .BI "int ntp_adjtime(struct timex *" buf );
     +.P
    -+.BR #include <time.h>
    ++.BR #define\~_GNU_SOURCE "  // See feature_test_macros(7)"
    ++.B #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).
    -@@ man/man2/adjtimex.2: .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:  578a02146 man/man2/adjtimex.2: Add error for clock_adjtime
-- 
2.55.0

[PATCH v2 1/2] man/man2/adjtimex.2: Add include and macro for clock_adjtime

[Georg Sauthoff]

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)

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

diff --git a/man/man2/adjtimex.2 b/man/man2/adjtimex.2
index f12d9413e..5b9a0667b 100644
--- a/man/man2/adjtimex.2
+++ b/man/man2/adjtimex.2
@@ -17,9 +17,12 @@ .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 #define\~_GNU_SOURCE "  // See feature_test_macros(7)"
+.B #include <time.h>
+.P
+.BI "int clock_adjtime(clockid_t " clk_id, " struct timex *" "buf" );
 .fi
 .SH DESCRIPTION
 Linux uses David L.\& Mills' clock adjustment algorithm (see RFC\ 5905).
-- 
2.55.0

[PATCH v2 2/2] man/man2/adjtimex.2: Add error for clock_adjtime

[Georg Sauthoff]

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 | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/man/man2/adjtimex.2 b/man/man2/adjtimex.2
index 5b9a0667b..6b6ee98b0 100644
--- a/man/man2/adjtimex.2
+++ b/man/man2/adjtimex.2
@@ -537,6 +537,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