Commit | Line | Data |
---|---|---|
637a994b KB |
1 | .\" Copyright (c) 1989 The Regents of the University of California. |
2 | .\" All rights reserved. | |
463d6749 | 3 | .\" |
637a994b KB |
4 | .\" This code is derived from software contributed to Berkeley by |
5 | .\" Arthur Olson. | |
463d6749 | 6 | .\" |
91cff1e1 | 7 | .\" %sccs.include.redist.man% |
637a994b | 8 | .\" |
04de8116 | 9 | .\" @(#)ctime.3 6.14 (Berkeley) %G% |
637a994b KB |
10 | .\" |
11 | .TH CTIME 3 "" | |
463d6749 | 12 | .SH NAME |
04de8116 | 13 | asctime, ctime, difftime, gmtime, localtime, mktime \- convert date and time to ASCII |
463d6749 KM |
14 | .SH SYNOPSIS |
15 | .nf | |
04de8116 KB |
16 | .ft B |
17 | extern char *tzname[2]; | |
18 | ||
19 | #include <sys/types.h> | |
20 | ||
21 | char *ctime(time_t *clock); | |
22 | ||
23 | double difftime(time_t time1, time_t time0); | |
24 | ||
25 | #include <time.h> | |
26 | ||
27 | char *asctime(struct tm *tm); | |
28 | ||
29 | struct tm *localtime(long *clock); | |
30 | ||
31 | struct tm *gmtime(long *clock); | |
32 | ||
33 | time_t mktime(struct tm *tm); | |
34 | .ft R | |
94c2eda1 | 35 | .fi |
463d6749 | 36 | .SH DESCRIPTION |
04de8116 KB |
37 | .IR Ctime , |
38 | .I gmtime | |
39 | and | |
637a994b | 40 | .I localtime |
04de8116 KB |
41 | all take as an argument a time value representing the time in seconds since |
42 | the Epoch (00:00:00 UTC, January 1, 1970; see | |
43 | .IR time (3)). | |
637a994b | 44 | .PP |
04de8116 KB |
45 | .I Localtime |
46 | converts the time value pointed at by | |
637a994b | 47 | .IR clock , |
04de8116 KB |
48 | and returns a pointer to a ``struct tm'' (described below) which contains |
49 | the broken-out time information for the value after adjusting for the current | |
50 | time zone (and any other factors such as Daylight Saving Time). | |
51 | Time zone adjustments are performed as specified by the | |
52 | .B TZ | |
53 | environmental variable (see | |
54 | .IR tzset (3)). | |
55 | .I Localtime | |
56 | uses | |
57 | .I tzset | |
58 | to initialize time conversion information if | |
59 | .I tzset | |
60 | has not already been called by the process. | |
637a994b | 61 | .PP |
04de8116 | 62 | After filling in the tm structure, |
637a994b KB |
63 | .I localtime |
64 | sets the | |
65 | .BR tm_isdst 'th | |
66 | element of | |
67 | .B tzname | |
04de8116 KB |
68 | to a pointer to an ASCII string that's the time zone abbreviation to be |
69 | used with | |
637a994b KB |
70 | .IR localtime 's |
71 | return value. | |
72 | .PP | |
04de8116 KB |
73 | .I Gmtime |
74 | similarly converts the time value, but without any time zone adjustment, | |
75 | and returns a pointer to a tm structure (described below). | |
76 | .PP | |
77 | .I Ctime | |
78 | adjusts the time value for the current time zone in the same manner as | |
79 | .IR localtime , | |
80 | and returns a pointer to a 26-character string of the form: | |
81 | .sp | |
82 | .RS | |
83 | Thu Nov 24 18:22:48 1986\en\e0 | |
84 | .RE | |
85 | .sp | |
86 | All the fields have constant width. | |
637a994b | 87 | .PP |
04de8116 KB |
88 | .I Asctime |
89 | converts a time value contained in a tm structure to a 26-character | |
90 | string, as shown in the above example, and returns a pointer to the string. | |
91 | .PP | |
92 | .I Mktime | |
93 | converts the broken-down time, expressed as local time, in the structure | |
94 | pointed to by tm into a time value with the same encoding as that of the | |
95 | values returned by the | |
96 | .IR time (3) | |
97 | function, that is, seconds from the Epoch, UTC. | |
463d6749 | 98 | .PP |
637a994b KB |
99 | The original values of the |
100 | .B tm_wday | |
101 | and | |
102 | .B tm_yday | |
04de8116 KB |
103 | components of the structure are ignored, and the original values of the |
104 | other components are not restricted to their normal ranges. | |
637a994b KB |
105 | (A positive or zero value for |
106 | .B tm_isdst | |
107 | causes | |
108 | .I mktime | |
04de8116 KB |
109 | to presume initially that summer time (for example, Daylight Saving Time) |
110 | is or is not in effect for the specified time, respectively. | |
637a994b KB |
111 | A negative value for |
112 | .B tm_isdst | |
113 | causes the | |
114 | .I mktime | |
04de8116 KB |
115 | function to attempt to divine whether summer time is in effect for the |
116 | specified time.) | |
117 | .PP | |
637a994b KB |
118 | On successful completion, the values of the |
119 | .B tm_wday | |
120 | and | |
121 | .B tm_yday | |
04de8116 KB |
122 | components of the structure are set appropriately, and the other components |
123 | are set to represent the specified calendar time, but with their values | |
124 | forced to their normal ranges; the final value of | |
637a994b KB |
125 | .B tm_mday |
126 | is not set until | |
127 | .B tm_mon | |
128 | and | |
129 | .B tm_year | |
130 | are determined. | |
04de8116 KB |
131 | .I Mktime |
132 | returns the specified calendar time; if the calendar time cannot be | |
133 | represented, it returns | |
637a994b KB |
134 | .BR -1 . |
135 | .PP | |
04de8116 | 136 | .I Difftime |
637a994b | 137 | returns the difference between two calendar times, |
04de8116 | 138 | .RI ( time1 |
637a994b | 139 | - |
04de8116 | 140 | .IR time0 ), |
637a994b KB |
141 | expressed in seconds. |
142 | .PP | |
04de8116 KB |
143 | External declarations as well as the tm structure definition are in the |
144 | ``<time.h>'' include file. | |
145 | The tm structure includes at least the following fields: | |
146 | .sp | |
8eafd288 | 147 | .RS |
463d6749 | 148 | .nf |
637a994b | 149 | .ta .5i +\w'long tm_gmtoff;\0\0'u |
04de8116 KB |
150 | int tm_sec; /\(** seconds (0 - 60) \(**/ |
151 | int tm_min; /\(** minutes (0 - 59) \(**/ | |
152 | int tm_hour; /\(** hours (0 - 23) \(**/ | |
153 | int tm_mday; /\(** day of month (1 - 31) \(**/ | |
154 | int tm_mon; /\(** month of year (0 - 11) \(**/ | |
155 | int tm_year; /\(** year \- 1900 \(**/ | |
156 | int tm_wday; /\(** day of week (Sunday = 0) \(**/ | |
157 | int tm_yday; /\(** day of year (0 - 365) \(**/ | |
158 | int tm_isdst; /\(** is summer time in effect? \(**/ | |
159 | char \(**tm_zone; /\(** abbreviation of timezone name \(**/ | |
160 | long tm_gmtoff; /\(** offset from UTC in seconds \(**/ | |
463d6749 KM |
161 | .fi |
162 | .RE | |
163 | .PP | |
04de8116 | 164 | .I Tm_isdst |
637a994b KB |
165 | is non-zero if summer time is in effect. |
166 | .PP | |
167 | .I Tm_gmtoff | |
04de8116 KB |
168 | is the offset (in seconds) of the time represented from UTC, with positive |
169 | values indicating east of the Prime Meridian. | |
94c2eda1 | 170 | .SH SEE ALSO |
04de8116 KB |
171 | date(1), gettimeofday(2), getenv(3), time(3), tzset(3), tzfile(5) |
172 | .SH BUGS | |
173 | Except for | |
174 | .I difftime | |
175 | and | |
176 | .IR mktime , | |
177 | these routines all return pointers to static data whose content is | |
178 | overwritten by each call. | |
179 | .PP | |
637a994b KB |
180 | The |
181 | .B tm_zone | |
04de8116 KB |
182 | field of a returned tm structure points to a static array of characters, |
183 | which will also be overwritten by any subsequent calls (as well as by | |
184 | subsequent calls to | |
185 | .IR tzset (3) | |
186 | and | |
187 | .IR tzsetwall (3)). | |
188 | .PP | |
189 | Use of the external variable | |
190 | .B tzname | |
191 | is discouraged; the | |
192 | .B tm_zone | |
193 | entry in the tm structure is preferred. | |
637a994b KB |
194 | .PP |
195 | Avoid using out-of-range values with | |
196 | .I mktime | |
197 | when setting up lunch with promptness sticklers in Riyadh. |