From a0d7485e8331ab220b53717f5331ea5943f0b231 Mon Sep 17 00:00:00 2001
From: tb <tb@openbsd.org>
Date: Mon, 13 Apr 2026 16:01:54 +0000
Subject: [PATCH] Document RETURN value for timegm(3)

APIs with in-band errors that conflate the error with a legitimate return
value are about the worst you can get. Near and dear to my heart is the API
aptly described as "gibbering eidritch horror" by beck: ASN1_INTEGER_get(3).
Adapt the wording of its RETURN VALUES to timegm() and mktime(), for which
Dec 31, 1969 at 23:59:59 will yield the error return -1 and thereby errata.

Missing docs pointed out by claudio a while back and yesterday by deraadt

ok deraadt millert
---
 lib/libc/time/ctime.3 | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/lib/libc/time/ctime.3 b/lib/libc/time/ctime.3
index 44a3a01a22b..9489a10a8b5 100644
--- a/lib/libc/time/ctime.3
+++ b/lib/libc/time/ctime.3
@@ -1,7 +1,7 @@
-.\"	$OpenBSD: ctime.3,v 1.50 2025/11/20 10:58:11 tb Exp $
+.\"	$OpenBSD: ctime.3,v 1.51 2026/04/13 16:01:54 tb Exp $
 .\"
 .\"
-.Dd $Mdocdate: November 20 2025 $
+.Dd $Mdocdate: April 13 2026 $
 .Dt CTIME 3
 .Os
 .Sh NAME
@@ -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 timegm
+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