305 lines
11 KiB
HTML
305 lines
11 KiB
HTML
<HTML><HEAD><TITLE><time.h></TITLE></HEAD><BODY BGCOLOR="#FFFFFF">
|
|
|
|
<H1><A NAME="<time.h>"><CODE><time.h></CODE></A></H1><HR>
|
|
|
|
<P><CODE>
|
|
#define <A HREF="#CLOCKS_PER_SEC"><B>CLOCKS_PER_SEC</B></A>
|
|
<I><integer constant expression > 0></I><BR>
|
|
#define <A HREF="#NULL"><B>NULL</B></A>
|
|
<I><either 0, 0L, or (void *)0></I> <B>[0 in C++]</B><BR>
|
|
char *<A HREF="#asctime"><B>asctime</B></A>(const
|
|
struct tm *tptr);<BR>
|
|
clock_t <A HREF="#clock"><B>clock</B></A>(void);<BR>
|
|
typedef <I>a-type</I> <A HREF="#clock_t"><B>clock_t</B></A>;<BR>
|
|
char *<A HREF="#ctime"><B>ctime</B></A>(const time_t *tod);<BR>
|
|
double <A HREF="#difftime"><B>difftime</B></A>(time_t t1,
|
|
time_t t0);<BR>
|
|
struct <A HREF="#tm"><B>tm</B></A>
|
|
*gmtime(const time_t *tod);<BR>
|
|
struct <A HREF="#tm"><B>tm</B></A>
|
|
*localtime(const time_t *tod);<BR>
|
|
time_t <A HREF="#mktime"><B>mktime</B></A>(struct tm *tptr);<BR>
|
|
typedef <I>ui-type</I> <A HREF="#size_t"><B>size_t</B></A>;<BR>
|
|
size_t <A HREF="#strftime"><B>strftime</B></A>(char *s,
|
|
size_t n, const char *format, const struct tm *tptr);<BR>
|
|
time_t <A HREF="#time"><B>time</B></A>(time_t *tod);<BR>
|
|
typedef <I>a-type</I> <A HREF="#time_t"><B>time_t</B></A>;<BR>
|
|
struct <A HREF="#tm"><B>tm</B></A>;
|
|
</CODE></P>
|
|
|
|
<P>Include the standard header <B><CODE><time.h></CODE></B> to declare several
|
|
functions that help you manipulate times. The following diagram
|
|
summarizes the functions and the object types that they convert
|
|
between</P>
|
|
|
|
<P><IMG SRC="time.gif" tppabs="http://ccs.ucsd.edu/c/gif/time.gif"></P>
|
|
|
|
<P>The functions share two static-duration objects that hold values
|
|
computed by the functions:</P>
|
|
|
|
<UL>
|
|
<LI>a <B><A NAME="time string">time string</A></B>
|
|
of type array of <I>char</I>
|
|
|
|
<LI>a <B><A NAME="time structure">time structure</A></B>
|
|
of type <CODE>struct tm</CODE>
|
|
</UL>
|
|
|
|
<P>A call to one of these functions can alter the value that was
|
|
stored earlier in a static-duration object by another of these functions.</P>
|
|
|
|
<H2><A NAME="CLOCKS_PER_SEC"><CODE>CLOCKS_PER_SEC</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
#define <B>CLOCKS_PER_SEC</B>
|
|
<I><integer constant expression > 0></I>
|
|
</CODE></P>
|
|
|
|
<P>The macro yields the number of clock ticks,
|
|
returned by <CODE>clock</CODE>, in one second.</P>
|
|
|
|
<H2><A NAME="NULL"><CODE>NULL</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
#define <B>NULL</B> <I><either 0, 0L, or (void *)0></I>
|
|
<B>[0 in C++]</B>
|
|
</CODE></P>
|
|
|
|
<P>The macro yields a null pointer constant that is usable as an
|
|
<A HREF="express.html#address constant expression" tppabs="http://ccs.ucsd.edu/c/express.html#address constant expression">
|
|
address constant expression</A>.</P>
|
|
|
|
<H2><A NAME="asctime"><CODE>asctime</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
char *<B>asctime</B>(const struct tm *tptr);
|
|
</CODE></P>
|
|
|
|
<P>The function stores in the static-duration time string a 26-character
|
|
English-language representation of the time encoded in <CODE>*tptr</CODE>.
|
|
It returns the address of the static-duration
|
|
<A HREF="#time string">time string</A>. The text
|
|
representation takes the form:</P>
|
|
|
|
<PRE>
|
|
Sun Dec 2 06:55:15 1979\n\0</PRE>
|
|
|
|
<H2><A NAME="clock"><CODE>clock</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
clock_t <B>clock</B>(void);
|
|
</CODE></P>
|
|
|
|
<P>The function returns the number of clock ticks of elapsed processor
|
|
time, counting from a time related to
|
|
<A HREF="lib_over.html#program startup" tppabs="http://ccs.ucsd.edu/c/lib_over.html#program startup">program startup</A>, or it returns
|
|
-1 if the target environment cannot measure elapsed processor
|
|
time.</P>
|
|
|
|
<H2><A NAME="clock_t"><CODE>clock_t</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
typedef <I>a-type</I> <B>clock_t</B>;
|
|
</CODE></P>
|
|
|
|
<P>The type is the arithmetic type <CODE><I>a-type</I></CODE>
|
|
of an object that you declare to hold the value returned by
|
|
<A HREF="#clock"><CODE>clock</CODE></A>, representing
|
|
elapsed processor time.</P>
|
|
|
|
<H2><A NAME="ctime"><CODE>ctime</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
char *<B>ctime</B>(const time_t *tod);
|
|
</CODE></P>
|
|
|
|
<P>The function converts the calendar time in <CODE>*tod</CODE> to a
|
|
text representation of the local time in the static-duration
|
|
<A HREF="#time string">time string</A>.
|
|
It returns the address of that string. It is equivalent to
|
|
<CODE><A HREF="#asctime">asctime</A>(localtime(tod))</CODE>.</P>
|
|
|
|
<H2><A NAME="difftime"><CODE>difftime</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
double <B>difftime</B>(time_t t1, time_t t0);
|
|
</CODE></P>
|
|
|
|
<P>The function returns the difference <CODE>t1 - t0</CODE>, in seconds,
|
|
between the calendar time <CODE>t0</CODE>
|
|
and the calendar time <CODE>t1</CODE>.</P>
|
|
|
|
<H2><A NAME="gmtime"><CODE>gmtime</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
struct tm *<B>gmtime</B>(const time_t *tod);
|
|
</CODE></P>
|
|
|
|
<P>The function stores in the static-duration
|
|
<A HREF="#time structure">time structure</A> an
|
|
encoding of the calendar time in <CODE>*tod</CODE>, expressed as
|
|
<B><A NAME="Universal Time Coordinated">
|
|
Universal Time Coordinated</A></B>, or UTC.
|
|
(UTC was formerly Greenwich Mean Time, or GMT).
|
|
It returns the address of that structure.</P>
|
|
|
|
<H2><A NAME="localtime"><CODE>localtime</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
struct tm *<B>localtime</B>(const time_t *tod);
|
|
</CODE></P>
|
|
|
|
<P>The function stores in the static-duration
|
|
<A HREF="#time structure">time structure</A> an
|
|
encoding of the calendar time in <CODE>*tod</CODE>, expressed as local time.
|
|
It returns the address of that structure.</P>
|
|
|
|
<H2><A NAME="mktime"><CODE>mktime</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
time_t <B>mktime</B>(struct tm *tptr);
|
|
</CODE></P>
|
|
|
|
<P>The function alters the values stored in <CODE>*tptr</CODE> to represent
|
|
an equivalent encoded local time, but with the values of all members
|
|
within their normal ranges.
|
|
It then determines the values <CODE>tptr->wday</CODE>
|
|
and <CODE>tptr->yday</CODE> from the values of the other members.
|
|
It returns the calendar time equivalent to the encoded time, or it returns a
|
|
value of -1 if the calendar time cannot be represented.</P>
|
|
|
|
<H2><A NAME="size_t"><CODE>size_t</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
typedef <I>ui-type</I> <B>size_t</B>;
|
|
</CODE></P>
|
|
|
|
<P>The type is the unsigned integer type <CODE><I>ui-type</I></CODE>
|
|
of an object that you declare to store the result of the
|
|
<A HREF="express.html#sizeof operator" tppabs="http://ccs.ucsd.edu/c/express.html#sizeof operator"><I>sizeof</I></A> operator.</P>
|
|
|
|
<H2><A NAME="strftime"><CODE>strftime</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
size_t <B>strftime</B>(char *s, size_t n, const char *format,
|
|
const struct tm *tptr);</CODE>
|
|
|
|
<P>The function generates formatted text, under the control of
|
|
the format <CODE>format</CODE> and the values stored in the time structure
|
|
<CODE>*tptr</CODE>. It stores each generated character
|
|
in successive locations of the array object of size
|
|
<CODE>n</CODE> whose first element has the address <CODE>s</CODE>.
|
|
The function then stores a null character in the next location
|
|
of the array. It returns <CODE>x</CODE>, the number of characters generated,
|
|
if <CODE>x < n</CODE>; otherwise, it returns zero, and the
|
|
values stored in the array are indeterminate.</P>
|
|
|
|
<P>For each multibyte character other than <CODE>%</CODE> in the format,
|
|
the function stores that multibyte character in the array object.
|
|
Each occurrence of <CODE>%</CODE> followed by
|
|
another character in the format is a
|
|
<B><A NAME="conversion specifier">conversion specifier</A></B>.
|
|
For each conversion specifier, the
|
|
function stores a replacement character sequence.</P>
|
|
|
|
<P>The following table lists all conversion specifiers
|
|
defined for <CODE>strftime</CODE>. Example replacement character sequences
|
|
in parentheses follow each conversion specifier. All examples are for the
|
|
<A HREF="locale.html#C locale" tppabs="http://ccs.ucsd.edu/c/locale.html#C locale"><CODE>"C"</CODE></A> locale,
|
|
using the date and time Sunday, 2 December 1979 at 06:55:15 AM EST.</P>
|
|
|
|
<PRE>
|
|
%a <B>abbreviated weekday name (Sun)</B>
|
|
%A <B>full weekday name (Sunday)</B>
|
|
%b <B>abbreviated month name (Dec)</B>
|
|
%B <B>full month name (December)</B>
|
|
%c <B>date and time (Dec 2 06:55:15 1979)</B>
|
|
%d <B>day of the month (02)</B>
|
|
%H <B>hour of the 24-hour day (06)</B>
|
|
%I <B>hour of the 12-hour day (06)</B>
|
|
%j <B>day of the year, from 001 (335)</B>
|
|
%m <B>month of the year, from 01 (12)</B>
|
|
%M <B>minutes after the hour (55)</B>
|
|
%p <B>AM/PM indicator (AM)</B>
|
|
%S <B>seconds after the minute (15)</B>
|
|
%U <B>Sunday week of the year, from 00 (48)</B>
|
|
%w <B>day of the week, from 0 for Sunday (6)</B>
|
|
%W <B>Monday week of the year, from 00 (47)</B>
|
|
%x <B>date (Dec 2 1979)</B>
|
|
%X <B>time (06:55:15)</B>
|
|
%y <B>year of the century, from 00 (79)</B>
|
|
%Y <B>year (1979)</B>
|
|
%Z <B>time zone name, if any (EST)</B>
|
|
%% <B>percent character %</B>
|
|
</PRE>
|
|
|
|
<P>The current
|
|
<A HREF="locale.html#locale category" tppabs="http://ccs.ucsd.edu/c/locale.html#locale category">locale category</A>
|
|
<A HREF="locale.html#LC_TIME" tppabs="http://ccs.ucsd.edu/c/locale.html#LC_TIME"><CODE>LC_TIME</CODE></A> can affect these
|
|
replacement character sequences.</P>
|
|
|
|
<H2><A NAME="time"><CODE>time</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
time_t <B>time</B>(time_t *tod);
|
|
</CODE></P>
|
|
|
|
<P>If <CODE>tod</CODE> is not a null pointer, the function stores the
|
|
current calendar time in <CODE>*tod</CODE>. The function returns the current
|
|
calendar time, if the target environment can determine it; otherwise,
|
|
it returns -1.</P>
|
|
|
|
<H2><A NAME="time_t"><CODE>time_t</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
typedef <I>a-type</I> <B>time_t</B>;
|
|
</CODE></P>
|
|
|
|
<P>The type is the arithmetic type <CODE><I>a-type</I></CODE>
|
|
of an object that you declare to hold
|
|
the value returned by <CODE>time</CODE>.
|
|
The value represents calendar time.</P>
|
|
|
|
<H2><A NAME="tm"><CODE>tm</CODE></A></H2>
|
|
|
|
<PRE>struct <B>tm</B> {
|
|
int tm_sec; <B>seconds after the minute (from 0)</B>
|
|
int tm_min; <B>minutes after the hour (from 0)</B>
|
|
int tm_hour; <B>hour of the day (from 0)</B>
|
|
int tm_mday; <B>day of the month (from 1)</B>
|
|
int tm_mon; <B>month of the year (from 0)</B>
|
|
int tm_year; <B>years since 1900 (from 0)</B>
|
|
int tm_wday; <B>days since Sunday (from 0)</B>
|
|
int tm_yday; <B>day of the year (from 0)</B>
|
|
int tm_isdst; <B>Daylight Saving Time flag</B>
|
|
};
|
|
</PRE>
|
|
|
|
<P><CODE>struct tm</CODE> contains members that describe various
|
|
properties of the calendar time. The members shown above can occur
|
|
in any order, interspersed with additional members. The comment following
|
|
each member briefly describes its meaning.</P>
|
|
|
|
<P>The member <CODE>tm_isdst</CODE> contains:</P>
|
|
|
|
<UL>
|
|
<LI>a positive value if
|
|
<B><A NAME="Daylight Saving Time">Daylight Saving Time</A></B> is in effect
|
|
|
|
<LI>zero if Daylight Saving Time is not in effect
|
|
|
|
<LI>a negative value if the status of Daylight Saving Time is not
|
|
known (so the target environment should attempt to determine its status)
|
|
</UL>
|
|
|
|
<HR>
|
|
<P>See also the
|
|
<B><A HREF="index.html#Table of Contents" tppabs="http://ccs.ucsd.edu/c/index.html#Table of Contents">Table of Contents</A></B> and the
|
|
<B><A HREF="_index.html" tppabs="http://ccs.ucsd.edu/c/_index.html">Index</A></B>.</P>
|
|
|
|
<P><I>
|
|
<A HREF="crit_pb.html" tppabs="http://ccs.ucsd.edu/c/crit_pb.html">Copyright</A> © 1989-1996
|
|
by P.J. Plauger and Jim Brodie. All rights reserved.</I></P>
|
|
|
|
</BODY></HTML>
|