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 BSD 4.3 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.Fd #include <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's 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 143.Fn ctime_r 144provides the same functionality as 145.Fn ctime 146except the caller must provide the output buffer 147.Fa buf 148to store the result, which must be at least 26 characters long. 149.Fn localtime_r 150and 151.Fn gmtime_r 152provide the same functionality as 153.Fn localtime 154and 155.Fn gmtime 156respectively, except the caller must provide the output buffer 157.Fa result . 158.Pp 159The 160.Fn asctime 161function 162converts the broken down time in the structure 163.Fa tm 164pointed at by 165.Fa *tm 166to the form 167shown in the example above. 168.Pp 169.Fn asctime_r 170provides the same functionality as 171.Fn asctime 172except the caller provide the output buffer 173.Fa buf 174to store the result, which must be at least 26 characters long. 175.Pp 176The functions 177.Fn mktime 178and 179.Fn timegm 180convert the broken-down time in the structure 181pointed to by tm into a time value with the same encoding as that of the 182values returned by the 183.Xr time 3 184function (that is, seconds from the Epoch, 185.Tn UTC ) . 186.Fn mktime 187interprets the input structure according to the current timezone setting 188(see 189.Xr tzset 3 ) . 190.Fn timegm 191interprets the input structure as representing Universal Coordinated Time 192.Pq Tn UTC . 193.Pp 194The original values of the 195.Fa tm_wday 196and 197.Fa tm_yday 198components of the structure are ignored, and the original values of the 199other components are not restricted to their normal ranges, and will be 200normalized if needed. 201For example, 202October 40 is changed into November 9, 203a 204.Fa tm_hour 205of \-1 means 1 hour before midnight, 206.Fa tm_mday 207of 0 means the day preceding the current month, and 208.Fa tm_mon 209of \-2 means 2 months before January of 210.Fa tm_year . 211(A positive or zero value for 212.Fa tm_isdst 213causes 214.Fn mktime 215to presume initially that summer time (for example, Daylight Saving Time) 216is or is not in effect for the specified time, respectively. 217A negative value for 218.Fa tm_isdst 219causes the 220.Fn mktime 221function to attempt to divine whether summer time is in effect for the 222specified time. 223The 224.Fa tm_isdst 225and 226.Fa tm_gmtoff 227members are forced to zero by 228.Fn timegm . ) 229.Pp 230On successful completion, the values of the 231.Fa tm_wday 232and 233.Fa tm_yday 234components of the structure are set appropriately, and the other components 235are set to represent the specified calendar time, but with their values 236forced to their normal ranges; the final value of 237.Fa tm_mday 238is not set until 239.Fa tm_mon 240and 241.Fa tm_year 242are determined. 243.Fn Mktime 244returns the specified calendar time; if the calendar time cannot be 245represented, it returns \-1; 246.Pp 247The 248.Fn difftime 249function 250returns the difference between two calendar times, 251.Pf ( Fa time1 252- 253.Fa time0 ) , 254expressed in seconds. 255.Pp 256External declarations as well as the tm structure definition are in the 257.Aq Pa time.h 258include file. 259The tm structure includes at least the following fields: 260.Bd -literal -offset indent 261int tm_sec; /\(** seconds (0 - 60) \(**/ 262int tm_min; /\(** minutes (0 - 59) \(**/ 263int tm_hour; /\(** hours (0 - 23) \(**/ 264int tm_mday; /\(** day of month (1 - 31) \(**/ 265int tm_mon; /\(** month of year (0 - 11) \(**/ 266int tm_year; /\(** year \- 1900 \(**/ 267int tm_wday; /\(** day of week (Sunday = 0) \(**/ 268int tm_yday; /\(** day of year (0 - 365) \(**/ 269int tm_isdst; /\(** is summer time in effect? \(**/ 270char \(**tm_zone; /\(** abbreviation of timezone name \(**/ 271long tm_gmtoff; /\(** offset from UTC in seconds \(**/ 272.Ed 273.Pp 274The 275field 276.Fa tm_isdst 277is non-zero if summer time is in effect. 278.Pp 279The field 280.Fa tm_gmtoff 281is the offset (in seconds) of the time represented from 282.Tn UTC , 283with positive 284values indicating east of the Prime Meridian. 285.Sh SEE ALSO 286.Xr date 1 , 287.Xr gettimeofday 2 , 288.Xr getenv 3 , 289.Xr time 3 , 290.Xr tzset 3 , 291.Xr tzfile 5 292.Sh STANDARDS 293The 294.Fn asctime , 295.Fn ctime , 296.Fn difftime , 297.Fn gmtime , 298.Fn localtime , 299and 300.Fn mktime 301functions conform to 302.St -isoC , 303and conform to 304.St -p1003.1-96 305provided the selected local timezone does not contain a leap-second table 306(see 307.Xr zic 8 ) . 308.Pp 309The 310.Fn asctime_r , 311.Fn ctime_r , 312.Fn gmtime_r , 313and 314.Fn localtime_r 315functions are expected to conform to 316.St -p1003.1-96 317(again provided the selected local timezone does not contain a leap-second 318table). 319.Pp 320The 321.Fn timegm 322function is not specified by any standard; its function cannot be 323completely emulated using the standard functions described above. 324.Sh HISTORY 325This manual page is derived from 326the time package contributed to Berkeley by 327.An Arthur Olson 328and which appeared in 329.Bx 4.3 . 330.Sh BUGS 331Except for 332.Fn difftime , 333.Fn mktime , 334and the 335.Fn \&_r 336variants of the other functions, 337these functions leaves their result in an internal static object and return 338a pointer to that object. 339Subsequent calls to these 340function will modify the same object. 341.Pp 342The C Standard provides no mechanism for a program to modify its current 343local timezone setting, and the 344.Tn POSIX Ns No \&-standard 345method is not reentrant. (However, thread-safe implementations are provided 346in the 347.Tn POSIX 348threaded environment.) 349.Pp 350The 351.Fa tm_zone 352field of a returned tm structure points to a static array of characters, 353which will also be overwritten by any subsequent calls (as well as by 354subsequent calls to 355.Xr tzset 3 356and 357.Xr tzsetwall 3 ) . 358.Pp 359Use of the external variable 360.Fa tzname 361is discouraged; the 362.Fa tm_zone 363entry in the tm structure is preferred. 364