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