1.\" $NetBSD: ctime.3,v 1.27 2003/04/16 13:34:58 wiz 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.In time.h 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. 136A negative value for 137.Fa tm_isdst 138causes the 139.Fn mktime 140function to attempt to divine whether summer time is in effect 141for the specified time.) 142On successful completion, the values of the 143.Fa tm_wday 144and 145.Fa tm_yday 146components of the structure are set appropriately, 147and the other components are set to represent the specified calendar time, 148but with their values forced to their normal ranges; the final value of 149.Fa tm_mday 150is not set until 151.Fa tm_mon 152and 153.Fa tm_year 154are determined. 155.Fn mktime 156returns the specified calendar time; if the calendar time cannot be 157represented, it returns -1. 158.Pp 159.Fn difftime 160returns the difference between two calendar times, 161.Fa ( time1 No - Fa time0 ) , 162expressed in seconds. 163.Pp 164The structure (of type) 165.Va "struct tm" 166includes the following fields: 167.Bd -literal -offset indent 168int tm_sec; /* seconds after the minute [0,61] */ 169int tm_min; /* minutes after the hour [0,59] */ 170int tm_hour; /* hours since midnight [0,23] */ 171int tm_mday; /* day of the month [1,31] */ 172int tm_mon; /* months since January [0,11] */ 173int tm_year; /* years since 1900 */ 174int tm_wday; /* day of week [0,6] (Sunday = 0) */ 175int tm_yday; /* day of year [0,365] (Jan 1 = 0) */ 176int tm_isdst; /* daylight savings flag */ 177long tm_gmtoff; /* offset from UTC in seconds */ 178char *tm_zone; /* abbreviation of timezone name */ 179.Ed 180.Pp 181The 182.Fa tm_zone 183and 184.Fa tm_gmtoff 185fields exist, and are filled in, only if arrangements to do 186so were made when the library containing these functions was 187created. 188There is no guarantee that these fields will continue to exist 189in this form in future releases of this code. 190.Pp 191.Fa tm_isdst 192is non-zero if summer time is in effect. 193.Pp 194.Fa tm_gmtoff 195is the offset (in seconds) of the time represented 196from UTC, with positive values indicating east 197of the Prime Meridian. 198.Sh FILES 199.Bl -tag -width /usr/share/zoneinfo/posixrules -compact 200.It Pa /etc/localtime 201local time zone file 202.It Pa /usr/share/zoneinfo 203time zone information directory 204.It Pa /usr/share/zoneinfo/posixrules 205used with POSIX-style TZ's 206.It Pa /usr/share/zoneinfo/GMT 207for UTC leap seconds 208.El 209.Pp 210If 211.Pa /usr/share/zoneinfo/GMT 212is absent, UTC leap seconds are loaded from 213.Pa /usr/share/zoneinfo/posixrules . 214.Sh SEE ALSO 215.Xr getenv 3 , 216.Xr strftime 3 , 217.Xr time 3 , 218.Xr tzset 3 , 219.Xr tzfile 5 220.Sh STANDARDS 221The 222.Fn ctime , 223.Fn difftime , 224.Fn asctime , 225.Fn localtime , 226.Fn gmtime 227and 228.Fn mktime 229functions conform to 230.St -ansiC 231The 232.Fn ctime_r , 233.Fn asctime_r , 234.Fn localtime_r 235and 236.Fn gmtime_r 237functions conform to 238.St -p1003.1c-95 . 239.Sh NOTES 240The return values point to static data; the data is overwritten by 241each call. 242The 243.Fa tm_zone 244field of a returned 245.Va "struct tm" 246points to a static array of characters, which will also be overwritten 247at the next call (and by calls to 248.Xr tzset 3 ) . 249.Pp 250Avoid using out-of-range values with 251.Fn mktime 252when setting up lunch with promptness sticklers in Riyadh. 253.\" @(#)newctime.3 7.14 254