diff options
Diffstat (limited to 'lib/libc/stdtime/ctime.3')
| -rw-r--r-- | lib/libc/stdtime/ctime.3 | 57 |
1 files changed, 48 insertions, 9 deletions
diff --git a/lib/libc/stdtime/ctime.3 b/lib/libc/stdtime/ctime.3 index 25a7c6a7656e..6384e8bd959b 100644 --- a/lib/libc/stdtime/ctime.3 +++ b/lib/libc/stdtime/ctime.3 @@ -27,9 +27,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" From: @(#)ctime.3 8.1 (Berkeley) 6/4/93 -.\" -.Dd April 20, 2023 +.Dd September 23, 2025 .Dt CTIME 3 .Os .Sh NAME @@ -43,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 @@ -70,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 @@ -125,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 @@ -157,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 @@ -243,7 +262,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 @@ -356,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 , |