1.\" $NetBSD: ctime.3,v 1.25 2002/02/07 07:00:34 ross Exp $ 2.Dd March 31, 2001 3.Dt CTIME 3 4.Os 5.Sh NAME 6.Nm asctime , 7.Nm asctime_r , 8.Nm ctime , 9.Nm ctime_r , 10.Nm difftime , 11.Nm gmtime , 12.Nm gmtime_r , 13.Nm localtime , 14.Nm localtime_r , 15.Nm mktime 16.Nd convert date and time to ASCII 17.Sh LIBRARY 18.Lb libc 19.Sh SYNOPSIS 20.Fd #include \*[Lt]time.h\*[Gt] 21.Dv extern char *tzname[2]; 22.Ft char * 23.Fn ctime "const time_t *clock" 24.Ft char * 25.Fn ctime_r "const time_t *clock" "char *buf" 26.Ft double 27.Fn difftime "time_t time1" "time_t time0" 28.Ft char * 29.Fn asctime "const struct tm *tm" 30.Ft char * 31.Fn asctime_r "const struct tm restrict tm" "char * restrict buf" 32.Ft struct tm * 33.Fn localtime "const time_t *clock" 34.Ft struct tm * 35.Fn localtime_r "const time_t * restrict clock" "struct tm * restrict result" 36.Ft struct tm * 37.Fn gmtime "const time_t *clock" 38.Ft struct tm * 39.Fn gmtime_r "const time_t * restrict clock" "struct tm * restrict result" 40.Ft time_t 41.Fn mktime "struct tm *tm" 42.Sh DESCRIPTION 43.Fn ctime 44converts a long integer, pointed to by 45.Fa clock , 46representing the time in seconds since 00:00:00 UTC, 1970-01-01, 47and returns a pointer to a 26-character string of the form 48.Dl Thu Nov 24 18:22:48 1986\en\e0 49All the fields have constant width. 50.Pp 51The 52.Fn ctime_r 53function provides the same functionality as 54.Fn ctime 55differing in that the caller must supply a buffer area 56.Fa buf 57with a size of at least 26 bytes, in which the result is stored. 58.Pp 59.Fn localtime 60and 61.Fn gmtime 62return pointers to 63.Va tm 64structures, described below. 65.Fn localtime 66corrects for the time zone and any time zone adjustments 67(such as Daylight Saving Time in the U.S.A.). 68After filling in the 69.Va tm 70structure, 71.Fn localtime 72sets the 73.Fa tm_isdst Ns 'th 74element of 75.Fa tzname 76to a pointer to an 77ASCII string that's the time zone abbreviation to be used with 78.Fn localtime Ns 's 79return value. 80.Pp 81.Fn gmtime 82converts to Coordinated Universal Time. 83.Pp 84The 85.Fn gmtime_r 86and 87.Fn localtime_r 88functions provide the same functionality as 89.Fn gmtime 90and 91.Fn localtime 92differing in that the caller must supply a buffer area 93.Fa result 94in which the result is stored; also, 95.Fn localtime_r 96does not imply initialization of the local time conversion information; 97the application may need to do so by calling 98.Xr tzset 3 . 99.Pp 100.Fn asctime 101converts a time value contained in a 102.Va tm 103structure to a 26-character string, as shown in the above example, 104and returns a pointer to the string. 105.Pp 106The 107.Fn asctime_r 108function provides the same functionality as 109.Fn asctime 110differing in that the caller must supply a buffer area 111.Fa buf 112with a size of at least 26 bytes, in which the result is stored. 113.Pp 114.Fn mktime 115converts the broken-down time, expressed as local time, 116in the structure pointed to by 117.Fa tm 118into a calendar time value with the same encoding as that of the values 119returned by the 120.Xr time 3 121function. 122The original values of the 123.Fa tm_wday 124and 125.Fa tm_yday 126components of the structure are ignored, 127and the original values of the other components are not restricted 128to their normal ranges. 129(A positive or zero value for 130.Fa tm_isdst 131causes 132.Fn mktime 133to presume initially that summer time (for example, Daylight Saving Time 134in the U.S.A.) respectively, 135is or is not in effect for the specified time. A negative value for 136.Fa tm_isdst 137causes the 138.Fn mktime 139function to attempt to divine whether summer time is in effect 140for the specified time.) 141On successful completion, the values of the 142.Fa tm_wday 143and 144.Fa tm_yday 145components of the structure are set appropriately, 146and the other components are set to represent the specified calendar time, 147but with their values forced to their normal ranges; the final value of 148.Fa tm_mday 149is not set until 150.Fa tm_mon 151and 152.Fa tm_year 153are determined. 154.Fn mktime 155returns the specified calendar time; if the calendar time cannot be 156represented, it returns -1. 157.Pp 158.Fn difftime 159returns the difference between two calendar times, 160.Fa ( time1 No - Fa time0 ) , 161expressed in seconds. 162.Pp 163The structure (of type) 164.Va "struct tm" 165includes the following fields: 166.Bd -literal -offset indent 167int tm_sec; /* seconds after the minute [0,61] */ 168int tm_min; /* minutes after the hour [0,59] */ 169int tm_hour; /* hours since midnight [0,23] */ 170int tm_mday; /* day of the month [1,31] */ 171int tm_mon; /* months since January [0,11] */ 172int tm_year; /* years since 1900 */ 173int tm_wday; /* day of week [0,6] (Sunday = 0) */ 174int tm_yday; /* day of year [0,365] (Jan 1 = 0) */ 175int tm_isdst; /* daylight savings flag */ 176long tm_gmtoff; /* offset from UTC in seconds */ 177char *tm_zone; /* abbreviation of timezone name */ 178.Ed 179.Pp 180The 181.Fa tm_zone 182and 183.Fa tm_gmtoff 184fields exist, and are filled in, only if arrangements to do 185so were made when the library containing these functions was 186created. 187There is no guarantee that these fields will continue to exist 188in this form in future releases of this code. 189.Pp 190.Fa tm_isdst 191is non-zero if summer time is in effect. 192.Pp 193.Fa tm_gmtoff 194is the offset (in seconds) of the time represented 195from UTC, with positive values indicating east 196of the Prime Meridian. 197.Sh FILES 198.Bl -tag -width /usr/share/zoneinfo/posixrules -compact 199.It Pa /etc/localtime 200local time zone file 201.It Pa /usr/share/zoneinfo 202time zone information directory 203.It Pa /usr/share/zoneinfo/posixrules 204used with POSIX-style TZ's 205.It Pa /usr/share/zoneinfo/GMT 206for UTC leap seconds 207.El 208.Pp 209If 210.Pa /usr/share/zoneinfo/GMT 211is absent, UTC leap seconds are loaded from 212.Pa /usr/share/zoneinfo/posixrules . 213.Sh SEE ALSO 214.Xr getenv 3 , 215.Xr strftime 3 , 216.Xr time 3 , 217.Xr tzset 3 , 218.Xr tzfile 5 219.Sh STANDARDS 220The 221.Fn ctime , 222.Fn difftime , 223.Fn asctime , 224.Fn localtime , 225.Fn gmtime 226and 227.Fn mktime 228functions conform to 229.St -ansiC 230The 231.Fn ctime_r , 232.Fn asctime_r , 233.Fn localtime_r 234and 235.Fn gmtime_r 236functions conform to 237.St -p1003.1c-95 . 238.Sh NOTES 239The return values point to static data; the data is overwritten by 240each call. The 241.Fa tm_zone 242field of a returned 243.Va "struct tm" 244points to a static array of characters, which will also be overwritten 245at the next call (and by calls to 246.Xr tzset 3 ) . 247.Pp 248Avoid using out-of-range values with 249.Fn mktime 250when setting up lunch with promptness sticklers in Riyadh. 251.\" @(#)newctime.3 7.14 252