<!-- This HTML file has been created by texi2html 1.27
     from library.texinfo on 3 March 1994 -->

<TITLE>The GNU C Library - Date and Time</TITLE>
<P>Go to the <A HREF="library_18.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_18.html">previous</A>, <A HREF="library_20.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_20.html">next</A> section.<P>
<H1><A NAME="SEC309" HREF="library_toc.html#SEC309" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC309">Date and Time</A></H1>
<P>
This chapter describes functions for manipulating dates and times,
including functions for determining what the current time is and
conversion between different time representations.
<P>
The time functions fall into three main categories:
<P>
<UL>
<LI>
Functions for measuring elapsed CPU time are discussed in section <A HREF="library_19.html#SEC310" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC310">Processor Time</A>.
<P>
<LI>
Functions for measuring absolute clock or calendar time are discussed in
section <A HREF="library_19.html#SEC313" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC313">Calendar Time</A>.
<P>
<LI>
Functions for setting alarms and timers are discussed in section <A HREF="library_19.html#SEC321" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC321">Setting an Alarm</A>.
</UL>
<P>
<H2><A NAME="SEC310" HREF="library_toc.html#SEC310" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC310">Processor Time</A></H2>
<P>
If you're trying to optimize your program or measure its efficiency, it's
very useful to be able to know how much <DFN>processor time</DFN> or <DFN>CPU
time</DFN> it has used at any given point.  Processor time is different from
actual wall clock time because it doesn't include any time spent waiting
for I/O or when some other process is running.  Processor time is
represented by the data type <CODE>clock_t</CODE>, and is given as a number of
<DFN>clock ticks</DFN> relative to an arbitrary base time marking the beginning
of a single program invocation.
<A NAME="IDX1346"></A>
<A NAME="IDX1347"></A>
<A NAME="IDX1348"></A>
<A NAME="IDX1349"></A>
<A NAME="IDX1345"></A>
<P>
<H3><A NAME="SEC311" HREF="library_toc.html#SEC311" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC311">Basic CPU Time Inquiry</A></H3>
<P>
To get the elapsed CPU time used by a process, you can use the
<CODE>clock</CODE> function.  This facility is declared in the header file
<TT>`time.h'</TT>.
<A NAME="IDX1350"></A>
<P>
In typical usage, you call the <CODE>clock</CODE> function at the beginning and
end of the interval you want to time, subtract the values, and then divide
by <CODE>CLOCKS_PER_SEC</CODE> (the number of clock ticks per second), like this:
<P>
<PRE>
#include &#60;time.h&#62;

clock_t start, end;
double elapsed;

start = clock();
... /* Do the work. */
end = clock();
elapsed = ((double) (end - start)) / CLOCKS_PER_SEC;
</PRE>
<P>
Different computers and operating systems vary wildly in how they keep
track of processor time.  It's common for the internal processor clock
to have a resolution somewhere between hundredths and millionths of a
second.
<P>
In the GNU system, <CODE>clock_t</CODE> is equivalent to <CODE>long int</CODE> and
<CODE>CLOCKS_PER_SEC</CODE> is an integer value.  But in other systems, both
<CODE>clock_t</CODE> and the type of the macro <CODE>CLOCKS_PER_SEC</CODE> can be
either integer or floating-point types.  Casting processor time values
to <CODE>double</CODE>, as in the example above, makes sure that operations
such as arithmetic and printing work properly and consistently no matter
what the underlying representation is.
<P>
<A NAME="IDX1351"></A>
<U>Macro:</U> int <B>CLOCKS_PER_SEC</B><P>
The value of this macro is the number of clock ticks per second measured
by the <CODE>clock</CODE> function.
<P>
<A NAME="IDX1352"></A>
<U>Macro:</U> int <B>CLK_TCK</B><P>
This is an obsolete name for <CODE>CLOCKS_PER_SEC</CODE>.  
<P>
<A NAME="IDX1353"></A>
<U>Data Type:</U> <B>clock_t</B><P>
This is the type of the value returned by the <CODE>clock</CODE> function.
Values of type <CODE>clock_t</CODE> are in units of clock ticks.
<P>
<A NAME="IDX1354"></A>
<U>Function:</U> clock_t <B>clock</B> <I>(void)</I><P>
This function returns the elapsed processor time.  The base time is
arbitrary but doesn't change within a single process.  If the processor
time is not available or cannot be represented, <CODE>clock</CODE> returns the
value <CODE>(clock_t)(-1)</CODE>.
<P>
<H3><A NAME="SEC312" HREF="library_toc.html#SEC312" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC312">Detailed Elapsed CPU Time Inquiry</A></H3>
<P>
The <CODE>times</CODE> function returns more detailed information about
elapsed processor time in a <CODE>struct tms</CODE> object.  You should
include the header file <TT>`sys/times.h'</TT> to use this facility.
<A NAME="IDX1355"></A>
<P>
<A NAME="IDX1356"></A>
<U>Data Type:</U> <B>struct tms</B><P>
The <CODE>tms</CODE> structure is used to return information about process
times.  It contains at least the following members:
<P>
<DL COMPACT>
<DT><CODE>clock_t tms_utime</CODE>
<DD>This is the CPU time used in executing the instructions of the calling
process.
<P>
<DT><CODE>clock_t tms_stime</CODE>
<DD>This is the CPU time used by the system on behalf of the calling process.
<P>
<DT><CODE>clock_t tms_cutime</CODE>
<DD>This is the sum of the <CODE>tms_utime</CODE> values and the <CODE>tms_cutime</CODE>
values of all terminated child processes of the calling process, whose
status has been reported to the parent process by <CODE>wait</CODE> or
<CODE>waitpid</CODE>; see section <A HREF="library_23.html#SEC407" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_23.html#SEC407">Process Completion</A>.  In other words, it represents
the total CPU time used in executing the instructions of all the terminated
child processes of the calling process.
<P>
<DT><CODE>clock_t tms_cstime</CODE>
<DD>This is similar to <CODE>tms_cutime</CODE>, but represents the total CPU time
used by the system on behalf of all the terminated child processes of the
calling process.
</DL>
<P>
All of the times are given in clock ticks.  These are absolute values; in a
newly created process, they are all zero.  See section <A HREF="library_23.html#SEC405" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_23.html#SEC405">Creating a Process</A>.
<P>
<A NAME="IDX1357"></A>
<U>Function:</U> clock_t <B>times</B> <I>(struct tms *<VAR>buffer</VAR>)</I><P>
The <CODE>times</CODE> function stores the processor time information for
the calling process in <VAR>buffer</VAR>.
<P>
The return value is the same as the value of <CODE>clock()</CODE>: the elapsed
real time relative to an arbitrary base.  The base is a constant within a
particular process, and typically represents the time since system
start-up.  A value of <CODE>(clock_t)(-1)</CODE> is returned to indicate failure.
<P>
<STRONG>Portability Note:</STRONG> The <CODE>clock</CODE> function described in
section <A HREF="library_19.html#SEC311" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC311">Basic CPU Time Inquiry</A>, is specified by the ANSI C standard.  The
<CODE>times</CODE> function is a feature of POSIX.1.  In the GNU system, the
value returned by the <CODE>clock</CODE> function is equivalent to the sum of
the <CODE>tms_utime</CODE> and <CODE>tms_stime</CODE> fields returned by
<CODE>times</CODE>.
<P>
<H2><A NAME="SEC313" HREF="library_toc.html#SEC313" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC313">Calendar Time</A></H2>
<P>
This section describes facilities for keeping track of dates and times
according to the Gregorian calendar.
<A NAME="IDX1359"></A>
<A NAME="IDX1360"></A>
<A NAME="IDX1358"></A>
<P>
There are three representations for date and time information:
<P>
<UL>
<LI>
<DFN>Calendar time</DFN> (the <CODE>time_t</CODE> data type) is a compact 
representation, typically giving the number of seconds elapsed since
some implementation-specific base time.
<A NAME="IDX1361"></A>
<P>
<LI>
There is also a <DFN>high-resolution time</DFN> representation (the <CODE>struct
timeval</CODE> data type) that includes fractions of a second.  Use this time
representation instead of ordinary calendar time when you need greater
precision.
<A NAME="IDX1362"></A>
<P>
<LI>
<DFN>Local time</DFN> or <DFN>broken-down time</DFN> (the <CODE>struct
tm</CODE> data type) represents the date and time as a set of components
specifying the year, month, and so on, for a specific time zone.
This time representation is usually used in conjunction with formatting
date and time values.
<A NAME="IDX1364"></A>
<A NAME="IDX1363"></A>
</UL>
<P>
<H3><A NAME="SEC314" HREF="library_toc.html#SEC314" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC314">Simple Calendar Time</A></H3>
<P>
This section describes the <CODE>time_t</CODE> data type for representing
calendar time, and the functions which operate on calendar time objects.
These facilities are declared in the header file <TT>`time.h'</TT>.
<A NAME="IDX1365"></A>
<A NAME="IDX1366"></A>
<P>
<A NAME="IDX1367"></A>
<U>Data Type:</U> <B>time_t</B><P>
This is the data type used to represent calendar time.  In the GNU C
library and other POSIX-compliant implementations, <CODE>time_t</CODE> is
equivalent to <CODE>long int</CODE>.  When interpreted as an absolute time
value, it represents the number of seconds elapsed since 00:00:00 on
January 1, 1970, Coordinated Universal Time.  (This date is sometimes
referred to as the <DFN>epoch</DFN>.)
<P>
In other systems, <CODE>time_t</CODE> might be either an integer or
floating-point type.
<P>
<A NAME="IDX1368"></A>
<U>Function:</U> double <B>difftime</B> <I>(time_t <VAR>time1</VAR>, time_t <VAR>time0</VAR>)</I><P>
The <CODE>difftime</CODE> function returns the number of seconds elapsed
between time <VAR>time1</VAR> and time <VAR>time0</VAR>, as a value of type
<CODE>double</CODE>.  
<P>
In the GNU system, you can simply subtract <CODE>time_t</CODE> values.  But on
other systems, the <CODE>time_t</CODE> data type might use some other encoding
where subtraction doesn't work directly.
<P>
<A NAME="IDX1369"></A>
<U>Function:</U> time_t <B>time</B> <I>(time_t *<VAR>result</VAR>)</I><P>
The <CODE>time</CODE> function returns the current time as a value of type
<CODE>time_t</CODE>.  If the argument <VAR>result</VAR> is not a null pointer, the
time value is also stored in <CODE>*<VAR>result</VAR></CODE>.  If the calendar 
time is not available, the value <CODE>(time_t)(-1)</CODE> is returned.
<P>
<H3><A NAME="SEC315" HREF="library_toc.html#SEC315" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC315">High-Resolution Calendar</A></H3>
<P>
The <CODE>time_t</CODE> data type used to represent calendar times has a 
resolution of only one second.  Some applications need more precision.
<P>
So, the GNU C library also contains functions which are capable of
representing calendar times to a higher resolution than one second.  The
functions and the associated data types described in this section are
declared in <TT>`sys/time.h'</TT>.
<A NAME="IDX1370"></A>
<P>
<A NAME="IDX1371"></A>
<U>Data Type:</U> <B>struct timeval</B><P>
The <CODE>struct timeval</CODE> structure represents a calendar time.  It
has the following members:
<P>
<DL COMPACT>
<DT><CODE>long int tv_sec</CODE>
<DD>This represents the number of seconds since the epoch.  It is equivalent
to a normal <CODE>time_t</CODE> value.
<P>
<DT><CODE>long int tv_usec</CODE>
<DD>This is the fractional second value, represented as the number of
microseconds.
<P>
Some times struct timeval values are user for time intervals.  Then the
<CODE>tv_sec</CODE> member is the number of seconds in the interval, and
<CODE>tv_usec</CODE> is the number of addictional microseconds.
</DL>
<P>
<A NAME="IDX1372"></A>
<U>Data Type:</U> <B>struct timezone</B><P>
The <CODE>struct timezone</CODE> structure is used to hold minimal information
about the local time zone.  It has the following members:
<P>
<DL COMPACT>
<DT><CODE>int tz_minuteswest</CODE>
<DD>This is the number of minutes west of GMT.
<P>
<DT><CODE>int tz_dsttime</CODE>
<DD>If nonzero, daylight savings time applies during some part of the year.
</DL>
<P>
It is often necessary to subtract two values of type <CODE>struct
timeval</CODE>.  Here is the best way to do this.  It works even on some
peculiar operating systems where the <CODE>tv_sec</CODE> member has an
unsigned type.
<P>
<PRE>
/* Subtract the `struct timeval' values X and Y,
   storing the result in RESULT.
   Return 1 if the difference is negative, otherwise 0.  */

int
timeval_subtract (result, x, y)
     struct timeval *result, *x, *y;
{
  /* Perform the carry for the later subtraction by updating y. */
  if (x-&#62;tv_usec &#60; y-&#62;tv_usec) {
    int nsec = (y-&#62;tv_usec - x-&#62;tv_usec) / 1000000 + 1;
    y-&#62;tv_usec -= 1000000 * nsec;
    y-&#62;tv_sec += nsec;
  }
  if (x-&#62;tv_usec - y-&#62;tv_usec &#62; 1000000) {
    int nsec = (y-&#62;tv_usec - x-&#62;tv_usec) / 1000000;
    y-&#62;tv_usec += 1000000 * nsec;
    y-&#62;tv_sec -= nsec;
  }

  /* Compute the time remaining to wait.
     <CODE>tv_usec</CODE> is certainly positive. */
  result-&#62;tv_sec = x-&#62;tv_sec - y-&#62;tv_sec;
  result-&#62;tv_usec = x-&#62;tv_usec - y-&#62;tv_usec;

  /* Return 1 if result is negative. */
  return x-&#62;tv_sec &#60; y-&#62;tv_sec;
}
</PRE>
<P>
<A NAME="IDX1373"></A>
<U>Function:</U> int <B>gettimeofday</B> <I>(struct timeval *<VAR>tp</VAR>, struct timezone *<VAR>tzp</VAR>)</I><P>
The <CODE>gettimeofday</CODE> function returns the current date and time in the
<CODE>struct timeval</CODE> structure indicated by <VAR>tp</VAR>.  Information about the
time zone is returned in the structure pointed at <VAR>tzp</VAR>.  If the <VAR>tzp</VAR>
argument is a null pointer, time zone information is ignored.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  The
following <CODE>errno</CODE> error condition is defined for this function:
<P>
<DL COMPACT>
<DT><CODE>ENOSYS</CODE>
<DD>The operating system does not support getting time zone information, and
<VAR>tzp</VAR> is not a null pointer.  The GNU operating system does not
support using <CODE>struct timezone</CODE> to represent time zone
information.  Use <CODE>tzname</CODE> et al instead.  <STRONG>Say something
more helpful here.</STRONG>
</DL>
<P>
<A NAME="IDX1374"></A>
<U>Function:</U> int <B>settimeofday</B> <I>(const struct timeval *<VAR>tp</VAR>, const struct timezone *<VAR>tzp</VAR>)</I><P>
The <CODE>settimeofday</CODE> function sets the current date and time
according to the arguments.  As for <CODE>gettimeofday</CODE>, time zone
information is ignored if <VAR>tzp</VAR> is a null pointer.
<P>
You must be a privileged user in order to use <CODE>settimeofday</CODE>.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  The
following <CODE>errno</CODE> error conditions are defined for this function:
<P>