add directory Ref-docs
This commit is contained in:
gohigh
392
Ref-docs/c_lib_guide/2.15.html
Normal file
392
Ref-docs/c_lib_guide/2.15.html
Normal file
@@ -0,0 +1,392 @@
|
||||
<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>
|
||||
Reference in New Issue
Block a user