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