[PATCH 1/3] man/man2/gettimeofday.2: Declare gettimeofday with [[deprecated]].

[PATCH 1/3] man/man2/gettimeofday.2: Declare gettimeofday with [[deprecated]].

[Collin Funk]

As documented in the STANDARDS section gettimeofday was deprecated in
POSIX.1-2008 and removed in POSIX.1-2024. Mark the function as
[[deprecated]] since most systems still have it for comparability, along
with a more modern alternative (e.g. clock_gettime).

Signed-off-by: Collin Funk <collin.funk1@gmail.com>
---
 man/man2/gettimeofday.2 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/man/man2/gettimeofday.2 b/man/man2/gettimeofday.2
index d954a253f..bdb2b0bd3 100644
--- a/man/man2/gettimeofday.2
+++ b/man/man2/gettimeofday.2
@@ -12,8 +12,8 @@ .SH SYNOPSIS
 .nf
 .B #include <sys/time.h>
 .P
-.BI "int gettimeofday(struct timeval *restrict " tv ,
-.BI "                 struct timezone *_Nullable restrict " tz );
+.BI "[[deprecated]] int gettimeofday(struct timeval *restrict " tv ,
+.BI "                                struct timezone *_Nullable restrict " tz );
 .BI "int settimeofday(const struct timeval *" tv ,
 .BI "                 const struct timezone *_Nullable " tz );
 .fi
-- 
2.49.0

[PATCH 2/3] man/man3/ftime.3: Declare ftime with [[deprecated]].

[Collin Funk]

This function was marked as legacy in POSIX.1-2001 and has been removed
from many systems, including glibc.

Signed-off-by: Collin Funk <collin.funk1@gmail.com>
---
 man/man3/ftime.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/man3/ftime.3 b/man/man3/ftime.3
index a34b15888..8ae808ec2 100644
--- a/man/man3/ftime.3
+++ b/man/man3/ftime.3
@@ -13,7 +13,7 @@ .SH SYNOPSIS
 .nf
 .B "#include <sys/timeb.h>"
 .P
-.BI "int ftime(struct timeb *" tp );
+.BI "[[deprecated]] int ftime(struct timeb *" tp );
 .fi
 .SH DESCRIPTION
 .BR NOTE :
-- 
2.49.0

[PATCH 3/3] man/man3/ftime.3: Correct POSIX standards in HISTORY.

[Collin Funk]

This function was incorrectly marked as removed in POSIX-1.2001, but
that standard contained this function marked as LEGACY. It was then
removed in POSIX.1-2008.

Signed-off-by: Collin Funk <collin.funk1@gmail.com>
---
 man/man3/ftime.3 | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/man/man3/ftime.3 b/man/man3/ftime.3
index 8ae808ec2..5cdaf3e70 100644
--- a/man/man3/ftime.3
+++ b/man/man3/ftime.3
@@ -83,9 +83,10 @@ .SH ATTRIBUTES
 .SH STANDARDS
 None.
 .SH HISTORY
+Marked as LEGACY in POSIX.1-2001;
+removed in POSIX.1-2008.
 Removed in glibc 2.33.
-4.2BSD, POSIX.1-2001.
-Removed in POSIX.1-2008.
+4.2BSD.
 .P
 This function is obsolete.
 Don't use it.
-- 
2.49.0

Re: [PATCH 1/3] man/man2/gettimeofday.2: Declare gettimeofday with [[deprecated]].

[Alejandro Colomar]

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

Hi Collin,

On Wed, Jun 18, 2025 at 09:22:09PM -0700, Collin Funk wrote:
> As documented in the STANDARDS section gettimeofday was deprecated in
> POSIX.1-2008 and removed in POSIX.1-2024. Mark the function as
> [[deprecated]] since most systems still have it for comparability, along
> with a more modern alternative (e.g. clock_gettime).
> 
> Signed-off-by: Collin Funk <collin.funk1@gmail.com>
> ---
>  man/man2/gettimeofday.2 | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/man/man2/gettimeofday.2 b/man/man2/gettimeofday.2
> index d954a253f..bdb2b0bd3 100644
> --- a/man/man2/gettimeofday.2
> +++ b/man/man2/gettimeofday.2
> @@ -12,8 +12,8 @@ .SH SYNOPSIS
>  .nf
>  .B #include <sys/time.h>
>  .P
> -.BI "int gettimeofday(struct timeval *restrict " tv ,
> -.BI "                 struct timezone *_Nullable restrict " tz );
> +.BI "[[deprecated]] int gettimeofday(struct timeval *restrict " tv ,

Please put the attribute in a separate line, to avoid bad alignment.

> +.BI "                                struct timezone *_Nullable restrict " tz );
>  .BI "int settimeofday(const struct timeval *" tv ,
>  .BI "                 const struct timezone *_Nullable " tz );

Should settimeofday(2) be considered deprecated too, even if it was
never standard?  It doesn't seem to make much sense to keep it intact if
the get*() one is deprecated.


Have a lovely day!
Alex

>  .fi
> -- 
> 2.49.0
> 

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

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

Re: [PATCH 1/3] man/man2/gettimeofday.2: Declare gettimeofday with [[deprecated]].

[Collin Funk]

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

Hi Alex,

Alejandro Colomar <alx@kernel.org> writes:

>> -.BI "int gettimeofday(struct timeval *restrict " tv ,
>> -.BI "                 struct timezone *_Nullable restrict " tz );
>> +.BI "[[deprecated]] int gettimeofday(struct timeval *restrict " tv ,
>
> Please put the attribute in a separate line, to avoid bad alignment.

I thought my patch had lines that were too long, but I wasn't sure of a
better way to format it. If I understand correctly, you suggest:

    .BI "[[deprecated]]"
    .BI "int gettimeofday(struct timeval *restrict " tv ,
    .BI "                 struct timezone *_Nullable restrict " tz );

But I think the [[deprecated]] looks a bit strange alone on that line.
Maybe the return type 'int' should be placed on the line with it. What
do you think?

>>  .BI "int settimeofday(const struct timeval *" tv ,
>>  .BI "                 const struct timezone *_Nullable " tz );
>
> Should settimeofday(2) be considered deprecated too, even if it was
> never standard?  It doesn't seem to make much sense to keep it intact if
> the get*() one is deprecated.

Sure, it seems pretty uncontroversial to deprecate it ourselves. In V2 I
can also add the [[deprecated]] there and recommend 'clock_settime'
instead in HISTORY.

I will wait for your input on the declaration formatting first though.

Collin

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

Re: [PATCH 1/3] man/man2/gettimeofday.2: Declare gettimeofday with [[deprecated]].

[Alejandro Colomar]

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

Hi Collin,

On Thu, Jun 19, 2025 at 10:54:32AM -0700, Collin Funk wrote:
> Hi Alex,
> 
> Alejandro Colomar <alx@kernel.org> writes:
> 
> >> -.BI "int gettimeofday(struct timeval *restrict " tv ,
> >> -.BI "                 struct timezone *_Nullable restrict " tz );
> >> +.BI "[[deprecated]] int gettimeofday(struct timeval *restrict " tv ,
> >
> > Please put the attribute in a separate line, to avoid bad alignment.
> 
> I thought my patch had lines that were too long, but I wasn't sure of a
> better way to format it. If I understand correctly, you suggest:
> 
>     .BI "[[deprecated]]"
>     .BI "int gettimeofday(struct timeval *restrict " tv ,
>     .BI "                 struct timezone *_Nullable restrict " tz );
> 
> But I think the [[deprecated]] looks a bit strange alone on that line.

No, we already have several pages with that style; usually with
functions with a long name.

> Maybe the return type 'int' should be placed on the line with it. What
> do you think?

No, I don't like that.  The type on its own line is fine IMO, but in the
same line as the attribute looks weird.

To me, OK:

	[[attr]] int foo(void);

	[[attr]]
	int foo(void);

	[[attr]]
	int
	foo(void); // I use this style when writing function definitions

To me, not OK:

	[[attr]] int
	foo(void);

> >>  .BI "int settimeofday(const struct timeval *" tv ,
> >>  .BI "                 const struct timezone *_Nullable " tz );
> >
> > Should settimeofday(2) be considered deprecated too, even if it was
> > never standard?  It doesn't seem to make much sense to keep it intact if
> > the get*() one is deprecated.
> 
> Sure, it seems pretty uncontroversial to deprecate it ourselves. In V2 I
> can also add the [[deprecated]] there and recommend 'clock_settime'
> instead in HISTORY.

Thanks!  It might be good to CC libc-alpha@ and linux-api@ in such a
patch.  Or maybe it's overkill.


Have a lovely day!
Alex

> 
> I will wait for your input on the declaration formatting first though.
> 
> Collin



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

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

[PATCH v2] man/man2/gettimeofday.2: Declare functions with [[deprecated]].

[Collin Funk]

As documented in the STANDARDS section gettimeofday was deprecated in
POSIX.1-2008 and removed in POSIX.1-2024. Mark it and settimeofday with
[[deprecated]], and mention clock_settime as a modern and standardized
alternative to settimeofday.

Signed-off-by: Collin Funk <collin.funk1@gmail.com>
---
 man/man2/gettimeofday.2 | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/man/man2/gettimeofday.2 b/man/man2/gettimeofday.2
index d954a253f..83dfc2e5a 100644
--- a/man/man2/gettimeofday.2
+++ b/man/man2/gettimeofday.2
@@ -12,8 +12,10 @@ .SH SYNOPSIS
 .nf
 .B #include <sys/time.h>
 .P
+.BI "[[deprecated]]"
 .BI "int gettimeofday(struct timeval *restrict " tv ,
 .BI "                 struct timezone *_Nullable restrict " tz );
+.BI "[[deprecated]]"
 .BI "int settimeofday(const struct timeval *" tv ,
 .BI "                 const struct timezone *_Nullable " tz );
 .fi
@@ -184,6 +186,10 @@ .SH HISTORY
 as obsolete, recommending the use of
 .BR clock_gettime (2)
 instead.
+Likewise,
+.BR clock_settime (2)
+should be used instead of
+.BR settimeofday ().
 POSIX.1-2024 removed
 .BR gettimeofday ().
 .P
-- 
2.49.0

Re: [PATCH 1/3] man/man2/gettimeofday.2: Declare gettimeofday with [[deprecated]].

[Collin Funk]

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

Hi Alex,

Alejandro Colomar <alx@kernel.org> writes:

> No, I don't like that.  The type on its own line is fine IMO, but in the
> same line as the attribute looks weird.
>
> To me, OK:
>
> 	[[attr]] int foo(void);
>
> 	[[attr]]
> 	int foo(void);
>
> 	[[attr]]
> 	int
> 	foo(void); // I use this style when writing function definitions
>
> To me, not OK:
>
> 	[[attr]] int
> 	foo(void);

Okay, good to know the conventions. Thanks.

> Thanks!  It might be good to CC libc-alpha@ and linux-api@ in such a
> patch.  Or maybe it's overkill.

I will avoid it. I don't expect the syscalls to be removed as many old
programs still use them. And they work fine in most programs where
nanosecond resolution does not matter.

Also, currently glibc does not mark them as
[[deprecated]]/__attribute__ ((__deprecated__)) and I hope that it stays
that way for the foreseeable future. Apple, for example, marks functions
that are fine and used safely with deprecated and it causes many
annoying warnings when building programs. Specifically, any file that
uses sprintf or vfork will cause a warning on MacOS.

Anyways, submitted a v2 for patch 1/3 [1]. The other patches don't
depend on it. Just other things I have noticed.

Collin

[1] https://lore.kernel.org/linux-man/2d37d5a9251af3c1d25cf8e73e3585a9955d5772.1750373011.git.collin.funk1@gmail.com/T/#u

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

Re: [PATCH v2] man/man2/gettimeofday.2: Declare functions with [[deprecated]].

[Alejandro Colomar]

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

Hi Collin,

On Thu, Jun 19, 2025 at 03:43:49PM -0700, Collin Funk wrote:
> As documented in the STANDARDS section gettimeofday was deprecated in
> POSIX.1-2008 and removed in POSIX.1-2024. Mark it and settimeofday with
> [[deprecated]], and mention clock_settime as a modern and standardized
> alternative to settimeofday.
> 
> Signed-off-by: Collin Funk <collin.funk1@gmail.com>

Thanks!  I've appplied this patch (but see below).


Have a lovely day!
Alex

> ---
>  man/man2/gettimeofday.2 | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/man/man2/gettimeofday.2 b/man/man2/gettimeofday.2
> index d954a253f..83dfc2e5a 100644
> --- a/man/man2/gettimeofday.2
> +++ b/man/man2/gettimeofday.2
> @@ -12,8 +12,10 @@ .SH SYNOPSIS
>  .nf
>  .B #include <sys/time.h>
>  .P
> +.BI "[[deprecated]]"

I've changed this to

	.B [[deprecated]]

The '"' were redundant, and BI is for alternating Bold and Italics, but
in this case we only wanted bold.

>  .BI "int gettimeofday(struct timeval *restrict " tv ,
>  .BI "                 struct timezone *_Nullable restrict " tz );
> +.BI "[[deprecated]]"
>  .BI "int settimeofday(const struct timeval *" tv ,
>  .BI "                 const struct timezone *_Nullable " tz );
>  .fi
> @@ -184,6 +186,10 @@ .SH HISTORY
>  as obsolete, recommending the use of
>  .BR clock_gettime (2)
>  instead.
> +Likewise,
> +.BR clock_settime (2)
> +should be used instead of
> +.BR settimeofday ().
>  POSIX.1-2024 removed
>  .BR gettimeofday ().
>  .P
> -- 
> 2.49.0
> 

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

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

Re: [PATCH 2/3] man/man3/ftime.3: Declare ftime with [[deprecated]].

[Alejandro Colomar]

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

Hi Collin,

On Wed, Jun 18, 2025 at 09:22:10PM -0700, Collin Funk wrote:
> This function was marked as legacy in POSIX.1-2001 and has been removed
> from many systems, including glibc.
> 
> Signed-off-by: Collin Funk <collin.funk1@gmail.com>

Thanks!  Patch applied.


Cheers,
Alex

> ---
>  man/man3/ftime.3 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man/man3/ftime.3 b/man/man3/ftime.3
> index a34b15888..8ae808ec2 100644
> --- a/man/man3/ftime.3
> +++ b/man/man3/ftime.3
> @@ -13,7 +13,7 @@ .SH SYNOPSIS
>  .nf
>  .B "#include <sys/timeb.h>"
>  .P
> -.BI "int ftime(struct timeb *" tp );
> +.BI "[[deprecated]] int ftime(struct timeb *" tp );
>  .fi
>  .SH DESCRIPTION
>  .BR NOTE :
> -- 
> 2.49.0
> 

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

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

Re: [PATCH 3/3] man/man3/ftime.3: Correct POSIX standards in HISTORY.

[Alejandro Colomar]

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

Hi Collin,

On Wed, Jun 18, 2025 at 09:22:11PM -0700, Collin Funk wrote:
> This function was incorrectly marked as removed in POSIX-1.2001, but
> that standard contained this function marked as LEGACY. It was then
> removed in POSIX.1-2008.

The old page didn't say it was removed in POSIX.1-2001.

	$ man -w ftime \
	| xargs mansect HISTORY \
	| MANWIDTH=64 man /dev/stdin \
	| cat;
	ftime(3)            Library Functions Manual           ftime(3)

	HISTORY
	       Removed  in  glibc 2.33.  4.2BSD, POSIX.1‐2001.  Removed
	       in POSIX.1‐2008.

	       This function is obsolete.  Don’t use it.  If  the  time
	       in  seconds  suffices,  time(2)  can be used; gettimeof‐
	       day(2)  gives   microseconds;   clock_gettime(2)   gives
	       nanoseconds but is not as widely available.

	Linux man‐pages 6.14‐18... 2025‐05‐17                  ftime(3)

However, I agree that the order of the text could be confusing.  I like
yours better, but how about moving 4.2BSD to the begining to improve it
further?


Cheers,
Alex

> 
> Signed-off-by: Collin Funk <collin.funk1@gmail.com>
> ---
>  man/man3/ftime.3 | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/man/man3/ftime.3 b/man/man3/ftime.3
> index 8ae808ec2..5cdaf3e70 100644
> --- a/man/man3/ftime.3
> +++ b/man/man3/ftime.3
> @@ -83,9 +83,10 @@ .SH ATTRIBUTES
>  .SH STANDARDS
>  None.
>  .SH HISTORY
> +Marked as LEGACY in POSIX.1-2001;
> +removed in POSIX.1-2008.
>  Removed in glibc 2.33.
> -4.2BSD, POSIX.1-2001.
> -Removed in POSIX.1-2008.
> +4.2BSD.
>  .P
>  This function is obsolete.
>  Don't use it.
> -- 
> 2.49.0
> 

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

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

Re: [PATCH v2] man/man2/gettimeofday.2: Declare functions with [[deprecated]].

[Collin Funk]

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

Alejandro Colomar <alx@kernel.org> writes:

>>  .B #include <sys/time.h>
>>  .P
>> +.BI "[[deprecated]]"
>
> I've changed this to
>
> 	.B [[deprecated]]
>
> The '"' were redundant, and BI is for alternating Bold and Italics, but
> in this case we only wanted bold.

Good to know, thanks. I just assumed it should be the same as the other
lines. I didn't even know what the ".BI" meant. :)

Collin

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

Re: [PATCH 3/3] man/man3/ftime.3: Correct POSIX standards in HISTORY.

[Collin Funk]

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

Alejandro Colomar <alx@kernel.org> writes:

> The old page didn't say it was removed in POSIX.1-2001.
>
> 	$ man -w ftime \
> 	| xargs mansect HISTORY \
> 	| MANWIDTH=64 man /dev/stdin \
> 	| cat;
> 	ftime(3)            Library Functions Manual           ftime(3)
>
> 	HISTORY
> 	       Removed  in  glibc 2.33.  4.2BSD, POSIX.1‐2001.  Removed
> 	       in POSIX.1‐2008.
>
> 	       This function is obsolete.  Don’t use it.  If  the  time
> 	       in  seconds  suffices,  time(2)  can be used; gettimeof‐
> 	       day(2)  gives   microseconds;   clock_gettime(2)   gives
> 	       nanoseconds but is not as widely available.
>
> 	Linux man‐pages 6.14‐18... 2025‐05‐17                  ftime(3)
>
> However, I agree that the order of the text could be confusing.  I like
> yours better, but how about moving 4.2BSD to the begining to improve it
> further?

Oops, I must have interpreted that period as a comma.

I agree re-ordering will make it more clear, so I sent a new patch [1].

I realize now after sending it that the commit message should be
s/STANDARDS/HISTORY/ though...

Collin

[1] https://lore.kernel.org/linux-man/fcc66f4d8694f933a71688ad529e6f4f43024658.1750646692.git.collin.funk1@gmail.com/T/#u

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

Re: [PATCH v2] man/man2/gettimeofday.2: Declare functions with [[deprecated]].

[G. Branden Robinson]

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

At 2025-06-22T19:42:10-0700, Collin Funk wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> > The '"' were redundant, and BI is for alternating Bold and Italics,
> > but in this case we only wanted bold.
> 
> Good to know, thanks. I just assumed it should be the same as the
> other lines. I didn't even know what the ".BI" meant. :)

Be sure to Like and Subscribe, check out my Patreon^W^W^W^W^W^W^W
consult the groff_man(7) man page for a description of the macros you'll
see in a Linux man-pages document.  :)

Regards,
Branden

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