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. 200(A positive or zero value for 201.Fa tm_isdst 202causes 203.Fn mktime 204to presume initially that summer time (for example, Daylight Saving Time) 205is or is not in effect for the specified time, respectively. 206A negative value for 207.Fa tm_isdst 208causes the 209.Fn mktime 210function to attempt to divine whether summer time is in effect for the 211specified time. 212The 213.Fa tm_isdst 214and 215.Fa tm_gmtoff 216members are forced to zero by 217.Fn timegm . ) 218.Pp 219On successful completion, the values of the 220.Fa tm_wday 221and 222.Fa tm_yday 223components of the structure are set appropriately, and the other components 224are set to represent the specified calendar time, but with their values 225forced to their normal ranges; the final value of 226.Fa tm_mday 227is not set until 228.Fa tm_mon 229and 230.Fa tm_year 231are determined. 232.Fn Mktime 233returns the specified calendar time; if the calendar time cannot be 234represented, it returns \-1; 235.Pp 236The 237.Fn difftime 238function 239returns the difference between two calendar times, 240.Pf ( Fa time1 241- 242.Fa time0 ) , 243expressed in seconds. 244.Pp 245External declarations as well as the tm structure definition are in the 246.Aq Pa time.h 247include file. 248The tm structure includes at least the following fields: 249.Bd -literal -offset indent 250int tm_sec; /\(** seconds (0 - 60) \(**/ 251int tm_min; /\(** minutes (0 - 59) \(**/ 252int tm_hour; /\(** hours (0 - 23) \(**/ 253int tm_mday; /\(** day of month (1 - 31) \(**/ 254int tm_mon; /\(** month of year (0 - 11) \(**/ 255int tm_year; /\(** year \- 1900 \(**/ 256int tm_wday; /\(** day of week (Sunday = 0) \(**/ 257int tm_yday; /\(** day of year (0 - 365) \(**/ 258int tm_isdst; /\(** is summer time in effect? \(**/ 259char \(**tm_zone; /\(** abbreviation of timezone name \(**/ 260long tm_gmtoff; /\(** offset from UTC in seconds \(**/ 261.Ed 262.Pp 263The 264field 265.Fa tm_isdst 266is non-zero if summer time is in effect. 267.Pp 268The field 269.Fa tm_gmtoff 270is the offset (in seconds) of the time represented from 271.Tn UTC , 272with positive 273values indicating east of the Prime Meridian. 274.Sh SEE ALSO 275.Xr date 1 , 276.Xr gettimeofday 2 , 277.Xr getenv 3 , 278.Xr time 3 , 279.Xr tzset 3 , 280.Xr tzfile 5 281.Sh STANDARDS 282The 283.Fn asctime , 284.Fn ctime , 285.Fn difftime , 286.Fn gmtime , 287.Fn localtime , 288and 289.Fn mktime 290functions conform to 291.St -isoC , 292and conform to 293.St -p1003.1-96 294provided the selected local timezone does not contain a leap-second table 295(see 296.Xr zic 8 ) . 297.Pp 298The 299.Fn asctime_r , 300.Fn ctime_r , 301.Fn gmtime_r , 302and 303.Fn localtime_r 304functions are expected to conform to 305.St -p1003.1-96 306(again provided the selected local timezone does not contain a leap-second 307table). 308.Pp 309The 310.Fn timegm 311function is not specified by any standard; its function cannot be 312completely emulated using the standard functions described above. 313.Sh HISTORY 314This manual page is derived from 315the time package contributed to Berkeley by 316.An Arthur Olson 317and which appeared in 318.Bx 4.3 . 319.Sh BUGS 320Except for 321.Fn difftime , 322.Fn mktime , 323and the 324.Fn \&_r 325variants of the other functions, 326these functions leaves their result in an internal static object and return 327a pointer to that object. 328Subsequent calls to these 329function will modify the same object. 330.Pp 331The C Standard provides no mechanism for a program to modify its current 332local timezone setting, and the 333.Tn POSIX Ns No \&-standard 334method is not reentrant. (However, thread-safe implementations are provided 335in the 336.Tn POSIX 337threaded environment.) 338.Pp 339The 340.Fa tm_zone 341field of a returned tm structure points to a static array of characters, 342which will also be overwritten by any subsequent calls (as well as by 343subsequent calls to 344.Xr tzset 3 345and 346.Xr tzsetwall 3 ) . 347.Pp 348Use of the external variable 349.Fa tzname 350is discouraged; the 351.Fa tm_zone 352entry in the tm structure is preferred. 353