projects / OpenSPARC-T2-DV / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 design and verification files.
[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / lib / module-time.html
CommitLineData
86530b38
AT		 1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<link rel="STYLESHEET" href="lib.css" type='text/css' />
5<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
6<link rel='start' href='../index.html' title='Python Documentation Index' />
7<link rel="first" href="lib.html" title='Python Library Reference' />
8<link rel='contents' href='contents.html' title="Contents" />
9<link rel='index' href='genindex.html' title='Index' />
10<link rel='last' href='about.html' title='About this document...' />
11<link rel='help' href='about.html' title='About this document...' />
12<link rel="next" href="module-sched.html" />
13<link rel="prev" href="module-datetime.html" />
14<link rel="parent" href="allos.html" />
15<link rel="next" href="module-sched.html" />
16<meta name='aesop' content='information' />
17<title>6.11 time -- Time access and conversions</title>
18</head>
19<body>
20<DIV CLASS="navigation">
21<div id='top-navigation-panel' xml:id='top-navigation-panel'>
22<table align="center" width="100%" cellpadding="0" cellspacing="2">
23<tr>
24<td class='online-navigation'><a rel="prev" title="6.10.7 strftime() Behavior"
25 href="node257.html"><img src='../icons/previous.png'
26 border='0' height='32' alt='Previous Page' width='32' /></A></td>
27<td class='online-navigation'><a rel="parent" title="6. Generic Operating System"
28 href="allos.html"><img src='../icons/up.png'
29 border='0' height='32' alt='Up One Level' width='32' /></A></td>
30<td class='online-navigation'><a rel="next" title="6.12 sched "
31 href="module-sched.html"><img src='../icons/next.png'
32 border='0' height='32' alt='Next Page' width='32' /></A></td>
33<td align="center" width="100%">Python Library Reference</td>
34<td class='online-navigation'><a rel="contents" title="Table of Contents"
35 href="contents.html"><img src='../icons/contents.png'
36 border='0' height='32' alt='Contents' width='32' /></A></td>
37<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
38 border='0' height='32' alt='Module Index' width='32' /></a></td>
39<td class='online-navigation'><a rel="index" title="Index"
40 href="genindex.html"><img src='../icons/index.png'
41 border='0' height='32' alt='Index' width='32' /></A></td>
42</tr></table>
43<div class='online-navigation'>
44<b class="navlabel">Previous:</b>
45<a class="sectref" rel="prev" href="node257.html">6.10.7 strftime() Behavior</A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="allos.html">6. Generic Operating System</A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="module-sched.html">6.12 sched </A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H1><A NAME="SECTION0081100000000000000000">
566.11 <tt class="module">time</tt> --
57 Time access and conversions</A>
58</H1>
59
60<P>
61<A NAME="module-time"></A>
62
63<P>
64This module provides various time-related functions. It is always
65available, but not all functions are available on all platforms. Most
66of the functions defined in this module call platform C library
67functions with the same name. It may sometimes be helpful to consult
68the platform documentation, because the semantics of these functions
69varies among platforms.
70
71<P>
72An explanation of some terminology and conventions is in order.
73
74<P>
75
76<UL>
77<LI>The <i class="dfn">epoch</i><a id='l2h-1962' xml:id='l2h-1962'></a> is the point where the time starts. On
78January 1st of that year, at 0 hours, the ``time since the epoch'' is
79zero. For <span class="Unix">Unix</span>, the epoch is 1970. To find out what the epoch is,
80look at <code>gmtime(0)</code>.
81
82<P>
83</LI>
84<LI>The functions in this module do not handle dates and times before the
85epoch or far in the future. The cut-off point in the future is
86determined by the C library; for <span class="Unix">Unix</span>, it is typically in
872038<a id='l2h-1963' xml:id='l2h-1963'></a>.
88
89<P>
90</LI>
91<LI><strong>Year 2000 (Y2K) issues</strong>:<a id='l2h-1964' xml:id='l2h-1964'></a> Python
92depends on the platform's C library, which generally doesn't have year
932000 issues, since all dates and times are represented internally as
94seconds since the epoch. Functions accepting a <tt class="class">struct_time</tt>
95(see below) generally require a 4-digit year. For backward
96compatibility, 2-digit years are supported if the module variable
97<code>accept2dyear</code> is a non-zero integer; this variable is
98initialized to <code>1</code> unless the environment variable
99<a class="envvar" id='l2h-1965' xml:id='l2h-1965'>PYTHONY2K</a> is set to a non-empty string, in which case it is
100initialized to <code>0</code>. Thus, you can set
101<a class="envvar" id='l2h-1966' xml:id='l2h-1966'>PYTHONY2K</a> to a non-empty string in the environment to require 4-digit
102years for all year input. When 2-digit years are accepted, they are
103converted according to the POSIX or X/Open standard: values 69-99
104are mapped to 1969-1999, and values 0-68 are mapped to 2000-2068.
105Values 100-1899 are always illegal. Note that this is new as of
106Python 1.5.2(a2); earlier versions, up to Python 1.5.1 and 1.5.2a1,
107would add 1900 to year values below 1900.
108
109<P>
110</LI>
111<LI>UTC<a id='l2h-1967' xml:id='l2h-1967'></a> is Coordinated Universal Time<a id='l2h-1968' xml:id='l2h-1968'></a> (formerly known as Greenwich Mean
112Time,<a id='l2h-1969' xml:id='l2h-1969'></a> or GMT). The acronym UTC is not a
113mistake but a compromise between English and French.
114
115<P>
116</LI>
117<LI>DST is Daylight Saving Time,<a id='l2h-1970' xml:id='l2h-1970'></a> an adjustment
118of the timezone by (usually) one hour during part of the year. DST
119rules are magic (determined by local law) and can change from year to
120year. The C library has a table containing the local rules (often it
121is read from a system file for flexibility) and is the only source of
122True Wisdom in this respect.
123
124<P>
125</LI>
126<LI>The precision of the various real-time functions may be less than
127suggested by the units in which their value or argument is expressed.
128E.g. on most <span class="Unix">Unix</span> systems, the clock ``ticks'' only 50 or 100 times a
129second, and on the Mac, times are only accurate to whole seconds.
130
131<P>
132</LI>
133<LI>On the other hand, the precision of <tt class="function">time()</tt> and
134<tt class="function">sleep()</tt> is better than their <span class="Unix">Unix</span> equivalents: times are
135expressed as floating point numbers, <tt class="function">time()</tt> returns the
136most accurate time available (using <span class="Unix">Unix</span> <tt class="cfunction">gettimeofday()</tt>
137where available), and <tt class="function">sleep()</tt> will accept a time with a
138nonzero fraction (<span class="Unix">Unix</span> <tt class="cfunction">select()</tt> is used to implement
139this, where available).
140
141<P>
142</LI>
143<LI>The time value as returned by <tt class="function">gmtime()</tt>,
144<tt class="function">localtime()</tt>, and <tt class="function">strptime()</tt>, and accepted by
145<tt class="function">asctime()</tt>, <tt class="function">mktime()</tt> and <tt class="function">strftime()</tt>,
146is a sequence of 9 integers. The return values of <tt class="function">gmtime()</tt>,
147<tt class="function">localtime()</tt>, and <tt class="function">strptime()</tt> also offer attribute
148names for individual fields.
149
150<P>
151<div class="center"><table class="realtable">
152 <thead>
153 <tr>
154 <th class="center">Index</th>
155 <th class="left" >Attribute</th>
156 <th class="left" >Values</th>
157 </tr>
158 </thead>
159 <tbody>
160 <tr><td class="center" valign="baseline"><code>0</code></td>
161 <td class="left" ><tt class="member">tm_year</tt></td>
162 <td class="left" >(for example, 1993)</td></tr>
163 <tr><td class="center" valign="baseline"><code>1</code></td>
164 <td class="left" ><tt class="member">tm_mon</tt></td>
165 <td class="left" >range [1,12]</td></tr>
166 <tr><td class="center" valign="baseline"><code>2</code></td>
167 <td class="left" ><tt class="member">tm_mday</tt></td>
168 <td class="left" >range [1,31]</td></tr>
169 <tr><td class="center" valign="baseline"><code>3</code></td>
170 <td class="left" ><tt class="member">tm_hour</tt></td>
171 <td class="left" >range [0,23]</td></tr>
172 <tr><td class="center" valign="baseline"><code>4</code></td>
173 <td class="left" ><tt class="member">tm_min</tt></td>
174 <td class="left" >range [0,59]</td></tr>
175 <tr><td class="center" valign="baseline"><code>5</code></td>
176 <td class="left" ><tt class="member">tm_sec</tt></td>
177 <td class="left" >range [0,61]; see <strong>(1)</strong> in <tt class="function">strftime()</tt> description</td></tr>
178 <tr><td class="center" valign="baseline"><code>6</code></td>
179 <td class="left" ><tt class="member">tm_wday</tt></td>
180 <td class="left" >range [0,6], Monday is 0</td></tr>
181 <tr><td class="center" valign="baseline"><code>7</code></td>
182 <td class="left" ><tt class="member">tm_yday</tt></td>
183 <td class="left" >range [1,366]</td></tr>
184 <tr><td class="center" valign="baseline"><code>8</code></td>
185 <td class="left" ><tt class="member">tm_isdst</tt></td>
186 <td class="left" >0, 1 or -1; see below</td></tr></tbody>
187</table></div>
188
189<P>
190Note that unlike the C structure, the month value is a
191range of 1-12, not 0-11. A year value will be handled as described
192under ``Year 2000 (Y2K) issues'' above. A <code>-1</code> argument as the
193daylight savings flag, passed to <tt class="function">mktime()</tt> will usually
194result in the correct daylight savings state to be filled in.
195
196<P>
197When a tuple with an incorrect length is passed to a function
198expecting a <tt class="class">struct_time</tt>, or having elements of the wrong type, a
199<tt class="exception">TypeError</tt> is raised.
200
201<P>
202
203<span class="versionnote">Changed in version 2.2:
204The time value sequence was changed from a tuple to a
205 <tt class="class">struct_time</tt>, with the addition of attribute names
206 for the fields.</span>
207
208</LI>
209</UL>
210
211<P>
212The module defines the following functions and data items:
213
214<P>
215<dl><dt><b><tt id='l2h-1945' xml:id='l2h-1945'>accept2dyear</tt></b></dt>
216<dd>
217Boolean value indicating whether two-digit year values will be
218accepted. This is true by default, but will be set to false if the
219environment variable <a class="envvar" id='l2h-1971' xml:id='l2h-1971'>PYTHONY2K</a> has been set to a non-empty
220string. It may also be modified at run time.
221</dd></dl>
222
223<P>
224<dl><dt><b><tt id='l2h-1946' xml:id='l2h-1946'>altzone</tt></b></dt>
225<dd>
226The offset of the local DST timezone, in seconds west of UTC, if one
227is defined. This is negative if the local DST timezone is east of UTC
228(as in Western Europe, including the UK). Only use this if
229<code>daylight</code> is nonzero.
230</dd></dl>
231
232<P>
233<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
234 <td><nobr><b><tt id='l2h-1947' xml:id='l2h-1947' class="function">asctime</tt></b>(</nobr></td>
235 <td><var></var><big>[</big><var>t</var><big>]</big><var></var>)</td></tr></table></dt>
236<dd>
237Convert a tuple or <tt class="class">struct_time</tt> representing a time as returned
238by <tt class="function">gmtime()</tt>
239or <tt class="function">localtime()</tt> to a 24-character string of the following form:
240<code>'Sun Jun 20 23:21:05 1993'</code>. If <var>t</var> is not provided, the
241current time as returned by <tt class="function">localtime()</tt> is used.
242Locale information is not used by <tt class="function">asctime()</tt>.
243<span class="note"><b class="label">Note:</b>
244Unlike the C function of the same name, there is no trailing
245newline.</span>
246
247<span class="versionnote">Changed in version 2.1:
248Allowed <var>t</var> to be omitted.</span>
249
250</dl>
251
252<P>
253<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
254 <td><nobr><b><tt id='l2h-1948' xml:id='l2h-1948' class="function">clock</tt></b>(</nobr></td>
255 <td><var></var>)</td></tr></table></dt>
256<dd>
257On <span class="Unix">Unix</span>, return
258the current processor time as a floating point number expressed in
259seconds. The precision, and in fact the very definition of the meaning
260of ``processor time''<a id='l2h-1972' xml:id='l2h-1972'></a>, depends
261on that of the C function of the same name, but in any case, this is
262the function to use for benchmarking<a id='l2h-1973' xml:id='l2h-1973'></a> Python or
263timing algorithms.
264
265<P>
266On Windows, this function returns wall-clock seconds elapsed since the
267first call to this function, as a floating point number,
268based on the Win32 function <tt class="cfunction">QueryPerformanceCounter()</tt>.
269The resolution is typically better than one microsecond.
270</dl>
271
272<P>
273<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
274 <td><nobr><b><tt id='l2h-1949' xml:id='l2h-1949' class="function">ctime</tt></b>(</nobr></td>
275 <td><var></var><big>[</big><var>secs</var><big>]</big><var></var>)</td></tr></table></dt>
276<dd>
277Convert a time expressed in seconds since the epoch to a string
278representing local time. If <var>secs</var> is not provided or
279<tt class="constant">None</tt>, the current time as returned by <tt class="function">time()</tt> is
280used. <code>ctime(<var>secs</var>)</code> is equivalent to
281<code>asctime(localtime(<var>secs</var>))</code>.
282Locale information is not used by <tt class="function">ctime()</tt>.
283
284<span class="versionnote">Changed in version 2.1:
285Allowed <var>secs</var> to be omitted.</span>
286
287<span class="versionnote">Changed in version 2.4:
288If <var>secs</var> is <tt class="constant">None</tt>, the current time is
289 used.</span>
290
291</dl>
292
293<P>
294<dl><dt><b><tt id='l2h-1950' xml:id='l2h-1950'>daylight</tt></b></dt>
295<dd>
296Nonzero if a DST timezone is defined.
297</dd></dl>
298
299<P>
300<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
301 <td><nobr><b><tt id='l2h-1951' xml:id='l2h-1951' class="function">gmtime</tt></b>(</nobr></td>
302 <td><var></var><big>[</big><var>secs</var><big>]</big><var></var>)</td></tr></table></dt>
303<dd>
304Convert a time expressed in seconds since the epoch to a <tt class="class">struct_time</tt>
305in UTC in which the dst flag is always zero. If <var>secs</var> is not
306provided or <tt class="constant">None</tt>, the current time as returned by
307<tt class="function">time()</tt> is used. Fractions of a second are ignored. See
308above for a description of the <tt class="class">struct_time</tt> object. See
309<tt class="function">calendar.timegm()</tt> for the inverse of this function.
310
311<span class="versionnote">Changed in version 2.1:
312Allowed <var>secs</var> to be omitted.</span>
313
314<span class="versionnote">Changed in version 2.4:
315If <var>secs</var> is <tt class="constant">None</tt>, the current time is
316 used.</span>
317
318</dl>
319
320<P>
321<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
322 <td><nobr><b><tt id='l2h-1952' xml:id='l2h-1952' class="function">localtime</tt></b>(</nobr></td>
323 <td><var></var><big>[</big><var>secs</var><big>]</big><var></var>)</td></tr></table></dt>
324<dd>
325Like <tt class="function">gmtime()</tt> but converts to local time. If <var>secs</var> is
326not provided or <tt class="constant">None</tt>, the current time as returned by
327<tt class="function">time()</tt> is used. The dst flag is set to <code>1</code> when DST
328applies to the given time.
329
330<span class="versionnote">Changed in version 2.1:
331Allowed <var>secs</var> to be omitted.</span>
332
333<span class="versionnote">Changed in version 2.4:
334If <var>secs</var> is <tt class="constant">None</tt>, the current time is
335 used.</span>
336
337</dl>
338
339<P>
340<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
341 <td><nobr><b><tt id='l2h-1953' xml:id='l2h-1953' class="function">mktime</tt></b>(</nobr></td>
342 <td><var>t</var>)</td></tr></table></dt>
343<dd>
344This is the inverse function of <tt class="function">localtime()</tt>. Its argument
345is the <tt class="class">struct_time</tt> or full 9-tuple (since the dst flag is
346needed; use <code>-1</code> as the dst flag if it is unknown) which
347expresses the time in
348<em>local</em> time, not UTC. It returns a floating point number, for
349compatibility with <tt class="function">time()</tt>. If the input value cannot be
350represented as a valid time, either <tt class="exception">OverflowError</tt> or
351<tt class="exception">ValueError</tt> will be raised (which depends on whether the
352invalid value is caught by Python or the underlying C libraries). The
353earliest date for which it can generate a time is platform-dependent.
354</dl>
355
356<P>
357<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
358 <td><nobr><b><tt id='l2h-1954' xml:id='l2h-1954' class="function">sleep</tt></b>(</nobr></td>
359 <td><var>secs</var>)</td></tr></table></dt>
360<dd>
361Suspend execution for the given number of seconds. The argument may
362be a floating point number to indicate a more precise sleep time.
363The actual suspension time may be less than that requested because any
364caught signal will terminate the <tt class="function">sleep()</tt> following
365execution of that signal's catching routine. Also, the suspension
366time may be longer than requested by an arbitrary amount because of
367the scheduling of other activity in the system.
368</dl>
369
370<P>
371<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
372 <td><nobr><b><tt id='l2h-1955' xml:id='l2h-1955' class="function">strftime</tt></b>(</nobr></td>
373 <td><var>format</var><big>[</big><var>, t</var><big>]</big><var></var>)</td></tr></table></dt>
374<dd>
375Convert a tuple or <tt class="class">struct_time</tt> representing a time as returned
376by <tt class="function">gmtime()</tt> or <tt class="function">localtime()</tt> to a string as
377specified by the <var>format</var> argument. If <var>t</var> is not
378provided, the current time as returned by <tt class="function">localtime()</tt> is
379used. <var>format</var> must be a string. <tt class="exception">ValueError</tt> is raised
380if any field in <var>t</var> is outside of the allowed range.
381
382<span class="versionnote">Changed in version 2.1:
383Allowed <var>t</var> to be omitted.</span>
384
385<span class="versionnote">Changed in version 2.4:
386<tt class="exception">ValueError</tt> raised if a field in <var>t</var> is
387out of range..</span>
388
389<P>
390The following directives can be embedded in the <var>format</var> string.
391They are shown without the optional field width and precision
392specification, and are replaced by the indicated characters in the
393<tt class="function">strftime()</tt> result:
394
395<P>
396<div class="center"><table class="realtable">
397 <thead>
398 <tr>
399 <th class="center">Directive</th>
400 <th class="left" >Meaning</th>
401 <th class="center">Notes</th>
402 </tr>
403 </thead>
404 <tbody>
405 <tr><td class="center" valign="baseline"><code>%a</code></td>
406 <td class="left" >Locale's abbreviated weekday name.</td>
407 <td class="center"></td></tr>
408 <tr><td class="center" valign="baseline"><code>%A</code></td>
409 <td class="left" >Locale's full weekday name.</td>
410 <td class="center"></td></tr>
411 <tr><td class="center" valign="baseline"><code>%b</code></td>
412 <td class="left" >Locale's abbreviated month name.</td>
413 <td class="center"></td></tr>
414 <tr><td class="center" valign="baseline"><code>%B</code></td>
415 <td class="left" >Locale's full month name.</td>
416 <td class="center"></td></tr>
417 <tr><td class="center" valign="baseline"><code>%c</code></td>
418 <td class="left" >Locale's appropriate date and time representation.</td>
419 <td class="center"></td></tr>
420 <tr><td class="center" valign="baseline"><code>%d</code></td>
421 <td class="left" >Day of the month as a decimal number [01,31].</td>
422 <td class="center"></td></tr>
423 <tr><td class="center" valign="baseline"><code>%H</code></td>
424 <td class="left" >Hour (24-hour clock) as a decimal number [00,23].</td>
425 <td class="center"></td></tr>
426 <tr><td class="center" valign="baseline"><code>%I</code></td>
427 <td class="left" >Hour (12-hour clock) as a decimal number [01,12].</td>
428 <td class="center"></td></tr>
429 <tr><td class="center" valign="baseline"><code>%j</code></td>
430 <td class="left" >Day of the year as a decimal number [001,366].</td>
431 <td class="center"></td></tr>
432 <tr><td class="center" valign="baseline"><code>%m</code></td>
433 <td class="left" >Month as a decimal number [01,12].</td>
434 <td class="center"></td></tr>
435 <tr><td class="center" valign="baseline"><code>%M</code></td>
436 <td class="left" >Minute as a decimal number [00,59].</td>
437 <td class="center"></td></tr>
438 <tr><td class="center" valign="baseline"><code>%p</code></td>
439 <td class="left" >Locale's equivalent of either AM or PM.</td>
440 <td class="center">(1)</td></tr>
441 <tr><td class="center" valign="baseline"><code>%S</code></td>
442 <td class="left" >Second as a decimal number [00,61].</td>
443 <td class="center">(2)</td></tr>
444 <tr><td class="center" valign="baseline"><code>%U</code></td>
445 <td class="left" >Week number of the year (Sunday as the first day of the
446 week) as a decimal number [00,53]. All days in a new year
447 preceding the first Sunday are considered to be in week 0.</td>
448 <td class="center">(3)</td></tr>
449 <tr><td class="center" valign="baseline"><code>%w</code></td>
450 <td class="left" >Weekday as a decimal number [0(Sunday),6].</td>
451 <td class="center"></td></tr>
452 <tr><td class="center" valign="baseline"><code>%W</code></td>
453 <td class="left" >Week number of the year (Monday as the first day of the
454 week) as a decimal number [00,53]. All days in a new year
455 preceding the first Monday are considered to be in week 0.</td>
456 <td class="center">(3)</td></tr>
457 <tr><td class="center" valign="baseline"><code>%x</code></td>
458 <td class="left" >Locale's appropriate date representation.</td>
459 <td class="center"></td></tr>
460 <tr><td class="center" valign="baseline"><code>%X</code></td>
461 <td class="left" >Locale's appropriate time representation.</td>
462 <td class="center"></td></tr>
463 <tr><td class="center" valign="baseline"><code>%y</code></td>
464 <td class="left" >Year without century as a decimal number [00,99].</td>
465 <td class="center"></td></tr>
466 <tr><td class="center" valign="baseline"><code>%Y</code></td>
467 <td class="left" >Year with century as a decimal number.</td>
468 <td class="center"></td></tr>
469 <tr><td class="center" valign="baseline"><code>%Z</code></td>
470 <td class="left" >Time zone name (no characters if no time zone exists).</td>
471 <td class="center"></td></tr>
472 <tr><td class="center" valign="baseline"><code>%%</code></td>
473 <td class="left" >A literal "<tt class="character">%</tt>" character.</td>
474 <td class="center"></td></tr></tbody>
475</table></div>
476
477<P>
478Notes:
479
480<P>
481<DL>
482<DT><STRONG>(1)</STRONG></DT>
483<DD>When used with the <tt class="function">strptime()</tt> function, the <code>%p</code>
484 directive only affects the output hour field if the <code>%I</code> directive
485 is used to parse the hour.
486
487</DD>
488<DT><STRONG>(2)</STRONG></DT>
489<DD>The range really is <code>0</code> to <code>61</code>; this accounts for leap
490 seconds and the (very rare) double leap seconds.
491
492</DD>
493<DT><STRONG>(3)</STRONG></DT>
494<DD>When used with the <tt class="function">strptime()</tt> function, <code>%U</code> and <code>%W</code>
495 are only used in calculations when the day of the week and the year are
496 specified.
497</DD>
498</DL>
499
500<P>
501Here is an example, a format for dates compatible with that specified
502in the <a class="rfc" id='rfcref-88249' xml:id='rfcref-88249'
503href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> Internet email standard.
504 <A NAME="tex2html35"
505 HREF="#foot30076"><SUP>6.1</SUP></A>
506<P>
507<div class="verbatim"><pre>
508&gt;&gt;&gt; from time import gmtime, strftime
509&gt;&gt;&gt; strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
510'Thu, 28 Jun 2001 14:17:15 +0000'
511</pre></div>
512
513<P>
514Additional directives may be supported on certain platforms, but
515only the ones listed here have a meaning standardized by ANSI C.
516
517<P>
518On some platforms, an optional field width and precision
519specification can immediately follow the initial "<tt class="character">%</tt>" of a
520directive in the following order; this is also not portable.
521The field width is normally 2 except for <code>%j</code> where it is 3.
522</dl>
523
524<P>
525<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
526 <td><nobr><b><tt id='l2h-1956' xml:id='l2h-1956' class="function">strptime</tt></b>(</nobr></td>
527 <td><var>string</var><big>[</big><var>, format</var><big>]</big><var></var>)</td></tr></table></dt>
528<dd>
529Parse a string representing a time according to a format. The return
530value is a <tt class="class">struct_time</tt> as returned by <tt class="function">gmtime()</tt> or
531<tt class="function">localtime()</tt>. The <var>format</var> parameter uses the same
532directives as those used by <tt class="function">strftime()</tt>; it defaults to
533<code>"%a %b %d %H:%M:%S %Y"</code> which matches the formatting
534returned by <tt class="function">ctime()</tt>. If <var>string</var> cannot be parsed
535according to <var>format</var>, <tt class="exception">ValueError</tt> is raised. If the
536string to be parsed has excess data after parsing,
537<tt class="exception">ValueError</tt> is raised. The default values used to fill in
538any missing data are <code>(1900, 1, 1, 0, 0, 0, 0, 1, -1)</code> .
539
540<P>
541Support for the <code>%Z</code> directive is based on the values contained in
542<code>tzname</code> and whether <code>daylight</code> is true. Because of this,
543it is platform-specific except for recognizing UTC and GMT which are
544always known (and are considered to be non-daylight savings
545timezones).
546</dl>
547
548<P>
549<dl><dt><b><tt id='l2h-1957' xml:id='l2h-1957'>struct_time</tt></b></dt>
550<dd>
551The type of the time value sequence returned by <tt class="function">gmtime()</tt>,
552<tt class="function">localtime()</tt>, and <tt class="function">strptime()</tt>.
553
554<span class="versionnote">New in version 2.2.</span>
555
556</dd></dl>
557
558<P>
559<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
560 <td><nobr><b><tt id='l2h-1958' xml:id='l2h-1958' class="function">time</tt></b>(</nobr></td>
561 <td><var></var>)</td></tr></table></dt>
562<dd>
563Return the time as a floating point number expressed in seconds since
564the epoch, in UTC. Note that even though the time is always returned
565as a floating point number, not all systems provide time with a better
566precision than 1 second. While this function normally returns
567non-decreasing values, it can return a lower value than a previous
568call if the system clock has been set back between the two calls.
569</dl>
570
571<P>
572<dl><dt><b><tt id='l2h-1959' xml:id='l2h-1959'>timezone</tt></b></dt>
573<dd>
574The offset of the local (non-DST) timezone, in seconds west of UTC
575(negative in most of Western Europe, positive in the US, zero in the
576UK).
577</dd></dl>
578
579<P>
580<dl><dt><b><tt id='l2h-1960' xml:id='l2h-1960'>tzname</tt></b></dt>
581<dd>
582A tuple of two strings: the first is the name of the local non-DST
583timezone, the second is the name of the local DST timezone. If no DST
584timezone is defined, the second string should not be used.
585</dd></dl>
586
587<P>
588<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
589 <td><nobr><b><tt id='l2h-1961' xml:id='l2h-1961' class="function">tzset</tt></b>(</nobr></td>
590 <td><var></var>)</td></tr></table></dt>
591<dd>
592Resets the time conversion rules used by the library routines.
593The environment variable <a class="envvar" id='l2h-1974' xml:id='l2h-1974'>TZ</a> specifies how this is done.
594
595<span class="versionnote">New in version 2.3.</span>
596
597<P>
598Availability: <span class="Unix">Unix</span>.
599
600<P>
601<div class="note"><b class="label">Note:</b>
602Although in many cases, changing the <a class="envvar" id='l2h-1975' xml:id='l2h-1975'>TZ</a> environment variable
603may affect the output of functions like <tt class="function">localtime</tt> without calling
604<tt class="function">tzset</tt>, this behavior should not be relied on.
605
606<P>
607The <a class="envvar" id='l2h-1976' xml:id='l2h-1976'>TZ</a> environment variable should contain no whitespace.
608</div>
609
610<P>
611The standard format of the <a class="envvar" id='l2h-1977' xml:id='l2h-1977'>TZ</a> environment variable is:
612(whitespace added for clarity)
613<DL COMPACT>
614<DT>std offset [dst [offset] [,start[/time], end[/time]</DT>
615<DD>]]
616</DD>
617</DL>
618
619<P>
620Where:
621
622<P>
623<DL COMPACT>
624<DT>std and dst</DT>
625<DD>Three or more alphanumerics giving the timezone abbreviations.
626 These will be propagated into time.tzname
627
628<P>
629</DD>
630<DT>offset</DT>
631<DD>The offset has the form: &plusmn; hh[:mm[:ss]].
632 This indicates the value added the local time to arrive at UTC.
633 If preceded by a '-', the timezone is east of the Prime
634 Meridian; otherwise, it is west. If no offset follows
635 dst, summer time is assumed to be one hour ahead of standard time.
636
637<P>
638</DD>
639<DT>start[/time],end[/time]</DT>
640<DD>Indicates when to change to and back from DST. The format of the
641 start and end dates are one of the following:
642
643<P>
644<DL COMPACT>
645<DT>J<var>n</var></DT>
646<DD>The Julian day <var>n</var> (1 &lt;= <var>n</var> &lt;= 365). Leap days are not
647 counted, so in all years February 28 is day 59 and
648 March 1 is day 60.
649
650<P>
651</DD>
652<DT><var>n</var></DT>
653<DD>The zero-based Julian day (0 &lt;= <var>n</var> &lt;= 365). Leap days are
654 counted, and it is possible to refer to February 29.
655
656<P>
657</DD>
658<DT>M<var>m</var>.<var>n</var>.<var>d</var></DT>
659<DD>The <var>d</var>'th day (0 &lt;= <var>d</var> &lt;= 6) or week <var>n</var>
660 of month <var>m</var> of the year (1 &lt;= <var>n</var> &lt;= 5,
661 1 &lt;= <var>m</var> &lt;= 12, where week 5 means "the last <var>d</var> day
662 in month <var>m</var>" which may occur in either the fourth or
663 the fifth week). Week 1 is the first week in which the
664 <var>d</var>'th day occurs. Day zero is Sunday.
665
666</DD>
667</DL>
668
669<P>
670time has the same format as offset except that no leading sign ('-' or
671 '+') is allowed. The default, if time is not given, is 02:00:00.
672</DD>
673</DL>
674
675<P>
676<div class="verbatim"><pre>
677&gt;&gt;&gt; os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
678&gt;&gt;&gt; time.tzset()
679&gt;&gt;&gt; time.strftime('%X %x %Z')
680'02:07:36 05/08/03 EDT'
681&gt;&gt;&gt; os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
682&gt;&gt;&gt; time.tzset()
683&gt;&gt;&gt; time.strftime('%X %x %Z')
684'16:08:12 05/08/03 AEST'
685</pre></div>
686
687<P>
688On many Unix systems (including *BSD, Linux, Solaris, and Darwin), it
689is more convenient to use the system's zoneinfo (<span class="manpage"><i>tzfile</i>(5)</span>)
690database to specify the timezone rules. To do this, set the
691<a class="envvar" id='l2h-1978' xml:id='l2h-1978'>TZ</a> environment variable to the path of the required timezone
692datafile, relative to the root of the systems 'zoneinfo' timezone database,
693usually located at <span class="file">/usr/share/zoneinfo</span>. For example,
694<code>'US/Eastern'</code>, <code>'Australia/Melbourne'</code>, <code>'Egypt'</code> or
695<code>'Europe/Amsterdam'</code>.
696
697<P>
698<div class="verbatim"><pre>
699&gt;&gt;&gt; os.environ['TZ'] = 'US/Eastern'
700&gt;&gt;&gt; time.tzset()
701&gt;&gt;&gt; time.tzname
702('EST', 'EDT')
703&gt;&gt;&gt; os.environ['TZ'] = 'Egypt'
704&gt;&gt;&gt; time.tzset()
705&gt;&gt;&gt; time.tzname
706('EET', 'EEST')
707</pre></div>
708
709<P>
710</dl>
711
712<P>
713<div class="seealso">
714 <p class="heading">See Also:</p>
715
716 <dl compact="compact" class="seemodule">
717 <dt>Module <b><tt class="module"><a href="module-datetime.html">datetime</a></tt>:</b>
718 <dd>More object-oriented interface to dates and times.
719 </dl>
720 <dl compact="compact" class="seemodule">
721 <dt>Module <b><tt class="module"><a href="module-locale.html">locale</a></tt>:</b>
722 <dd>Internationalization services. The locale
723 settings can affect the return values for some of
724 the functions in the <tt class="module">time</tt> module.
725 </dl>
726 <dl compact="compact" class="seemodule">
727 <dt>Module <b><tt class="module"><a href="module-calendar.html">calendar</a></tt>:</b>
728 <dd>General calendar-related functions.
729 <tt class="function">timegm()</tt> is the inverse of
730 <tt class="function">gmtime()</tt> from this module.
731 </dl>
732</div>
733<BR><HR><H4>Footnotes</H4>
734<DL>
735<DT><A NAME="foot30076">... standard.</A><A
736 href="module-time.html#tex2html35"><SUP>6.1</SUP></A></DT>
737<DD>The use of <code>%Z</code> is now
738 deprecated, but the <code>%z</code> escape that expands to the preferred
739 hour/minute offset is not supported by all ANSI C libraries. Also,
740 a strict reading of the original 1982 <a class="rfc" id='rfcref-88203' xml:id='rfcref-88203'
741href="http://www.faqs.org/rfcs/rfc822.html">RFC 822</a> standard calls for
742 a two-digit year (%y rather than %Y), but practice moved to
743 4-digit years long before the year 2000. The 4-digit year has
744 been mandated by <a class="rfc" id='rfcref-88205' xml:id='rfcref-88205'
745href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>, which obsoletes <a class="rfc" id='rfcref-88207' xml:id='rfcref-88207'
746href="http://www.faqs.org/rfcs/rfc822.html">RFC 822</a>.
747
748</DD>
749</DL>
750<DIV CLASS="navigation">
751<div class='online-navigation'>
752<p></p><hr />
753<table align="center" width="100%" cellpadding="0" cellspacing="2">
754<tr>
755<td class='online-navigation'><a rel="prev" title="6.10.7 strftime() Behavior"
756 href="node257.html"><img src='../icons/previous.png'
757 border='0' height='32' alt='Previous Page' width='32' /></A></td>
758<td class='online-navigation'><a rel="parent" title="6. Generic Operating System"
759 href="allos.html"><img src='../icons/up.png'
760 border='0' height='32' alt='Up One Level' width='32' /></A></td>
761<td class='online-navigation'><a rel="next" title="6.12 sched "
762 href="module-sched.html"><img src='../icons/next.png'
763 border='0' height='32' alt='Next Page' width='32' /></A></td>
764<td align="center" width="100%">Python Library Reference</td>
765<td class='online-navigation'><a rel="contents" title="Table of Contents"
766 href="contents.html"><img src='../icons/contents.png'
767 border='0' height='32' alt='Contents' width='32' /></A></td>
768<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
769 border='0' height='32' alt='Module Index' width='32' /></a></td>
770<td class='online-navigation'><a rel="index" title="Index"
771 href="genindex.html"><img src='../icons/index.png'
772 border='0' height='32' alt='Index' width='32' /></A></td>
773</tr></table>
774<div class='online-navigation'>
775<b class="navlabel">Previous:</b>
776<a class="sectref" rel="prev" href="node257.html">6.10.7 strftime() Behavior</A>
777<b class="navlabel">Up:</b>
778<a class="sectref" rel="parent" href="allos.html">6. Generic Operating System</A>
779<b class="navlabel">Next:</b>
780<a class="sectref" rel="next" href="module-sched.html">6.12 sched </A>
781</div>
782</div>
783<hr />
784<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
785</DIV>
786<!--End of Navigation Panel-->
787<ADDRESS>
788See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
789</ADDRESS>
790</BODY>
791</HTML>
Full OpenSPARC design & verification tarball including full HDL.