1.\" $OpenBSD: ctime.3,v 1.46 2020/04/30 18:36:12 schwarze Exp $ 2.\" 3.\" 4.Dd $Mdocdate: April 30 2020 $ 5.Dt CTIME 3 6.Os 7.Sh NAME 8.Nm asctime , 9.Nm asctime_r , 10.Nm ctime , 11.Nm ctime_r , 12.Nm difftime , 13.Nm gmtime , 14.Nm gmtime_r , 15.Nm localtime , 16.Nm localtime_r , 17.Nm mktime , 18.Nm timegm , 19.Nm timelocal 20.Nd convert date and time to ASCII 21.Sh SYNOPSIS 22.In sys/types.h 23.In time.h 24.Vt extern char *tzname[2] ; 25.Ft "char *" 26.Fn ctime "const time_t *clock" 27.Ft "char *" 28.Fn ctime_r "const time_t *clock" "char *buf" 29.Ft double 30.Fn difftime "time_t time1" "time_t time0" 31.Ft "char *" 32.Fn asctime "const struct tm *tm" 33.Ft "char *" 34.Fn asctime_r "const struct tm *tm" "char *buf" 35.Ft "struct tm *" 36.Fn localtime "const time_t *clock" 37.Ft "struct tm *" 38.Fn localtime_r "const time_t *clock" "struct tm *result" 39.Ft "struct tm *" 40.Fn gmtime "const time_t *clock" 41.Ft "struct tm *" 42.Fn gmtime_r "const time_t *clock" "struct tm *result" 43.Ft time_t 44.Fn mktime "struct tm *tm" 45.Ft time_t 46.Fn timegm "struct tm *tm" 47.Ft time_t 48.Fn timelocal "struct tm *tm" 49.Sh DESCRIPTION 50The 51.Fn ctime 52function converts a 53.Li time_t , 54pointed to by 55.Fa clock , 56representing the time in seconds since 5700:00:00 UTC, 1970-01-01, 58and returns a pointer to a 59string of the form 60.Pp 61.Dl Thu Nov 24 18:22:48 1986\en 62.Pp 63Years requiring fewer than four characters are padded with leading zeroes. 64For years longer than four characters, the string is of the form 65.Pp 66.Dl Thu Nov 24 18:22:48\ \ \ \ \ 81986\en 67.Pp 68with five spaces before the year. 69These unusual formats are designed to make it less likely that older 70software that expects exactly 26 bytes of output will mistakenly output 71misleading values for out-of-range years. 72.Pp 73The 74.Fn ctime_r 75function converts the calendar time pointed to by 76.Fa clock 77to local time in exactly the same way as 78.Fn ctime 79and puts the string into the array pointed to by 80.Fa buf 81(which contains at least 26 bytes) and returns 82.Fa buf . 83Unlike 84.Fn ctime , 85the thread-safe version 86.Fn ctime_r 87is not required to set 88.Va tzname . 89.Pp 90The 91.Fn localtime 92and 93.Fn gmtime 94functions return pointers to 95.Li tm 96structures, described below. 97.Fn localtime 98corrects for the time zone and any time zone adjustments 99(such as Daylight Saving Time in the United States). 100After filling in the 101.Li tm 102structure, 103.Fn localtime 104sets the 105.Fa tm_isdst Ns 'th 106element of 107.Va tzname 108to a pointer to an 109ASCII string that's the time zone abbreviation to be used with 110the return value of 111.Fn localtime . 112.Pp 113.Fn gmtime 114converts to Coordinated Universal Time. 115.Pp 116The 117.Fn localtime_r 118and 119.Fn gmtime_r 120functions convert the calendar time pointed to by 121.Fa clock 122into a broken-down time in exactly the same way as their non-reentrant 123counterparts, 124.Fn localtime 125and 126.Fn gmtime , 127but instead store the result directly into the structure pointed to by 128.Fa result . 129Unlike 130.Fn localtime , 131the reentrant version is not required to set 132.Va tzname . 133.Pp 134.Fn asctime 135converts a time value contained in a 136.Li tm 137structure to a string, 138as shown in the above example, 139and returns a pointer to the string. 140.Fn asctime_r 141uses the buffer pointed to by 142.Fa buf 143(which should contain at least 26 bytes) and then 144returns 145.Fa buf . 146.Pp 147.Fn mktime 148converts the broken-down time, 149expressed as local time, 150in the structure pointed to by 151.Fa tm 152into a calendar time value with the same encoding as that of the values 153returned by the 154.Fn time 155function. 156The original values of the 157.Fa tm_wday 158and 159.Fa tm_yday 160components of the structure are ignored, 161and the original values of the other components are not restricted 162to their normal ranges. 163(A positive or zero value for 164.Fa tm_isdst 165causes 166.Fn mktime 167to presume initially that summer time (for example, Daylight Saving Time 168in the U.S.A.)\& 169respectively, 170is or is not in effect for the specified time. 171A negative value for 172.Fa tm_isdst 173causes the 174.Fn mktime 175function to attempt to divine whether summer time is in effect 176for the specified time; in this case it does not use a consistent 177rule and may give a different answer when later 178presented with the same argument.) 179On successful completion, the values of the 180.Fa tm_wday 181and 182.Fa tm_yday 183components of the structure are set appropriately, 184and the other components are set to represent the specified calendar time, 185but with their values forced to their normal ranges; the final value of 186.Fa tm_mday 187is not set until 188.Fa tm_mon 189and 190.Fa tm_year 191are determined. 192.Fn mktime 193returns the specified calendar time; 194if the calendar time cannot be represented, 195it returns \-1. 196.Pp 197.Fn timelocal 198is a deprecated interface that is equivalent to calling 199.Fn mktime 200with a negative value for 201.Fa tm_isdst . 202.Pp 203.Fn timegm 204converts the broken-down time, as returned by 205.Fn gmtime , 206into a calendar time value with the same encoding as that of the values 207returned by the 208.Fn time 209function. 210.Pp 211.Fn difftime 212returns the difference between two calendar times, 213.Pf ( Fa time1 No \- Fa time0 ) , 214expressed in seconds. 215.Pp 216Declarations of all the functions and externals, and the 217.Li tm 218structure, are in the 219.In time.h 220header file. 221The structure (of type) 222.Li struct tm 223includes the following fields: 224.Bd -literal -offset indent 225 int tm_sec; /* seconds (0 \- 60) */ 226 int tm_min; /* minutes (0 \- 59) */ 227 int tm_hour; /* hours (0 \- 23) */ 228 int tm_mday; /* day of month (1 \- 31) */ 229 int tm_mon; /* month of year (0 \- 11) */ 230 int tm_year; /* year \- 1900 */ 231 int tm_wday; /* day of week (Sunday = 0) */ 232 int tm_yday; /* day of year (0 \- 365) */ 233 int tm_isdst; /* is summer time in effect? */ 234 long tm_gmtoff; /* offset from UTC in seconds */ 235 char *tm_zone; /* abbreviation of timezone name */ 236.Ed 237.Pp 238The 239.Fa tm_zone 240and 241.Fa tm_gmtoff 242fields exist, and are filled in by 243.Fn mktime , 244.Fn localtime , 245.Fn timegm , 246and 247.Fn gmtime , 248but are not standardized. 249There is no guarantee that these fields will continue to exist 250in this form and they may be altered or removed in a future release. 251.Pp 252.Fa tm_isdst 253is non-zero if summer time is in effect. 254.Pp 255.Fa tm_gmtoff 256is the offset (in seconds) of the time represented 257from UTC, with positive values indicating east 258of the Prime Meridian. 259.Sh RETURN VALUES 260The functions 261.Fn ctime , 262.Fn ctime_r , 263.Fn asctime , 264.Fn asctime_r , 265.Fn localtime , 266.Fn localtime_r , 267.Fn gmtime 268and 269.Fn gmtime_r 270return NULL on error. 271The function 272.Fn mktime 273returns \-1 on error. 274.Sh FILES 275.Bl -tag -width "/usr/share/zoneinfo/posixrules" -compact 276.It Pa /usr/share/zoneinfo 277time zone information directory 278.It Pa /etc/localtime 279local time zone file 280.It Pa /usr/share/zoneinfo/posixrules 281used with POSIX-style TZ's 282.It Pa /usr/share/zoneinfo/GMT 283for UTC leap seconds 284.El 285.Pp 286If 287.Pa /usr/share/zoneinfo/GMT 288is absent, 289UTC leap seconds are loaded from 290.Pa /usr/share/zoneinfo/posixrules . 291.Sh SEE ALSO 292.Xr getenv 3 , 293.Xr strftime 3 , 294.Xr time 3 , 295.Xr tzset 3 , 296.Xr tzfile 5 , 297.Xr zic 8 298.Sh STANDARDS 299The functions 300.Fn asctime , 301.Fn ctime , 302.Fn difftime , 303.Fn gmtime , 304.Fn localtime , 305and 306.Fn mktime 307conform to 308.St -ansiC . 309.Pp 310The functions 311.Fn asctime_r , 312.Fn ctime_r , 313.Fn gmtime_r , 314and 315.Fn localtime_r 316conform to 317.St -p1003.1-2008 . 318.Pp 319The functions 320.Fn timegm 321and 322.Fn timelocal 323are extensions to these standards. 324.Sh HISTORY 325A 326.Fn ctime 327function first appeared in 328.At v1 . 329.Pp 330The functions 331.Fn asctime , 332.Fn gmtime , 333and 334.Fn localtime 335first appeared in 336.At v5 , 337.Fn difftime 338and 339.Fn mktime 340in 341.Bx 4.3 Reno , 342and 343.Fn timegm 344and 345.Fn timelocal 346in SunOS 4.0. 347.Pp 348The functions 349.Fn asctime_r , 350.Fn ctime_r , 351.Fn gmtime_r , 352and 353.Fn localtime_r 354have been available since 355.Ox 2.5 . 356.Sh CAVEATS 357The return values 358of the non re-entrant functions 359point to static data; 360the data is overwritten by each call. 361The 362.Fa tm_zone 363field of a returned 364.Li struct tm 365points to a static array of characters, which 366will also be overwritten at the next call 367(and by calls to 368.Xr tzset 3 ) . 369.Pp 370.Fn asctime 371and 372.Fn ctime 373behave strangely for years before 1000 or after 9999. 374The 1989 and 1999 editions of the C Standard say 375that years from \-99 through 999 are converted without 376extra spaces, but this conflicts with longstanding 377tradition and with this implementation. 378Traditional implementations of these two functions are 379restricted to years in the range 1900 through 2099. 380To avoid this portability mess, new programs should use 381.Fn strftime 382instead. 383.Pp 384The default system time zone may be set by running 385.Dq Li zic -l timezone 386as the superuser. 387.Pp 388Avoid using out-of-range values with 389.Fn mktime 390when setting up lunch with promptness sticklers in Riyadh. 391.\" This file is in the public domain, so clarified as of 392.\" 2009-05-17 by Arthur David Olson. 393