[PATCH v3] ctime.3: EXAMPLES: Add example program

[Xi Ruoyao]

On Fri, 2024-08-23 at 09:02 +0200, Alejandro Colomar wrote:
> Is mktime(3) allowed to return -1 and set EOVERFLOW on a successful
> call?
> 
> RETURN VALUE
>      The mktime() function shall return the specified  time  since  the
>      Epoch  encoded  as  a value of type time_t.  If the time since the
>      Epoch cannot be represented, the function shall return  the  value
>      (time_t)-1 and set errno to indicate the error.

For mktime the standard only says "return (time_t)-1."  It does not
mention errno at all.  And the standard also says:

   The value of errno may be set to nonzero by a library function call
   whether or not there is an error, provided the use of errno is not
   documented in the description of the function in this document.

> Then I think the API is completely broken.  How should we check for
> errors after a mktime(3) call?

Maybe, special case if tm contains Dec 31 1969 23:59:59 UTC...  But it's
just stupid.

> If this is so, let me file a glibc bug requesting a fix of the API,
> adding a promise that on success, errno will remain unset.

It's a bug in the standard, not glibc.  And the standard has deprecated
it anyway.

https://www.open-std.org/JTC1/SC22/WG14/www/docs/n2566.pdf

> > How about if we omit the sample code and make the minimal changes I
> > suggested earlier?
> 
> Because I'm being very careful writing that code, and still I'm having
> trouble doing that, I think we must provide some example of a correct
> call, to prevent many other programmers from doing it wrong.

So IMO you should just say "the interface is deprecated, do not use it
in any new code."

-- 
Xi Ruoyao <xry111@xry111.site>
School of Aerospace Science and Technology, Xidian University