From: Theo Buehler <tb@theobuehler.org>
Subject: Document timegm() error return
To: tech@openbsd.org
Date: Mon, 13 Apr 2026 06:11:54 +0200

The RETURN VALUE of timegm() is undocumented.

mktime() and timegm() call time1(), which returns WRONG aka -1 on error.
Of course, struct tm can represent Dec 31, 1969, 23:59:59, so this is
not necessarily an error. Wording adapted from ASN1_INTEGER_get(), which
suffers from the same fundamental design flaw.

It may well deserve more calling out, e.g., in DESCRIPTION and CAVEATS.
I'll leave that for someone else to fix.

Index: time/ctime.3
===================================================================
RCS file: /cvs/src/lib/libc/time/ctime.3,v
diff -u -p -r1.50 ctime.3
--- time/ctime.3	20 Nov 2025 10:58:11 -0000	1.50
+++ time/ctime.3	13 Apr 2026 03:46:41 -0000
@@ -278,9 +278,12 @@ The functions
 and
 .Fn gmtime_r
 return NULL on error.
-The function
+The functions
 .Fn mktime
-returns \-1 on error.
+and
+.Fn gmtime
+return \-1 on error,
+which is ambiguous because \-1 is a legitimate conversion result.
 .Sh FILES
 .Bl -tag -width "/usr/share/zoneinfo/posixrules" -compact
 .It Pa /usr/share/zoneinfo