1.\" Copyright (c) 1989, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" Arthur Olson. 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd March 26, 2024 31.Dt CTIME 3 32.Os 33.Sh NAME 34.Nm asctime , 35.Nm asctime_r , 36.Nm ctime , 37.Nm ctime_r , 38.Nm difftime , 39.Nm gmtime , 40.Nm gmtime_r , 41.Nm localtime , 42.Nm localtime_r , 43.Nm mktime , 44.Nm timegm 45.Nd transform binary date and time values 46.Sh LIBRARY 47.Lb libc 48.Sh SYNOPSIS 49.In time.h 50.Vt extern char *tzname[2] ; 51.Ft char * 52.Fn asctime "const struct tm *tm" 53.Ft char * 54.Fn asctime_r "const struct tm *tm" "char *buf" 55.Ft char * 56.Fn ctime "const time_t *clock" 57.Ft char * 58.Fn ctime_r "const time_t *clock" "char *buf" 59.Ft double 60.Fn difftime "time_t time1" "time_t time0" 61.Ft struct tm * 62.Fn gmtime "const time_t *clock" 63.Ft struct tm * 64.Fn gmtime_r "const time_t *clock" "struct tm *result" 65.Ft struct tm * 66.Fn localtime "const time_t *clock" 67.Ft struct tm * 68.Fn localtime_r "const time_t *clock" "struct tm *result" 69.Ft time_t 70.Fn mktime "struct tm *tm" 71.Ft time_t 72.Fn timegm "struct tm *tm" 73.Sh DESCRIPTION 74The 75.Fn ctime , 76.Fn gmtime , 77and 78.Fn localtime 79functions all take as argument a pointer to a time value representing 80the time in seconds since the Epoch (00:00:00 UTC on January 1, 1970; 81see 82.Xr time 3 ) . 83.Pp 84The 85.Fn localtime 86function converts the time value pointed to by 87.Fa clock , 88and returns a pointer to a 89.Vt struct tm 90(described below) which contains 91the broken-out time information for the value after adjusting for the current 92time zone (see 93.Xr tzset 3 ) . 94When the specified time translates to a year that will not fit in an 95.Vt int , 96.Fn localtime 97returns 98.Dv NULL . 99The 100.Fn localtime 101function uses 102.Xr tzset 3 103to initialize time conversion information if 104.Xr tzset 3 105has not already been called by the process. 106.Pp 107After filling in the 108.Vt struct tm , 109.Fn localtime 110sets the 111.Va tm_isdst Ns 'th 112element of 113.Va tzname 114to a pointer to an ASCII string that is the time zone abbreviation to be 115used with 116.Fn localtime Ns 's 117return value. 118.Pp 119The 120.Fn gmtime 121function similarly converts the time value, but without any time zone 122adjustment, and returns a pointer to a 123.Vt struct tm . 124.Pp 125The 126.Fn ctime 127function 128adjusts the time value for the current time zone in the same manner as 129.Fn localtime , 130and returns a pointer to a 26-character string of the form: 131.Bd -literal -offset indent 132Thu Nov 24 18:22:48 1986\en\e0 133.Ed 134.Pp 135All the fields have constant width. 136.Pp 137The 138.Fn asctime 139function converts the broken down time in the 140.Vt struct tm 141pointed to by 142.Fa tm 143to the form shown in the example above. 144.Pp 145The 146.Fn ctime_r 147and 148.Fn asctime_r 149functions 150provide the same functionality as 151.Fn ctime 152and 153.Fn asctime 154except the caller must provide the output buffer 155.Fa buf , 156which must be at least 26 characters long, to store the result in. 157The 158.Fn localtime_r 159and 160.Fn gmtime_r 161functions provide the same functionality as 162.Fn localtime 163and 164.Fn gmtime 165respectively, except the caller must provide the output buffer 166.Fa result . 167.Pp 168The functions 169.Fn mktime 170and 171.Fn timegm 172convert the broken-down time in the 173.Vt struct tm 174pointed to by 175.Fa tm 176into a time value with the same encoding as that of the values 177returned by the 178.Xr time 3 179function (that is, seconds from the Epoch, UTC). 180The 181.Fn mktime 182function interprets the input structure according to the current 183timezone setting (see 184.Xr tzset 3 ) 185while the 186.Fn timegm 187function interprets the input structure as representing Universal 188Coordinated Time 189.Pq UTC . 190.Pp 191The original values of the 192.Fa tm_wday 193and 194.Fa tm_yday 195components of the structure are ignored, and the original values of the 196other components are not restricted to their normal ranges, and will be 197normalized if needed. 198For example, 199October 40 is changed into November 9, 200a 201.Fa tm_hour 202of \-1 means 1 hour before midnight, 203.Fa tm_mday 204of 0 means the day preceding the current month, and 205.Fa tm_mon 206of \-2 means 2 months before January of 207.Fa tm_year . 208(A positive or zero value for 209.Fa tm_isdst 210causes 211.Fn mktime 212to presume initially that summer time (for example, Daylight Saving Time) 213is or is not in effect for the specified time, respectively. 214A negative value for 215.Fa tm_isdst 216causes the 217.Fn mktime 218function to attempt to guess whether summer time is in effect for the 219specified time. 220The 221.Fa tm_isdst 222and 223.Fa tm_gmtoff 224members are forced to zero by 225.Fn timegm . ) 226.Pp 227On successful completion, the values of the 228.Fa tm_wday 229and 230.Fa tm_yday 231components of the structure are set appropriately, and the other components 232are set to represent the specified calendar time, but with their values 233forced to their normal ranges; the final value of 234.Fa tm_mday 235is not set until 236.Fa tm_mon 237and 238.Fa tm_year 239are determined. 240The 241.Fn mktime 242function 243returns the specified calendar time; if the calendar time cannot be 244represented, it returns \-1 and sets 245.Xr errno 3 246to an appropriate value. 247.Pp 248Note that \-1 is a valid result (representing one second before 249midnight UTC on the evening of 31 December 1969), so this cannot be 250relied upon to indicate success or failure; instead, 251.Fa tm_wday 252and / or 253.Fa tm_yday 254should be set to an out-of-bounds value (e.g. \-1) prior to calling 255.Fn mktime 256or 257.Fn timegm 258and checked after the call. 259.Pp 260The 261.Fn difftime 262function returns the difference in seconds between two time values, 263.Fa time1 264\- 265.Fa time0 . 266.Pp 267External declarations as well as the definition of 268.Vt struct tm 269are in the 270.In time.h 271header. 272The 273.Vt tm 274structure includes at least the following fields: 275.Bd -literal -offset indent 276int tm_sec; /* seconds (0 - 60) */ 277int tm_min; /* minutes (0 - 59) */ 278int tm_hour; /* hours (0 - 23) */ 279int tm_mday; /* day of month (1 - 31) */ 280int tm_mon; /* month of year (0 - 11) */ 281int tm_year; /* year \- 1900 */ 282int tm_wday; /* day of week (Sunday = 0) */ 283int tm_yday; /* day of year (0 - 365) */ 284int tm_isdst; /* is summer time in effect? */ 285char *tm_zone; /* abbreviation of timezone name */ 286long tm_gmtoff; /* offset from UTC in seconds */ 287.Ed 288.Pp 289The 290.Fa tm_isdst 291field is non-zero if summer time is in effect. 292.Pp 293The 294.Fa tm_gmtoff 295field is the offset in seconds of the time represented from UTC, 296with positive values indicating a time zone ahead of UTC (east of the 297Prime Meridian). 298.Sh SEE ALSO 299.Xr date 1 , 300.Xr clock_gettime 2 , 301.Xr gettimeofday 2 , 302.Xr getenv 3 , 303.Xr time 3 , 304.Xr tzset 3 , 305.Xr tzfile 5 306.Sh STANDARDS 307The 308.Fn asctime , 309.Fn ctime , 310.Fn difftime , 311.Fn gmtime , 312.Fn localtime , 313and 314.Fn mktime 315functions conform to 316.St -isoC , 317and conform to 318.St -p1003.1-96 319provided the selected local timezone does not contain a leap-second table 320(see 321.Xr zic 8 ) . 322.Pp 323The 324.Fn asctime_r , 325.Fn ctime_r , 326.Fn gmtime_r , 327and 328.Fn localtime_r 329functions are expected to conform to 330.St -p1003.1-96 331(again provided the selected local timezone does not contain a leap-second 332table). 333.Pp 334The 335.Fn timegm 336function is not specified by any standard; its function cannot be 337completely emulated using the standard functions described above. 338.Sh HISTORY 339This manual page is derived from 340the time package contributed to Berkeley by 341.An Arthur Olson 342and which appeared in 343.Bx 4.3 . 344.Pp 345The functions 346.Fn asctime , 347.Fn gmtime , 348and 349.Fn localtime 350first appeared in 351.At v5 , 352.Fn difftime 353and 354.Fn mktime 355in 356.Bx 4.3 Reno , 357and 358.Fn timegm 359and 360.Fn timelocal 361in SunOS 4.0. 362.Pp 363The 364.Fn asctime_r , 365.Fn ctime_r , 366.Fn gmtime_r 367and 368.Fn localtime_r 369functions have been available since 370.Fx 8.0 . 371.Sh BUGS 372Except for 373.Fn difftime , 374.Fn mktime , 375and the 376.Fn \&_r 377variants of the other functions, 378these functions leave their result in an internal static object and return 379a pointer to that object. 380Subsequent calls to these 381function will modify the same object. 382.Pp 383The C Standard provides no mechanism for a program to modify its current 384local timezone setting, and the POSIX-standard 385method is not reentrant. 386(However, thread-safe implementations are provided 387in the POSIX threaded environment.) 388.Pp 389The 390.Va tm_zone 391field of a returned 392.Vt tm 393structure points to a static array of characters, 394which will also be overwritten by any subsequent calls (as well as by 395subsequent calls to 396.Xr tzset 3 ) . 397.Pp 398Use of the external variable 399.Fa tzname 400is discouraged; the 401.Fa tm_zone 402entry in the tm structure is preferred. 403