From 732a4803952c332443604578c687ff1c2e58bfb8 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Mon, 25 Mar 2024 18:49:10 -0700
Subject: [PATCH] Document how to detect mktime failure reliably

---
 newctime.3 | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/newctime.3 b/newctime.3
index 3b54d4ad..fe5176e4 100644
--- a/newctime.3
+++ b/newctime.3
@@ -191,9 +191,19 @@ are determined.
 The
 .B mktime
 function
-returns the specified calendar time;
+returns the specified calendar time.
 If the calendar time cannot be represented,
-it returns \-1.
+it returns \-1 without updating the structure.
+To distinguish failure from a valid \-1 return,
+you can set
+.B tm_mday
+or
+.B tm_yday
+to a negative value before calling
+.BR mktime ;
+if that value is still negative when
+.B mktime
+returns, the calendar time could not be represented.
 .PP
 The
 .B difftime
-- 
2.44.0