git: 7534109d13a6 - main - libc: Improve description of mktime() / timegm().

The branch main has been updated by des:

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

commit 7534109d13a6cdb22e78d9d4c0a0cd5efd323c45
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-03-27 10:03:37 +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
---
 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 698a63cfa73d..96b7f775535a 100644
--- a/lib/libc/stdtime/ctime.3
+++ b/lib/libc/stdtime/ctime.3
@@ -27,7 +27,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd April 20, 2023
+.Dd March 26, 2024
 .Dt CTIME 3
 .Os
 .Sh NAME
@@ -241,7 +241,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