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