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