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