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