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