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