393 lines
14 KiB
HTML
393 lines
14 KiB
HTML
<html>
|
|
<head>
|
|
<title>
|
|
C Guide--2.15 time.h
|
|
</title>
|
|
<!-- Changed by: eric huss, 12-Mar-1997 -->
|
|
</head>
|
|
<body text="#000000" bgcolor="#FFFFFF">
|
|
|
|
<center>
|
|
<table border=0 width=100%>
|
|
<tr>
|
|
<td align=left width=20% valign=top>
|
|
<a href="2.14.html">
|
|
<img src="left.gif" border=0>
|
|
Previous Section<br>
|
|
2.14 string.h</a></td>
|
|
<td align=center width=60% valign=top>
|
|
| <a href="index.html">Table of Contents</a> |
|
|
<a href="index2.html">Index</a> |</td>
|
|
<td align=right width=20% valign=top>
|
|
<a href="index2.html">
|
|
Next Section
|
|
<img src="right.gif" border=0><br>
|
|
Index</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
|
|
|
|
<h1> 2.15 time.h</h1>
|
|
<p>
|
|
|
|
The time header provides several functions useful for reading and converting the current
|
|
time and date. Some functions behavior is defined by the <code><b>LC_TIME</b></code> category of the location
|
|
setting.
|
|
<p>
|
|
Macros:
|
|
<blockquote><code><b>
|
|
NULL<br>
|
|
CLOCKS_PER_SEC
|
|
</b></code></blockquote>
|
|
|
|
Variables:
|
|
<blockquote><code><b>
|
|
typedef size_t<br>
|
|
typedef clock_t<br>
|
|
typedef size_t<br>
|
|
struct tm
|
|
</b></code></blockquote>
|
|
|
|
Functions:
|
|
<blockquote><code><b>
|
|
asctime();<br>
|
|
clock();<br>
|
|
ctime();<br>
|
|
difftime();<br>
|
|
gmtime();<br>
|
|
localtime();<br>
|
|
mktime();<br>
|
|
strftime(); <br>
|
|
time();
|
|
</b></code></blockquote>
|
|
|
|
<a name="variables"></a>
|
|
<h2>2.15.1 Variables and Definitions</h2>
|
|
<blockquote>
|
|
<code><b>NULL</b></code> is the value of a null pointer constant.<br>
|
|
<code><b>CLOCKS_PER_SEC</b></code> is the number of processor clocks per second.<br>
|
|
<p>
|
|
<code><b>size_t</b></code> is the unsigned integer result of the sizeof keyword.<br>
|
|
<code><b>clock_t</b></code> is a type suitable for storing the processor time.<br>
|
|
<code><b>time_t</b></code> is a type suitable for storing the calendar time.<br>
|
|
<p>
|
|
<code><b>struct tm</b></code> is a structure used to hold the time and date. Its members are as follows:
|
|
<code><b><pre>
|
|
int tm_sec; /* seconds after the minute (0 to 61) */
|
|
int tm_min; /* minutes after the hour (0 to 59) */
|
|
int tm_hour; /* hours since midnight (0 to 23) */
|
|
int tm_mday; /* day of the month (1 to 31) */
|
|
int tm_mon; /* months since January (0 to 11) */
|
|
int tm_year; /* years since 1900 */
|
|
int tm_wday; /* days since Sunday (0 to 6 Sunday=0) */
|
|
int tm_yday; /* days since January 1 (0 to 365) */
|
|
int tm_isdst; /* Daylight Savings Time */
|
|
</pre></b></code>
|
|
</blockquote>
|
|
<p>
|
|
If <code><b>tm_isdst</b></code> is zero, then Daylight Savings Time is not in effect. If it is a positive value,
|
|
then Daylight Savings Time is in effect. If it is negative, then the function using it is requested
|
|
to attempt to calculate whether or not Daylight Savings Time is in effect for the given time.
|
|
<p>
|
|
Note that <code><b>tm_sec</b></code> may go as high as 61 to allow for up to two leap seconds.
|
|
|
|
<a name="asctime"></a>
|
|
<h2> 2.15.2 asctime</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
char *asctime(const struct tm *</b></code><i>timeptr</i><code><b>);
|
|
</b></code></blockquote>
|
|
Returns a pointer to a string which represents the day and time of the structure <i>timeptr</i>.
|
|
The string is in the following format:
|
|
<blockquote><code><b>
|
|
DDD MMM dd hh:mm:ss YYYY
|
|
</b></code></blockquote>
|
|
<table border=0>
|
|
<tr><td><code><b>DDD</b></code></td><td> Day of the week (Sun, Mon, Tue, Wed, Thu, Fri, Sat)</td></tr>
|
|
<tr><td><code><b>MMM</b></code></td><td> Month of the year (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec)</td></tr>
|
|
<tr><td><code><b>dd</b></code></td><td> Day of the month (1,...,31)</td></tr>
|
|
<tr><td><code><b>hh</b></code></td><td> Hour (0,...,23)</td></tr>
|
|
<tr><td><code><b>mm </b></code></td><td> Minute (0,...,59)</td></tr>
|
|
<tr><td><code><b>ss</b></code></td><td> Second (0,...,59)</td></tr>
|
|
<tr><td><code><b>YYYY</b></code></td><td> Year</td></tr>
|
|
</table>
|
|
The string is terminated with a newline character and a null character. The string is
|
|
always 26 characters long (including the terminating newline and null characters).
|
|
<p>
|
|
A pointer to the string is returned.
|
|
<p>
|
|
|
|
Example:
|
|
<blockquote><code><b><pre>
|
|
#include<time.h>
|
|
#include<stdio.h>
|
|
|
|
int main(void)
|
|
{
|
|
time_t timer;
|
|
|
|
timer=time(NULL);
|
|
printf("The current time is %s.\n",asctime(localtime(&timer)));
|
|
return 0;
|
|
}
|
|
</pre></b></code></blockquote>
|
|
<a name="clock"></a>
|
|
<h2>2.15.3 clock</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
clock_t clock(void);
|
|
</b></code></blockquote>
|
|
|
|
Returns the processor clock time used since the beginning of an implementation-defined
|
|
era (normally the beginning of the program). The returned value divided by
|
|
<code><b>CLOCKS_PER_SEC</b></code> results in the number of seconds. If the value is unavailable, then -1 is
|
|
returned.
|
|
<p>
|
|
|
|
Example:
|
|
<blockquote><code><b><pre>
|
|
#include<time.h>
|
|
#include<stdio.h>
|
|
|
|
int main(void)
|
|
{
|
|
clock_t ticks1, ticks2;
|
|
|
|
ticks1=clock();
|
|
ticks2=ticks1;
|
|
while((ticks2/CLOCKS_PER_SEC-ticks1/CLOCKS_PER_SEC)<1)
|
|
ticks2=clock();
|
|
|
|
printf("Took %ld ticks to wait one second.\n",ticks2-ticks1);
|
|
printf("This value should be the same as CLOCKS_PER_SEC which is %ld.\n",CLOCKS_PER_SEC);
|
|
return 0;
|
|
}
|
|
</pre></b></code></blockquote>
|
|
<a name="ctime"></a>
|
|
<h2>2.15.4 ctime</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
char *ctime(const time_t *</b></code><i>timer</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Returns a string representing the localtime based on the argument <i>timer</i>. This is
|
|
equivalent to:
|
|
<blockquote><code><b>
|
|
asctime(locatime(timer));
|
|
</b></code></blockquote>
|
|
The returned string is in the following format:
|
|
<blockquote><code><b>
|
|
DDD MMM dd hh:mm:ss YYYY
|
|
</b></code></blockquote>
|
|
<table border=0>
|
|
<tr><td><code><b>DDD</b></code></td><td> Day of the week (Sun, Mon, Tue, Wed, Thu, Fri, Sat)</td></tr>
|
|
<tr><td><code><b>MMM</b></code></td><td> Month of the year (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec)</td></tr>
|
|
<tr><td><code><b>dd</b></code></td><td> Day of the month (1,...,31)</td></tr>
|
|
<tr><td><code><b>hh</b></code></td><td> Hour (0,...,23)</td></tr>
|
|
<tr><td><code><b>mm</b></code></td><td> Minute (0,...,59)</td></tr>
|
|
<tr><td><code><b>ss</b></code></td><td> Second (0,...,59)</td></tr>
|
|
<tr><td><code><b>YYYY</b></code></td><td> Year</td></tr>
|
|
</table>
|
|
The string is terminated with a newline character and a null character. The string is
|
|
always 26 characters long (including the terminating newline and null characters).
|
|
<p>
|
|
A pointer to the string is returned.
|
|
|
|
<a name="difftime"></a>
|
|
<h2>2.15.5 difftime</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
double difftime(time_t </b></code><i>time1</i><code><b>, time_t </b></code><i>time2</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Calculates the difference of seconds between <i>time1</i> and <i>time2</i> (time1-time2).
|
|
<p>
|
|
Returns the number of seconds.
|
|
|
|
<a name="gmtime"></a>
|
|
<h2>2.15.6 gmtime</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
struct tm *gmtime(const time_t *</b></code><i>timer);
|
|
</b></code></blockquote>
|
|
|
|
The value of timer is broken up into the structure <code><b>tm</b></code> and expressed in Coordinated
|
|
Universal Time (UTC) also known as Greenwich Mean Time (GMT).
|
|
<p>
|
|
A pointer to the structure is returned. A null pointer is returned if UTC is not available.
|
|
|
|
<a name="localtime"></a>
|
|
<h2>2.15.7 localtime</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
struct tm *localtime(const time_t *</b></code><i>timer</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
The value of timer is broken up into the structure <code><b>tm</b></code> and expressed in the local time
|
|
zone.
|
|
<p>
|
|
A pointer to the structure is returned.
|
|
<p>
|
|
|
|
Example:
|
|
<blockquote><code><b><pre>
|
|
#include<time.h>
|
|
#include<stdio.h>
|
|
|
|
int main(void)
|
|
{
|
|
time_t timer;
|
|
|
|
timer=time(NULL);
|
|
printf("The current time is %s.\n",asctime(localtime(&timer)));
|
|
return 0;
|
|
}
|
|
</pre></b></code></blockquote>
|
|
<a name="mktime"></a>
|
|
<h2>2.15.8 mktime</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
time_t mktime(struct tm *</b></code><i>timeptr</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Converts the structure pointed to by <i>timeptr</i> into a <code><b>time_t</b></code> value according to the local
|
|
time zone. The values in the structure are not limited to their constraints. If they exceed their
|
|
bounds, then they are adjusted accordingly so that they fit within their bounds. The original
|
|
values of <code><b>tm_wday</b></code> (day of the week) and <code><b>tm_yday</b></code> (day of the year) are ignored, but are set
|
|
correctly after the other values have been constrained. <code><b>tm_mday</b></code> (day of the month) is not
|
|
corrected until after <code><b>tm_mon</b></code> and <code><b>tm_year</b></code> are corrected.
|
|
<p>
|
|
After adjustment the structure still represents the same time.
|
|
<p>
|
|
The encoded <code><b>time_t</b></code> value is returned. If the calendar time cannot be represented, then -1
|
|
is returned.
|
|
<p>
|
|
|
|
Example:
|
|
<blockquote><code><b><pre>
|
|
#include<time.h>
|
|
#include<stdio.h>
|
|
|
|
/* find out what day of the week is January 1, 2001
|
|
(first day of the 21st century) */
|
|
|
|
int main(void)
|
|
{
|
|
struct tm time_struct;
|
|
char days[7][4]={"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"};
|
|
|
|
time_struct.tm_year=2001-1900;
|
|
time_struct.tm_mon=0;
|
|
time_struct.tm_mday=1;
|
|
time_struct.tm_sec=0;
|
|
time_struct.tm_min=0;
|
|
time_struct.tm_hour=0;
|
|
time_struct.tm_isdst=-1;
|
|
|
|
if(mktime(&time_struct)==-1)
|
|
{
|
|
printf("Error getting time.\n");
|
|
exit(0);
|
|
}
|
|
|
|
printf("January 1, 2001 is a %s.\n",days[time_struct.tm_wday]);
|
|
return 0;
|
|
}
|
|
</pre></b></code></blockquote>
|
|
<a name="strftime"></a>
|
|
<h2>2.15.9 strftime</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
size_t strftime(char *</b></code><i>str</i><code><b>, size_t </b></code><i>maxsize</i><code><b>, const char *</b></code><i>format</i><code><b>, const struct tm *</b></code><i>timeptr</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Formats the time represented in the structure <i>timeptr</i> according to the formatting rules
|
|
defined in <i>format</i> and stored into <i>str</i>. No more than <i>maxsize</i> characters are stored into <i>str</i>
|
|
(including the terminating null character).
|
|
<p>
|
|
All characters in the <i>format</i> string are copied to the <i>str</i> string, including the terminating
|
|
null character, except for conversion characters. A conversion character begins with the <code><b>%</b></code> sign
|
|
and is followed by another character which defines a special value that it is to be replaced by.
|
|
<table border=0>
|
|
<tr><td><b>Conversion<br>Character</b></td><td><b> What it is replaced by</b></td></tr>
|
|
<tr><td><code><b>%a</b></code></td><td> abbreviated weekday name</td></tr>
|
|
<tr><td><code><b>%A</b></code></td><td> full weekday name</td></tr>
|
|
<tr><td><code><b>%b</b></code></td><td> abbreviated month name</td></tr>
|
|
<tr><td><code><b>%B</b></code></td><td> full month name</td></tr>
|
|
<tr><td><code><b>%c</b></code></td><td> appropriate date and time representation</td></tr>
|
|
<tr><td><code><b>%d</b></code></td><td> day of the month (01-31)</td></tr>
|
|
<tr><td><code><b>%H</b></code></td><td> hour of the day (00-23)</td></tr>
|
|
<tr><td><code><b>%I</b></code></td><td> hour of the day (01-12)</td></tr>
|
|
<tr><td><code><b>%j</b></code></td><td> day of the year (001-366)</td></tr>
|
|
<tr><td><code><b>%m</b></code></td><td> month of the year (01-12)</td></tr>
|
|
<tr><td><code><b>%M</b></code></td><td> minute of the hour (00-59)</td></tr>
|
|
<tr><td><code><b>%p</b></code></td><td> AM/PM designator</td></tr>
|
|
<tr><td><code><b>%S</b></code></td><td> second of the minute (00-61)</td></tr>
|
|
<tr><td><code><b>%U</b></code></td><td> week number of the year where Sunday is the first day of week 1 (00-53)</td></tr>
|
|
<tr><td><code><b>%w</b></code></td><td> weekday where Sunday is day 0 (0-6)</td></tr>
|
|
<tr><td><code><b>%W</b></code></td><td> week number of the year where Monday is the first day of week 1 (00-53)</td></tr>
|
|
<tr><td><code><b>%x</b></code></td><td> appropriate date representation</td></tr>
|
|
<tr><td><code><b>%X</b></code></td><td> appropriate time representation</td></tr>
|
|
<tr><td><code><b>%y</b></code></td><td> year without century (00-99)</td></tr>
|
|
<tr><td><code><b>%Y</b></code></td><td> year with century</td></tr>
|
|
<tr><td><code><b>%Z</b></code></td><td> time zone (possibly abbreviated) or no characters if time zone isunavailable</td></tr>
|
|
<tr><td><code><b>%%</b></code></td><td> %</td></tr>
|
|
</table>
|
|
Returns the number of characters stored into str not including the terminating null
|
|
character. On error zero is returned.
|
|
|
|
<a name="time"></a>
|
|
<h2>2.15.10 time</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
time_t time(time_t *</b></code><i>timer</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Calculates the current calender time and encodes it into <code><b>time_t</b></code> format.
|
|
<p>
|
|
The <code><b>time_t</b></code> value is returned. If <i>timer</i> is not a null pointer, then the value is also stored
|
|
into the object it points to. If the time is unavailable, then -1 is returned.
|
|
<hr>
|
|
<center>
|
|
<table border=0 width=100%>
|
|
<tr>
|
|
<td align=left width=20% valign=top>
|
|
<a href="2.14.html">
|
|
<img src="left.gif" border=0>
|
|
Previous Section<br>
|
|
2.14 string.h</a></td>
|
|
<td align=center width=60% valign=top>
|
|
| <a href="index.html">Table of Contents</a> |
|
|
<a href="index2.html">Index</a> |</td>
|
|
<td align=right width=20% valign=top>
|
|
<a href="index2.html">
|
|
Next Section
|
|
<img src="right.gif" border=0><br>
|
|
Index</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
</body>
|
|
</html>
|