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 April 20, 2023 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; 245.Pp 246The 247.Fn difftime 248function returns the difference in seconds between two time values, 249.Fa time1 250\- 251.Fa time0 . 252.Pp 253External declarations as well as the definition of 254.Vt struct tm 255are in the 256.In time.h 257header. 258The 259.Vt tm 260structure includes at least the following fields: 261.Bd -literal -offset indent 262int tm_sec; /* seconds (0 - 60) */ 263int tm_min; /* minutes (0 - 59) */ 264int tm_hour; /* hours (0 - 23) */ 265int tm_mday; /* day of month (1 - 31) */ 266int tm_mon; /* month of year (0 - 11) */ 267int tm_year; /* year \- 1900 */ 268int tm_wday; /* day of week (Sunday = 0) */ 269int tm_yday; /* day of year (0 - 365) */ 270int tm_isdst; /* is summer time in effect? */ 271char *tm_zone; /* abbreviation of timezone name */ 272long tm_gmtoff; /* offset from UTC in seconds */ 273.Ed 274.Pp 275The 276.Fa tm_isdst 277field is non-zero if summer time is in effect. 278.Pp 279The 280.Fa tm_gmtoff 281field is the offset in seconds of the time represented from UTC, 282with positive values indicating a time zone ahead of UTC (east of the 283Prime Meridian). 284.Sh SEE ALSO 285.Xr date 1 , 286.Xr clock_gettime 2 , 287.Xr gettimeofday 2 , 288.Xr getenv 3 , 289.Xr time 3 , 290.Xr tzset 3 , 291.Xr tzfile 5 292.Sh STANDARDS 293The 294.Fn asctime , 295.Fn ctime , 296.Fn difftime , 297.Fn gmtime , 298.Fn localtime , 299and 300.Fn mktime 301functions conform to 302.St -isoC , 303and conform to 304.St -p1003.1-96 305provided the selected local timezone does not contain a leap-second table 306(see 307.Xr zic 8 ) . 308.Pp 309The 310.Fn asctime_r , 311.Fn ctime_r , 312.Fn gmtime_r , 313and 314.Fn localtime_r 315functions are expected to conform to 316.St -p1003.1-96 317(again provided the selected local timezone does not contain a leap-second 318table). 319.Pp 320The 321.Fn timegm 322function is not specified by any standard; its function cannot be 323completely emulated using the standard functions described above. 324.Sh HISTORY 325This manual page is derived from 326the time package contributed to Berkeley by 327.An Arthur Olson 328and which appeared in 329.Bx 4.3 . 330.Pp 331The functions 332.Fn asctime , 333.Fn gmtime , 334and 335.Fn localtime 336first appeared in 337.At v5 , 338.Fn difftime 339and 340.Fn mktime 341in 342.Bx 4.3 Reno , 343and 344.Fn timegm 345and 346.Fn timelocal 347in SunOS 4.0. 348.Pp 349The 350.Fn asctime_r , 351.Fn ctime_r , 352.Fn gmtime_r 353and 354.Fn localtime_r 355functions have been available since 356.Fx 8.0 . 357.Sh BUGS 358Except for 359.Fn difftime , 360.Fn mktime , 361and the 362.Fn \&_r 363variants of the other functions, 364these functions leave their result in an internal static object and return 365a pointer to that object. 366Subsequent calls to these 367function will modify the same object. 368.Pp 369The C Standard provides no mechanism for a program to modify its current 370local timezone setting, and the POSIX-standard 371method is not reentrant. 372(However, thread-safe implementations are provided 373in the POSIX threaded environment.) 374.Pp 375The 376.Va tm_zone 377field of a returned 378.Vt tm 379structure points to a static array of characters, 380which will also be overwritten by any subsequent calls (as well as by 381subsequent calls to 382.Xr tzset 3 ) . 383.Pp 384Use of the external variable 385.Fa tzname 386is discouraged; the 387.Fa tm_zone 388entry in the tm structure is preferred. 389