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