diff options
Diffstat (limited to 'lib/libc/stdtime/ctime.3')
| -rw-r--r-- | lib/libc/stdtime/ctime.3 | 429 |
1 files changed, 429 insertions, 0 deletions
diff --git a/lib/libc/stdtime/ctime.3 b/lib/libc/stdtime/ctime.3 new file mode 100644 index 000000000000..6384e8bd959b --- /dev/null +++ b/lib/libc/stdtime/ctime.3 @@ -0,0 +1,429 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Arthur Olson. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 23, 2025 +.Dt CTIME 3 +.Os +.Sh NAME +.Nm asctime , +.Nm asctime_r , +.Nm ctime , +.Nm ctime_r , +.Nm difftime , +.Nm gmtime , +.Nm gmtime_r , +.Nm localtime , +.Nm localtime_r , +.Nm mktime , +.Nm offtime , +.Nm offtime_r , +.Nm timegm +.Nd transform binary date and time values +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Vt extern char *tzname[2] ; +.Ft char * +.Fn asctime "const struct tm *tm" +.Ft char * +.Fn asctime_r "const struct tm *tm" "char *buf" +.Ft char * +.Fn ctime "const time_t *clock" +.Ft char * +.Fn ctime_r "const time_t *clock" "char *buf" +.Ft double +.Fn difftime "time_t time1" "time_t time0" +.Ft struct tm * +.Fn gmtime "const time_t *clock" +.Ft struct tm * +.Fn gmtime_r "const time_t *clock" "struct tm *result" +.Ft struct tm * +.Fn localtime "const time_t *clock" +.Ft struct tm * +.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 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 +.Xr time 3 ) . +.Pp +The +.Fn localtime +function converts the time value pointed to by +.Fa clock , +and returns a pointer to a +.Vt struct tm +(described below) which contains +the broken-out time information for the value after adjusting for the current +time zone (see +.Xr tzset 3 ) . +When the specified time translates to a year that will not fit in an +.Vt int , +.Fn localtime +returns +.Dv NULL . +The +.Fn localtime +function uses +.Xr tzset 3 +to initialize time conversion information if +.Xr tzset 3 +has not already been called by the process. +.Pp +After filling in the +.Vt struct tm , +.Fn localtime +sets the +.Va tm_isdst Ns 'th +element of +.Va tzname +to a pointer to an ASCII string that is the time zone abbreviation to be +used with +.Fn localtime Ns 's +return value. +.Pp +The +.Fn gmtime +function similarly converts the time value, but without any time zone +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 +.Fn localtime , +and returns a pointer to a 26-character string of the form: +.Bd -literal -offset indent +Thu Nov 24 18:22:48 1986\en\e0 +.Ed +.Pp +All the fields have constant width. +.Pp +The +.Fn asctime +function converts the broken down time in the +.Vt struct tm +pointed to by +.Fa tm +to the form shown in the example above. +.Pp +The +.Fn ctime_r +and +.Fn asctime_r +functions +provide the same functionality as +.Fn ctime +and +.Fn asctime +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 gmtime_r , +and +.Fn offtime_r +functions provide the same functionality as +.Fn localtime , +.Fn gmtime , +and +.Fn offtime +respectively, except the caller must provide the output buffer +.Fa result . +.Pp +The functions +.Fn mktime +and +.Fn timegm +convert the broken-down time in the +.Vt struct tm +pointed to by +.Fa tm +into a time value with the same encoding as that of the values +returned by the +.Xr time 3 +function (that is, seconds from the Epoch, UTC). +The +.Fn mktime +function interprets the input structure according to the current +timezone setting (see +.Xr tzset 3 ) +while the +.Fn timegm +function interprets the input structure as representing Universal +Coordinated Time +.Pq UTC . +.Pp +The original values of the +.Fa tm_wday +and +.Fa tm_yday +components of the structure are ignored, and the original values of the +other components are not restricted to their normal ranges, and will be +normalized if needed. +For example, +October 40 is changed into November 9, +a +.Fa tm_hour +of \-1 means 1 hour before midnight, +.Fa tm_mday +of 0 means the day preceding the current month, and +.Fa tm_mon +of \-2 means 2 months before January of +.Fa tm_year . +(A positive or zero value for +.Fa tm_isdst +causes +.Fn mktime +to presume initially that summer time (for example, Daylight Saving Time) +is or is not in effect for the specified time, respectively. +A negative value for +.Fa tm_isdst +causes the +.Fn mktime +function to attempt to guess whether summer time is in effect for the +specified time. +The +.Fa tm_isdst +and +.Fa tm_gmtoff +members are forced to zero by +.Fn timegm . ) +.Pp +On successful completion, the values of the +.Fa tm_wday +and +.Fa tm_yday +components of the structure are set appropriately, and the other components +are set to represent the specified calendar time, but with their values +forced to their normal ranges; the final value of +.Fa tm_mday +is not set until +.Fa tm_mon +and +.Fa tm_year +are determined. +The +.Fn mktime +function +returns the specified calendar time; if the calendar time cannot be +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 +function returns the difference in seconds between two time values, +.Fa time1 +\- +.Fa time0 . +.Pp +External declarations as well as the definition of +.Vt struct tm +are in the +.In time.h +header. +The +.Vt tm +structure includes at least the following fields: +.Bd -literal -offset indent +int tm_sec; /* seconds (0 - 60) */ +int tm_min; /* minutes (0 - 59) */ +int tm_hour; /* hours (0 - 23) */ +int tm_mday; /* day of month (1 - 31) */ +int tm_mon; /* month of year (0 - 11) */ +int tm_year; /* year \- 1900 */ +int tm_wday; /* day of week (Sunday = 0) */ +int tm_yday; /* day of year (0 - 365) */ +int tm_isdst; /* is summer time in effect? */ +char *tm_zone; /* abbreviation of timezone name */ +long tm_gmtoff; /* offset from UTC in seconds */ +.Ed +.Pp +The +.Fa tm_isdst +field is non-zero if summer time is in effect. +.Pp +The +.Fa tm_gmtoff +field is the offset in seconds of the time represented from UTC, +with positive values indicating a time zone ahead of UTC (east of the +Prime Meridian). +.Sh SEE ALSO +.Xr date 1 , +.Xr clock_gettime 2 , +.Xr gettimeofday 2 , +.Xr getenv 3 , +.Xr time 3 , +.Xr tzset 3 , +.Xr tzfile 5 +.Sh STANDARDS +The +.Fn asctime , +.Fn ctime , +.Fn difftime , +.Fn gmtime , +.Fn localtime , +and +.Fn mktime +functions conform to +.St -isoC , +and conform to +.St -p1003.1-96 +provided the selected local timezone does not contain a leap-second table +(see +.Xr zic 8 ) . +.Pp +The +.Fn asctime_r , +.Fn ctime_r , +.Fn gmtime_r , +and +.Fn localtime_r +functions are expected to conform to +.St -p1003.1-96 +(again provided the selected local timezone does not contain a leap-second +table). +.Pp +The +.Fn timegm +function is not specified by any standard; its function cannot be +completely emulated using the standard functions described above. +.Sh HISTORY +This manual page is derived from +the time package contributed to Berkeley by +.An Arthur Olson +and which appeared in +.Bx 4.3 . +.Pp +The functions +.Fn asctime , +.Fn gmtime , +and +.Fn localtime +first appeared in +.At v5 , +.Fn difftime +and +.Fn mktime +in +.Bx 4.3 Reno , +and +.Fn timegm +and +.Fn timelocal +in SunOS 4.0. +.Pp +The +.Fn asctime_r , +.Fn ctime_r , +.Fn gmtime_r +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 , +.Fn mktime , +and the +.Fn \&_r +variants of the other functions, +these functions leave their result in an internal static object and return +a pointer to that object. +Subsequent calls to these +function will modify the same object. +.Pp +The C Standard provides no mechanism for a program to modify its current +local timezone setting, and the POSIX-standard +method is not reentrant. +(However, thread-safe implementations are provided +in the POSIX threaded environment.) +.Pp +The +.Va tm_zone +field of a returned +.Vt tm +structure points to a static array of characters, +which will also be overwritten by any subsequent calls (as well as by +subsequent calls to +.Xr tzset 3 ) . +.Pp +Use of the external variable +.Fa tzname +is discouraged; the +.Fa tm_zone +entry in the tm structure is preferred. |