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