git: fdde01c5b449 - stable/14 - libc: Improve description of mktime() / timegm().

The branch stable/14 has been updated by des:

URL: https://cgit.FreeBSD.org/src/commit/?id=fdde01c5b44904e34ff3b003f446644de865fa21

commit fdde01c5b44904e34ff3b003f446644de865fa21
Author:     Dag-Erling Smørgrav <des@FreeBSD.org>
AuthorDate: 2024-03-27 10:03:37 +0000
Commit:     Dag-Erling Smørgrav <des@FreeBSD.org>
CommitDate: 2024-04-04 09:41:41 +0000

    libc: Improve description of mktime() / timegm().
    
    * Mention that mktime() and timegm() set errno on failure.
    * Correctly determining whether mktime() / timegm() succeeded with
      arbitrary input (where -1 can be a valid result) is non-trivial.
      Document the recommended procedure.
    
    PR:             277863
    MFC after:      1 week
    Reviewed by:    pauamma_gundo.com, gbe
    Differential Revision:  https://reviews.freebsd.org/D44503
    
    (cherry picked from commit 7534109d13a6cdb22e78d9d4c0a0cd5efd323c45)
---
 lib/libc/stdtime/ctime.3 | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/lib/libc/stdtime/ctime.3 b/lib/libc/stdtime/ctime.3
index 25a7c6a7656e..7216ada23826 100644
--- a/lib/libc/stdtime/ctime.3
+++ b/lib/libc/stdtime/ctime.3
@@ -29,7 +29,7 @@
 .\"
 .\"     From: @(#)ctime.3	8.1 (Berkeley) 6/4/93
 .\"
-.Dd April 20, 2023
+.Dd March 26, 2024
 .Dt CTIME 3
 .Os
 .Sh NAME
@@ -243,7 +243,21 @@ The
 .Fn mktime
 function
 returns the specified calendar time; if the calendar time cannot be
-represented, it returns \-1;
+represented, it returns \-1 and sets
+.Xr errno 3
+to an appropriate value.
+.Pp
+Note that \-1 is a valid result (representing one second before
+midnight UTC on the evening of 31 December 1969), so this cannot be
+relied upon to indicate success or failure; instead,
+.Fa tm_wday
+and / or
+.Fa tm_yday
+should be set to an out-of-bounds value (e.g. \-1) prior to calling
+.Fn mktime
+or
+.Fn timegm
+and checked after the call.
 .Pp
 The
 .Fn difftime