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.\" From: @(#)ctime.3 8.1 (Berkeley) 6/4/93 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.3 2006/05/26 19:39:37 swildner Exp $ 37.\" 38.Dd January 2, 1999 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 , 90January 1, 1970; 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 other factors such as Daylight Saving Time). 102Time zone adjustments are performed as specified by the 103.Ev TZ 104environment variable (see 105.Xr tzset 3 ) . 106The function 107.Fn localtime 108uses 109.Xr tzset 3 110to initialize time conversion information if 111.Xr tzset 3 112has not already been called by the process. 113.Pp 114After filling in the tm structure, 115.Fn localtime 116sets the 117.Fa tm_isdst Ns 'th 118element of 119.Fa tzname 120to a pointer to an 121.Tn ASCII 122string that's the time zone abbreviation to be 123used with 124.Fn localtime Ns 's 125return value. 126.Pp 127The function 128.Fn gmtime 129similarly converts the time value, but without any time zone adjustment, 130and returns a pointer to a tm structure (described below). 131.Pp 132The 133.Fn ctime 134function 135adjusts the time value for the current time zone in the same manner as 136.Fn localtime , 137and returns a pointer to a 26-character string of the form: 138.Bd -literal -offset indent 139Thu Nov 24 18:22:48 1986\en\e0 140.Ed 141.Pp 142All the fields have constant width. 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. 234The 235.Fa tm_isdst 236and 237.Fa tm_gmtoff 238members are forced to zero by 239.Fn timegm . ) 240.Pp 241On successful completion, the values of the 242.Fa tm_wday 243and 244.Fa tm_yday 245components of the structure are set appropriately, and the other components 246are set to represent the specified calendar time, but with their values 247forced to their normal ranges; the final value of 248.Fa tm_mday 249is not set until 250.Fa tm_mon 251and 252.Fa tm_year 253are determined. 254The 255.Fn mktime 256function 257returns the specified calendar time; if the calendar time cannot be 258represented, it returns \-1; 259.Pp 260The 261.Fn difftime 262function 263returns the difference between two calendar times, 264.Pf ( Fa time1 265- 266.Fa time0 ) , 267expressed in seconds. 268.Pp 269External declarations as well as the tm structure definition are in the 270.In time.h 271include file. 272The tm structure includes at least the following fields: 273.Bd -literal -offset indent 274int tm_sec; /\(** seconds (0 - 60) \(**/ 275int tm_min; /\(** minutes (0 - 59) \(**/ 276int tm_hour; /\(** hours (0 - 23) \(**/ 277int tm_mday; /\(** day of month (1 - 31) \(**/ 278int tm_mon; /\(** month of year (0 - 11) \(**/ 279int tm_year; /\(** year \- 1900 \(**/ 280int tm_wday; /\(** day of week (Sunday = 0) \(**/ 281int tm_yday; /\(** day of year (0 - 365) \(**/ 282int tm_isdst; /\(** is summer time in effect? \(**/ 283char \(**tm_zone; /\(** abbreviation of timezone name \(**/ 284long tm_gmtoff; /\(** offset from UTC in seconds \(**/ 285.Ed 286.Pp 287The 288field 289.Fa tm_isdst 290is non-zero if summer time is in effect. 291.Pp 292The field 293.Fa tm_gmtoff 294is the offset (in seconds) of the time represented from 295.Tn UTC , 296with positive 297values indicating east of the Prime Meridian. 298.Sh SEE ALSO 299.Xr date 1 , 300.Xr gettimeofday 2 , 301.Xr getenv 3 , 302.Xr time 3 , 303.Xr tzset 3 , 304.Xr tzfile 5 305.Sh STANDARDS 306The 307.Fn asctime , 308.Fn ctime , 309.Fn difftime , 310.Fn gmtime , 311.Fn localtime , 312and 313.Fn mktime 314functions conform to 315.St -isoC , 316and conform to 317.St -p1003.1-96 318provided the selected local timezone does not contain a leap-second table 319(see 320.Xr zic 8 ) . 321.Pp 322The 323.Fn asctime_r , 324.Fn ctime_r , 325.Fn gmtime_r , 326and 327.Fn localtime_r 328functions are expected to conform to 329.St -p1003.1-96 330(again provided the selected local timezone does not contain a leap-second 331table). 332.Pp 333The 334.Fn timegm 335function is not specified by any standard; its function cannot be 336completely emulated using the standard functions described above. 337.Sh HISTORY 338This manual page is derived from 339the time package contributed to Berkeley by 340.An Arthur Olson 341and which appeared in 342.Bx 4.3 . 343.Sh BUGS 344Except for 345.Fn difftime , 346.Fn mktime , 347and the 348.Fn \&_r 349variants of the other functions, 350these functions leaves their result in an internal static object and return 351a pointer to that object. 352Subsequent calls to these 353function will modify the same object. 354.Pp 355The C Standard provides no mechanism for a program to modify its current 356local timezone setting, and the 357.Tn POSIX Ns No \&-standard 358method is not reentrant. (However, thread-safe implementations are provided 359in the 360.Tn POSIX 361threaded environment.) 362.Pp 363The 364.Va tm_zone 365field of a returned 366.Vt tm 367structure points to a static array of characters, 368which will also be overwritten by any subsequent calls (as well as by 369subsequent calls to 370.Xr tzset 3 371and 372.Xr tzsetwall 3 ) . 373.Pp 374Use of the external variable 375.Fa tzname 376is discouraged; the 377.Fa tm_zone 378entry in the tm structure is preferred. 379