344 lines
16 KiB
HTML
344 lines
16 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title><time.h></title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="<time.h>"></a> <a name="tag_13_76"></a><!-- <time.h> -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_13_76_01"></a>NAME</h4>
|
|
|
|
<blockquote>time.h - time types</blockquote>
|
|
|
|
<h4><a name="tag_13_76_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><tt>#include <time.h></tt></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_76_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<div class="box"><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]"
|
|
border="0"> Some of the functionality described on this reference page extends the ISO C standard. Applications shall define
|
|
the appropriate feature test macro (see the System Interfaces volume of IEEE Std 1003.1-2001, <a href=
|
|
"../functions/xsh_chap02_02.html">Section 2.2, The Compilation Environment</a>) to enable the visibility of these symbols in this
|
|
header. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></div>
|
|
|
|
<p>The <i><time.h></i> header shall declare the structure <b>tm</b>, which shall include at least the following members:</p>
|
|
|
|
<pre>
|
|
<tt>int tm_sec </tt> Seconds [0,60]. <tt>
|
|
int tm_min </tt> Minutes [0,59]. <tt>
|
|
int tm_hour </tt> Hour [0,23]. <tt>
|
|
int tm_mday </tt> Day of month [1,31]. <tt>
|
|
int tm_mon </tt> Month of year [0,11]. <tt>
|
|
int tm_year </tt> Years since 1900. <tt>
|
|
int tm_wday </tt> Day of week [0,6] (Sunday =0). <tt>
|
|
int tm_yday </tt> Day of year [0,365]. <tt>
|
|
int tm_isdst</tt> Daylight Savings flag. <tt>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The value of <i>tm_isdst</i> shall be positive if Daylight Savings Time is in effect, 0 if Daylight Savings Time is not in
|
|
effect, and negative if the information is not available.</p>
|
|
|
|
<p>The <i><time.h></i> header shall define the following symbolic names:</p>
|
|
|
|
<dl compact>
|
|
<dt>NULL</dt>
|
|
|
|
<dd>Null pointer constant.</dd>
|
|
|
|
<dt>CLOCKS_PER_SEC</dt>
|
|
|
|
<dd>A number used to convert the value returned by the <a href="../functions/clock.html"><i>clock</i>()</a> function into
|
|
seconds.</dd>
|
|
|
|
<dt>CLOCK_PROCESS_CPUTIME_ID</dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('TMR')">TMR|CPT</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border=
|
|
"0"><br>
|
|
The identifier of the CPU-time clock associated with the process making a <a href="../functions/clock.html"><i>clock</i>()</a> or
|
|
<i>timer*</i>() function call. <img src="../images/opt-end.gif" alt="[Option End]" border=
|
|
"0"></dd>
|
|
|
|
<dt>CLOCK_THREAD_CPUTIME_ID</dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('TMR')">TMR|TCT</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border=
|
|
"0"><br>
|
|
The identifier of the CPU-time clock associated with the thread making a <a href="../functions/clock.html"><i>clock</i>()</a> or
|
|
<i>timer*</i>() function call. <img src="../images/opt-end.gif" alt="[Option End]" border=
|
|
"0"></dd>
|
|
</dl>
|
|
|
|
<p><sup>[<a href="javascript:open_code('TMR')">TMR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
The <i><time.h></i> header shall declare the structure <b>timespec</b>, which has at least the following members:</p>
|
|
|
|
<pre>
|
|
<tt>time_t tv_sec </tt> Seconds. <tt>
|
|
long tv_nsec </tt> Nanoseconds. <tt>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The <i><time.h></i> header shall also declare the <b>itimerspec</b> structure, which has at least the following
|
|
members:</p>
|
|
|
|
<pre>
|
|
<tt>struct timespec it_interval </tt> Timer period. <tt>
|
|
struct timespec it_value </tt> Timer expiration. <tt>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The following manifest constants shall be defined:</p>
|
|
|
|
<dl compact>
|
|
<dt>CLOCK_REALTIME</dt>
|
|
|
|
<dd>The identifier of the system-wide realtime clock.</dd>
|
|
|
|
<dt>TIMER_ABSTIME</dt>
|
|
|
|
<dd>Flag indicating time is absolute. For functions taking timer objects, this refers to the clock associated with the timer. <img
|
|
src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt>CLOCK_MONOTONIC</dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('MON')">MON</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border=
|
|
"0"><br>
|
|
The identifier for the system-wide monotonic clock, which is defined as a clock whose value cannot be set via <a href=
|
|
"../functions/clock_settime.html"><i>clock_settime</i>()</a> and which cannot have backward clock jumps. The maximum possible clock
|
|
jump shall be implementation-defined. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
</dl>
|
|
|
|
<p>The <b>clock_t</b>, <b>size_t</b>, <b>time_t</b>, <sup>[<a href="javascript:open_code('TMR')">TMR</a>]</sup> <img src=
|
|
"../images/opt-start.gif" alt="[Option Start]" border="0"> <b>clockid_t</b>, and <b>timer_t</b> <img src="../images/opt-end.gif"
|
|
alt="[Option End]" border="0"> types shall be defined as described in <a href="sys/types.h.html"><i><sys/types.h></i></a>
|
|
.</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Although the value of CLOCKS_PER_SEC is required to be 1 million on all XSI-conformant systems, it may be variable on other
|
|
systems, and it should not be assumed that CLOCKS_PER_SEC is a compile-time constant. <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
The <i><time.h></i> header shall provide a declaration for <i>getdate_err</i>. <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></p>
|
|
|
|
<p>The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided.</p>
|
|
|
|
<pre>
|
|
<tt>char *asctime(const struct tm *);
|
|
<sup>[<a href="javascript:open_code('TSF')">TSF</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
char *asctime_r(const struct tm *restrict, char *restrict);
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
|
|
clock_t clock(void);
|
|
<sup>[<a href="javascript:open_code('CPT')">CPT</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
int clock_getcpuclockid(pid_t, clockid_t *);
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
|
|
<sup>[<a href="javascript:open_code('TMR')">TMR</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
int clock_getres(clockid_t, struct timespec *);
|
|
int clock_gettime(clockid_t, struct timespec *);
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
|
|
<sup>[<a href="javascript:open_code('CS')">CS</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
int clock_nanosleep(clockid_t, int, const struct timespec *,
|
|
struct timespec *);
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
|
|
<sup>[<a href="javascript:open_code('TMR')">TMR</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
int clock_settime(clockid_t, const struct timespec *);
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
|
|
char *ctime(const time_t *);
|
|
<sup>[<a href="javascript:open_code('TSF')">TSF</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
char *ctime_r(const time_t *, char *);
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
|
|
double difftime(time_t, time_t);
|
|
<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
struct tm *getdate(const char *);
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
|
|
struct tm *gmtime(const time_t *);
|
|
<sup>[<a href="javascript:open_code('TSF')">TSF</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
struct tm *gmtime_r(const time_t *restrict, struct tm *restrict);
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
|
|
struct tm *localtime(const time_t *);
|
|
<sup>[<a href="javascript:open_code('TSF')">TSF</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
struct tm *localtime_r(const time_t *restrict, struct tm *restrict);
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
|
|
time_t mktime(struct tm *);
|
|
<sup>[<a href="javascript:open_code('TMR')">TMR</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
int nanosleep(const struct timespec *, struct timespec *);
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
|
|
size_t strftime(char *restrict, size_t, const char *restrict,
|
|
const struct tm *restrict);
|
|
<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
char *strptime(const char *restrict, const char *restrict,
|
|
struct tm *restrict);
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
|
|
time_t time(time_t *);
|
|
<sup>[<a href="javascript:open_code('TMR')">TMR</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
int timer_create(clockid_t, struct sigevent *restrict,
|
|
timer_t *restrict);
|
|
int timer_delete(timer_t);
|
|
int timer_gettime(timer_t, struct itimerspec *);
|
|
int timer_getoverrun(timer_t);
|
|
int timer_settime(timer_t, int, const struct itimerspec *restrict,
|
|
struct itimerspec *restrict);
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
|
|
<sup>[<a href="javascript:open_code('CX')">CX</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
void tzset(void);
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
|
|
</tt>
|
|
</pre>
|
|
|
|
<br>
|
|
<p>The following shall be declared as variables:</p>
|
|
|
|
<pre>
|
|
<tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
extern int daylight;
|
|
extern long timezone;
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
|
|
<sup>[<a href="javascript:open_code('CX')">CX</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
extern char *tzname[];
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
|
|
</tt>
|
|
</pre>
|
|
|
|
<p><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Inclusion of the <i><time.h></i> header may make visible all symbols from the <a href=
|
|
"../basedefs/signal.h.html"><i><signal.h></i></a> header. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_13_76_04"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>The range [0,60] for <i>tm_sec</i> allows for the occasional leap second.</p>
|
|
|
|
<p><i>tm_year</i> is a signed value; therefore, years before 1900 may be represented.</p>
|
|
|
|
<p>To obtain the number of clock ticks per second returned by the <a href="../functions/times.html"><i>times</i>()</a> function,
|
|
applications should call <i>sysconf</i>(_SC_CLK_TCK).</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_76_05"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>The range [0,60] seconds allows for positive or negative leap seconds. The formal definition of UTC does not permit double leap
|
|
seconds, so all mention of double leap seconds has been removed, and the range shortened from the former [0,61] seconds seen in
|
|
previous versions of POSIX.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_76_06"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_76_07"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="signal.h.html"><i><signal.h></i></a> , <a href="sys/types.h.html"><i><sys/types.h></i></a> , the System
|
|
Interfaces volume of IEEE Std 1003.1-2001, <a href="../functions/asctime.html"><i>asctime</i>()</a>, <a href=
|
|
"../functions/clock.html"><i>clock</i>()</a>, <a href="../functions/clock_getcpuclockid.html"><i>clock_getcpuclockid</i>()</a>, <a
|
|
href="../functions/clock_getres.html"><i>clock_getres</i>()</a>, <a href=
|
|
"../functions/clock_nanosleep.html"><i>clock_nanosleep</i>()</a>, <a href="../functions/ctime.html"><i>ctime</i>()</a>, <a href=
|
|
"../functions/difftime.html"><i>difftime</i>()</a>, <a href="../functions/getdate.html"><i>getdate</i>()</a>, <a href=
|
|
"../functions/gmtime.html"><i>gmtime</i>()</a>, <a href="../functions/localtime.html"><i>localtime</i>()</a>, <a href=
|
|
"../functions/mktime.html"><i>mktime</i>()</a>, <a href="../functions/nanosleep.html"><i>nanosleep</i>()</a>, <a href=
|
|
"../functions/strftime.html"><i>strftime</i>()</a>, <a href="../functions/strptime.html"><i>strptime</i>()</a>, <a href=
|
|
"../functions/sysconf.html"><i>sysconf</i>()</a>, <a href="../functions/time.html"><i>time</i>()</a>, <a href=
|
|
"../functions/timer_create.html"><i>timer_create</i>()</a>, <a href="../functions/timer_delete.html"><i>timer_delete</i>()</a>, <a
|
|
href="../functions/timer_getoverrun.html"><i>timer_getoverrun</i>()</a>, <i>tzname</i>, <a href=
|
|
"../functions/tzset.html"><i>tzset</i>()</a>, <a href="../functions/utime.html"><i>utime</i>()</a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_76_08"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 1. Derived from Issue 1 of the SVID.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_76_09"></a>Issue 5</h4>
|
|
|
|
<blockquote>
|
|
<p>The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX Threads Extension.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_76_10"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The Open Group Corrigendum U035/6 is applied. In the DESCRIPTION, the types <b>clockid_t</b> and <b>timer_t</b> have been
|
|
described.</p>
|
|
|
|
<p>The following changes are made for alignment with the ISO POSIX-1:1996 standard:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The POSIX timer-related functions are marked as part of the Timers option.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The symbolic name CLK_TCK is removed. Application usage is added describing how its equivalent functionality can be obtained
|
|
using <a href="../functions/sysconf.html"><i>sysconf</i>()</a>.</p>
|
|
|
|
<p>The <a href="../functions/clock_getcpuclockid.html"><i>clock_getcpuclockid</i>()</a> function and manifest constants
|
|
CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID are added for alignment with IEEE Std 1003.1d-1999.</p>
|
|
|
|
<p>The manifest constant CLOCK_MONOTONIC and the <a href="../functions/clock_nanosleep.html"><i>clock_nanosleep</i>()</a> function
|
|
are added for alignment with IEEE Std 1003.1j-2000.</p>
|
|
|
|
<p>The following changes are made for alignment with the ISO/IEC 9899:1999 standard:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The range for seconds is changed from [0,61] to [0,60].</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The <b>restrict</b> keyword is added to the prototypes for <a href="../functions/asctime_r.html"><i>asctime_r</i>()</a>, <a
|
|
href="../functions/gmtime_r.html"><i>gmtime_r</i>()</a>, <a href="../functions/localtime_r.html"><i>localtime_r</i>()</a>, <a href=
|
|
"../functions/strftime.html"><i>strftime</i>()</a>, <a href="../functions/strptime.html"><i>strptime</i>()</a>, <a href=
|
|
"../functions/timer_create.html"><i>timer_create</i>()</a>, and <a href=
|
|
"../functions/timer_settime.html"><i>timer_settime</i>()</a>.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>IEEE PASC Interpretation 1003.1 #84 is applied adding the statement that symbols from the <a href=
|
|
"../basedefs/signal.h.html"><i><signal.h></i></a> header may be made visible when the <i><time.h></i> header is
|
|
included.</p>
|
|
|
|
<p>Extensions beyond the ISO C standard are marked.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|