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