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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)newctime.3 8.2 35.\" $FreeBSD: src/lib/libc/stdtime/ctime.3,v 1.11.2.7 2003/05/23 23:53:40 keramida Exp $ 36.\" $DragonFly: src/lib/libc/stdtime/ctime.3,v 1.4 2008/10/19 20:15:58 swildner Exp $ 37.\" 38.Dd October 19, 2008 39.Dt CTIME 3 40.Os 41.Sh NAME 42.Nm asctime , 43.Nm asctime_r , 44.Nm ctime , 45.Nm ctime_r , 46.Nm difftime , 47.Nm gmtime , 48.Nm gmtime_r , 49.Nm localtime , 50.Nm localtime_r , 51.Nm mktime , 52.Nm timegm 53.Nd transform binary date and time values 54.Sh LIBRARY 55.Lb libc 56.Sh SYNOPSIS 57.In time.h 58.Vt extern char *tzname[2] ; 59.Ft char * 60.Fn ctime "const time_t *clock" 61.Ft double 62.Fn difftime "time_t time1" "time_t time0" 63.Ft char * 64.Fn asctime "const struct tm *tm" 65.Ft struct tm * 66.Fn localtime "const time_t *clock" 67.Ft struct tm * 68.Fn gmtime "const time_t *clock" 69.Ft time_t 70.Fn mktime "struct tm *tm" 71.Ft time_t 72.Fn timegm "struct tm *tm" 73.Ft char * 74.Fn ctime_r "const time_t *clock" "char *buf" 75.Ft struct tm * 76.Fn localtime_r "const time_t *clock" "struct tm *result" 77.Ft struct tm * 78.Fn gmtime_r "const time_t *clock" "struct tm *result" 79.Ft char * 80.Fn asctime_r "const struct tm *tm" "char *buf" 81.Sh DESCRIPTION 82The functions 83.Fn ctime , 84.Fn gmtime 85and 86.Fn localtime 87all take as an argument a time value representing the time in seconds since 88the Epoch (00:00:00 89.Tn UTC , 901970-01-01; see 91.Xr time 3 ) . 92.Pp 93The function 94.Fn localtime 95converts the time value pointed at by 96.Fa clock , 97and returns a pointer to a 98.Dq Fa struct tm 99(described below) which contains 100the broken-out time information for the value after adjusting for the current 101time zone and any time zone adjustments. 102Time zone adjustments are performed as specified by the 103.Ev TZ 104environment variable (see 105.Xr tzset 3 ) . 106.Pp 107After filling in the tm structure, 108.Fn localtime 109sets the 110.Fa tm_isdst Ns 'th 111element of 112.Fa tzname 113to a pointer to an 114.Tn ASCII 115string that's the time zone abbreviation to be 116used with 117.Fn localtime Ns 's 118return value. 119.Pp 120The function 121.Fn gmtime 122similarly converts the time value, but without any time zone adjustment, 123and returns a pointer to a tm structure (described below). 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 string of the form: 131.Bd -literal -offset indent 132Thu Nov 24 18:22:48 1986\en\e0 133.Ed 134.Pp 135Years requiring fewer than four characters are padded with leading zeroes. 136For years longer than four characters, the string is of the form 137.Bd -literal -offset indent 138Thu Nov 24 18:22:48 81986\en\e0 139.Ed 140.Pp 141with five spaces before the year. 142These unusual formats are designed to make it less likely that older 143software that expects exactly 26 bytes of output will mistakenly output 144misleading values for out-of-range years. 145.Pp 146The 147.Fn ctime_r 148function 149provides the same functionality as 150.Fn ctime 151except the caller must provide the output buffer 152.Fa buf 153to store the result, which must be at least 26 characters long. 154The 155.Fn localtime_r 156and 157.Fn gmtime_r 158functions 159provide the same functionality as 160.Fn localtime 161and 162.Fn gmtime 163respectively, except the caller must provide the output buffer 164.Fa result . 165.Pp 166The 167.Fn asctime 168function 169converts the broken down time in the structure 170.Fa tm 171pointed at by 172.Fa *tm 173to the form 174shown in the example above. 175.Pp 176The 177.Fn asctime_r 178function 179provides the same functionality as 180.Fn asctime 181except the caller provide the output buffer 182.Fa buf 183to store the result, which must be at least 26 characters long. 184.Pp 185The functions 186.Fn mktime 187and 188.Fn timegm 189convert the broken-down time in the structure 190pointed to by tm into a time value with the same encoding as that of the 191values returned by the 192.Xr time 3 193function (that is, seconds from the Epoch, 194.Tn UTC ) . 195The 196.Fn mktime 197function 198interprets the input structure according to the current timezone setting 199(see 200.Xr tzset 3 ) . 201The 202.Fn timegm 203function 204interprets the input structure as representing Universal Coordinated Time 205.Pq Tn UTC . 206.Pp 207The original values of the 208.Fa tm_wday 209and 210.Fa tm_yday 211components of the structure are ignored, and the original values of the 212other components are not restricted to their normal ranges, and will be 213normalized if needed. 214For example, 215October 40 is changed into November 9, 216a 217.Fa tm_hour 218of \-1 means 1 hour before midnight, 219.Fa tm_mday 220of 0 means the day preceding the current month, and 221.Fa tm_mon 222of \-2 means 2 months before January of 223.Fa tm_year . 224(A positive or zero value for 225.Fa tm_isdst 226causes 227.Fn mktime 228to presume initially that summer time (for example, Daylight Saving Time) 229is or is not in effect for the specified time, respectively. 230A negative value for 231.Fa tm_isdst 232causes the 233.Fn mktime 234function to attempt to divine whether summer time is in effect for the 235specified time; in this case it does not use a consistent 236rule and may give a different answer when later 237presented with the same argument. 238The 239.Fa tm_isdst 240and 241.Fa tm_gmtoff 242members are forced to zero by 243.Fn timegm . ) 244.Pp 245On successful completion, the values of the 246.Fa tm_wday 247and 248.Fa tm_yday 249components of the structure are set appropriately, and the other components 250are set to represent the specified calendar time, but with their values 251forced to their normal ranges; the final value of 252.Fa tm_mday 253is not set until 254.Fa tm_mon 255and 256.Fa tm_year 257are determined. 258The 259.Fn mktime 260function 261returns the specified calendar time; if the calendar time cannot be 262represented, it returns \-1; 263.Pp 264The 265.Fn difftime 266function 267returns the difference between two calendar times, 268.Pf ( Fa time1 269- 270.Fa time0 ) , 271expressed in seconds. 272.Pp 273External declarations as well as the tm structure definition are in the 274.In time.h 275include file. 276The tm structure includes at least the following fields: 277.Bd -literal -offset indent 278int tm_sec; /\(** seconds (0 - 60) \(**/ 279int tm_min; /\(** minutes (0 - 59) \(**/ 280int tm_hour; /\(** hours (0 - 23) \(**/ 281int tm_mday; /\(** day of month (1 - 31) \(**/ 282int tm_mon; /\(** month of year (0 - 11) \(**/ 283int tm_year; /\(** year \- 1900 \(**/ 284int tm_wday; /\(** day of week (Sunday = 0) \(**/ 285int tm_yday; /\(** day of year (0 - 365) \(**/ 286int tm_isdst; /\(** is summer time in effect? \(**/ 287char \(**tm_zone; /\(** abbreviation of timezone name \(**/ 288long tm_gmtoff; /\(** offset from UTC in seconds \(**/ 289.Ed 290.Pp 291The 292field 293.Fa tm_isdst 294is non-zero if summer time is in effect. 295.Pp 296The field 297.Fa tm_gmtoff 298is the offset (in seconds) of the time represented from 299.Tn UTC , 300with positive 301values indicating east of the Prime Meridian. 302.Sh COMPATIBILITY 303The 304.Fn asctime 305and 306.Fn ctime 307functions 308behave strangely for years before 1000 or after 9999. 309The 1989 and 1999 editions of the C Standard say 310that years from -99 through 999 are converted without 311extra spaces, but this conflicts with longstanding 312tradition and with this implementation. 313Traditional implementations of these two functions are 314restricted to years in the range 1900 through 2099. 315To avoid this portability mess, new programs should use 316.Xr strftime 3 317instead. 318.Sh SEE ALSO 319.Xr date 1 , 320.Xr gettimeofday 2 , 321.Xr getenv 3 , 322.Xr strftime 3 , 323.Xr time 3 , 324.Xr tzset 3 , 325.Xr tzfile 5 326.Sh STANDARDS 327The 328.Fn asctime , 329.Fn ctime , 330.Fn difftime , 331.Fn gmtime , 332.Fn localtime , 333and 334.Fn mktime 335functions conform to 336.St -isoC , 337and conform to 338.St -p1003.1-96 339provided the selected local timezone does not contain a leap-second table 340(see 341.Xr zic 8 ) . 342.Pp 343The 344.Fn asctime_r , 345.Fn ctime_r , 346.Fn gmtime_r , 347and 348.Fn localtime_r 349functions are expected to conform to 350.St -p1003.1-96 351(again provided the selected local timezone does not contain a leap-second 352table). 353.Pp 354The 355.Fn timegm 356function is not specified by any standard; its function cannot be 357completely emulated using the standard functions described above. 358.Sh HISTORY 359This manual page is derived from 360the time package contributed to Berkeley by 361.An Arthur Olson 362and which appeared in 363.Bx 4.3 . 364.Sh BUGS 365Except for 366.Fn difftime , 367.Fn mktime , 368and the 369.Fn \&_r 370variants of the other functions, 371these functions leaves their result in an internal static object and return 372a pointer to that object. 373Subsequent calls to these 374function will modify the same object. 375.Pp 376The C Standard provides no mechanism for a program to modify its current 377local timezone setting, and the 378.Tn POSIX Ns No \&-standard 379method is not reentrant. (However, thread-safe implementations are provided 380in the 381.Tn POSIX 382threaded environment.) 383.Pp 384The 385.Va tm_zone 386field of a returned 387.Vt tm 388structure points to a static array of characters, 389which will also be overwritten by any subsequent calls (as well as by 390subsequent calls to 391.Xr tzset 3 392and 393.Xr tzsetwall 3 ) . 394.Pp 395Use of the external variable 396.Fa tzname 397is discouraged; the 398.Fa tm_zone 399entry in the tm structure is preferred. 400