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