git: b28b04428732 - stable/15 - tzcode: Expose and document offtime() and offtime_r()

The branch stable/15 has been updated by des:

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

commit b28b04428732b996aa29a79b8b3916c5cd7aa627
Author:     Dag-Erling Smørgrav <des@FreeBSD.org>
AuthorDate: 2025-09-23 18:52:10 +0000
Commit:     Dag-Erling Smørgrav <des@FreeBSD.org>
CommitDate: 2025-10-02 08:19:23 +0000

    tzcode: Expose and document offtime() and offtime_r()
    
    Includes diff reduction to upstream version of this patch.
    
    MFC after:      3 days
    Sponsored by:   Klara, Inc.
    Reviewed by:    philip
    Differential Revision:  https://reviews.freebsd.org/D39715
    
    (cherry picked from commit 155290b23f0b503b9db675d6a45f85b189ee1926)
---
 contrib/tzcode/localtime.c |  2 +-
 contrib/tzcode/private.h   |  2 +-
 include/time.h             |  2 ++
 lib/libc/stdtime/ctime.3   | 39 +++++++++++++++++++++++++++++++++------
 4 files changed, 37 insertions(+), 8 deletions(-)

diff --git a/contrib/tzcode/localtime.c b/contrib/tzcode/localtime.c
index 7ba72d730648..a8f97e31a4bb 100644
--- a/contrib/tzcode/localtime.c
+++ b/contrib/tzcode/localtime.c
@@ -2021,7 +2021,7 @@ offtime_key_init(void)
 }
 #endif /* __FreeBSD__ */
 struct tm *
-offtime(const time_t *timep, long offset)
+offtime(time_t const *timep, long offset)
 {
 #  if !SUPPORT_C89
   static struct tm tm;
diff --git a/contrib/tzcode/private.h b/contrib/tzcode/private.h
index 532d9ddc81c8..e6b206690b73 100644
--- a/contrib/tzcode/private.h
+++ b/contrib/tzcode/private.h
@@ -823,7 +823,7 @@ extern long altzone;
 struct tm *offtime(time_t const *, long);
 # endif
 # if TZ_TIME_T || !defined offtime_r
-struct tm *offtime_r(time_t const *, long, struct tm *);
+struct tm *offtime_r(time_t const *restrict, long, struct tm *restrict);
 # endif
 # if TZ_TIME_T || !defined timelocal
 time_t timelocal(struct tm *);
diff --git a/include/time.h b/include/time.h
index 89a76ca5fd93..9e71a85f6a9a 100644
--- a/include/time.h
+++ b/include/time.h
@@ -174,6 +174,8 @@ time_t timegm(struct tm * const);
 int timer_oshandle_np(timer_t timerid);
 time_t time2posix(time_t t);
 time_t posix2time(time_t t);
+struct tm *offtime(const time_t *, long);
+struct tm *offtime_r(const time_t *__restrict, long, struct tm *__restrict);
 #endif /* __BSD_VISIBLE */
 
 #if __POSIX_VISIBLE >= 200809 || defined(_XLOCALE_H_)
diff --git a/lib/libc/stdtime/ctime.3 b/lib/libc/stdtime/ctime.3
index 96b7f775535a..6384e8bd959b 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 March 26, 2024
+.Dd September 23, 2025
 .Dt CTIME 3
 .Os
 .Sh NAME
@@ -41,6 +41,8 @@
 .Nm localtime ,
 .Nm localtime_r ,
 .Nm mktime ,
+.Nm offtime ,
+.Nm offtime_r ,
 .Nm timegm
 .Nd transform binary date and time values
 .Sh LIBRARY
@@ -68,14 +70,19 @@
 .Fn localtime_r "const time_t *clock" "struct tm *result"
 .Ft time_t
 .Fn mktime "struct tm *tm"
+.Ft struct tm *
+.Fn offtime "const time_t *clock" "long offset"
+.Ft struct tm *
+.Fn offtime_r "const time_t *clock" "long offset" "struct tm *result"
 .Ft time_t
 .Fn timegm "struct tm *tm"
 .Sh DESCRIPTION
 The
 .Fn ctime ,
 .Fn gmtime ,
+.Fn localtime ,
 and
-.Fn localtime
+.Fn offtime
 functions all take as argument a pointer to a time value representing
 the time in seconds since the Epoch (00:00:00 UTC on January 1, 1970;
 see
@@ -123,6 +130,18 @@ adjustment, and returns a pointer to a
 .Vt struct tm .
 .Pp
 The
+.Fn offtime
+function similarly converts the time value with a time zone adjustment
+corresponding to the provided
+.Fa offset ,
+which is expressed in seconds, with positive values indicating a time
+zone ahead of UTC (east of the Prime Meridian).
+It does not call
+.Xr tzset 3
+or modify
+.Va tzname .
+.Pp
+The
 .Fn ctime
 function
 adjusts the time value for the current time zone in the same manner as
@@ -155,13 +174,15 @@ except the caller must provide the output buffer
 .Fa buf ,
 which must be at least 26 characters long, to store the result in.
 The
-.Fn localtime_r
+.Fn localtime_r ,
+.Fn gmtime_r ,
 and
-.Fn gmtime_r
+.Fn offtime_r
 functions provide the same functionality as
-.Fn localtime
+.Fn localtime ,
+.Fn gmtime ,
 and
-.Fn gmtime
+.Fn offtime
 respectively, except the caller must provide the output buffer
 .Fa result .
 .Pp
@@ -368,6 +389,12 @@ and
 .Fn localtime_r
 functions have been available since
 .Fx 8.0 .
+The
+.Fn offtime
+and
+.Fn offtime_r
+functions were added in
+.Fx 15.0 .
 .Sh BUGS
 Except for
 .Fn difftime ,