time.texi

一个C源代码分析器

@node Date and Time, Non-Local Exits, Arithmetic, Top
@chapter Date and Time

This chapter describes functions for manipulating dates and times,
including functions for determining what the current time is and
conversion between different time representations.

The time functions fall into three main categories:

@itemize @bullet
@item 
Functions for measuring elapsed CPU time are discussed in @ref{Processor
Time}.

@item
Functions for measuring absolute clock or calendar time are discussed in
@ref{Calendar Time}.

@item
Functions for setting alarms and timers are discussed in @ref{Setting
an Alarm}.
@end itemize

@menu
* Processor Time::              Measures processor time used by a program.
* Calendar Time::               Manipulation of ``real'' dates and times.
* Setting an Alarm::            Sending a signal after a specified time.
* Sleeping::                    Waiting for a period of time.
* Resource Usage::		Measuring various resources used.
* Limits on Resources::		Specifying limits on resource usage.
* Priority::			Reading or setting process run priority.
@end menu

@node Processor Time
@section Processor Time

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} or @dfn{CPU
time} 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}, and is given as a number of
@dfn{clock ticks} relative to an arbitrary base time marking the beginning
of a single program invocation.
@cindex CPU time
@cindex processor time
@cindex clock ticks
@cindex ticks, clock
@cindex time, elapsed CPU

@menu
* Basic CPU Time::              The @code{clock} function.
* Detailed CPU Time::           The @code{times} function.
@end menu

@node Basic CPU Time
@subsection Basic CPU Time Inquiry

To get the elapsed CPU time used by a process, you can use the
@code{clock} function.  This facility is declared in the header file
@file{time.h}.
@pindex time.h

In typical usage, you call the @code{clock} function at the beginning and
end of the interval you want to time, subtract the values, and then divide
by @code{CLOCKS_PER_SEC} (the number of clock ticks per second), like this:

@smallexample
@group
#include <time.h>

clock_t start, end;
double elapsed;

start = clock();
@dots{} /* @r{Do the work.} */
end = clock();
elapsed = ((double) (end - start)) / CLOCKS_PER_SEC;
@end group
@end smallexample

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.

In the GNU system, @code{clock_t} is equivalent to @code{long int} and
@code{CLOCKS_PER_SEC} is an integer value.  But in other systems, both
@code{clock_t} and the type of the macro @code{CLOCKS_PER_SEC} can be
either integer or floating-point types.  Casting processor time values
to @code{double}, 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.

@comment time.h
@comment ANSI
@deftypevr Macro int CLOCKS_PER_SEC
The value of this macro is the number of clock ticks per second measured
by the @code{clock} function.
@end deftypevr

@comment time.h
@comment POSIX.1
@deftypevr Macro int CLK_TCK
This is an obsolete name for @code{CLOCKS_PER_SEC}.  
@end deftypevr

@comment time.h
@comment ANSI
@deftp {Data Type} clock_t
This is the type of the value returned by the @code{clock} function.
Values of type @code{clock_t} are in units of clock ticks.
@end deftp

@comment time.h
@comment ANSI
@deftypefun clock_t clock (void)
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} returns the
value @code{(clock_t)(-1)}.
@end deftypefun


@node Detailed CPU Time
@subsection Detailed Elapsed CPU Time Inquiry

The @code{times} function returns more detailed information about
elapsed processor time in a @w{@code{struct tms}} object.  You should
include the header file @file{sys/times.h} to use this facility.
@pindex sys/times.h

@comment sys/times.h
@comment POSIX.1
@deftp {Data Type} {struct tms}
The @code{tms} structure is used to return information about process
times.  It contains at least the following members:

@table @code
@item clock_t tms_utime
This is the CPU time used in executing the instructions of the calling
process.

@item clock_t tms_stime
This is the CPU time used by the system on behalf of the calling process.

@item clock_t tms_cutime
This is the sum of the @code{tms_utime} values and the @code{tms_cutime}
values of all terminated child processes of the calling process, whose
status has been reported to the parent process by @code{wait} or
@code{waitpid}; see @ref{Process Completion}.  In other words, it
represents the total CPU time used in executing the instructions of all
the terminated child processes of the calling process, excluding child
processes which have not yet been reported by @code{wait} or
@code{waitpid}.

@item clock_t tms_cstime
This is similar to @code{tms_cutime}, but represents the total CPU time
used by the system on behalf of all the terminated child processes of the
calling process.
@end table

All of the times are given in clock ticks.  These are absolute values; in a
newly created process, they are all zero.  @xref{Creating a Process}.
@end deftp

@comment sys/times.h
@comment POSIX.1
@deftypefun clock_t times (struct tms *@var{buffer})
The @code{times} function stores the processor time information for
the calling process in @var{buffer}.

The return value is the same as the value of @code{clock()}: 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)} is returned to indicate failure.
@end deftypefun

@strong{Portability Note:} The @code{clock} function described in
@ref{Basic CPU Time}, is specified by the ANSI C standard.  The
@code{times} function is a feature of POSIX.1.  In the GNU system, the
value returned by the @code{clock} function is equivalent to the sum of
the @code{tms_utime} and @code{tms_stime} fields returned by
@code{times}.

@node Calendar Time
@section Calendar Time

This section describes facilities for keeping track of dates and times
according to the Gregorian calendar.
@cindex Gregorian calendar
@cindex time, calendar
@cindex date and time

There are three representations for date and time information:

@itemize @bullet
@item 
@dfn{Calendar time} (the @code{time_t} data type) is a compact 
representation, typically giving the number of seconds elapsed since
some implementation-specific base time.
@cindex calendar time

@item
There is also a @dfn{high-resolution time} representation (the @code{struct
timeval} data type) that includes fractions of a second.  Use this time
representation instead of ordinary calendar time when you need greater
precision.
@cindex high-resolution time

@item
@dfn{Local time} or @dfn{broken-down time} (the @code{struct
tm} 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.
@cindex local time
@cindex broken-down time
@end itemize

@menu
* Simple Calendar Time::        Facilities for manipulating calendar time.
* High-Resolution Calendar::    A time representation with greater precision.
* Broken-down Time::            Facilities for manipulating local time.
* Formatting Date and Time::    Converting times to strings.
* TZ Variable::                 How users specify the time zone.
* Time Zone Functions::         Functions to examine or specify the time zone. 
* Time Functions Example::      An example program showing use of some of
				 the time functions.
@end menu

@node Simple Calendar Time
@subsection Simple Calendar Time

This section describes the @code{time_t} data type for representing
calendar time, and the functions which operate on calendar time objects.
These facilities are declared in the header file @file{time.h}.
@pindex time.h

@cindex epoch
@comment time.h
@comment ANSI
@deftp {Data Type} time_t
This is the data type used to represent calendar time.  In the GNU C
library and other POSIX-compliant implementations, @code{time_t} is
equivalent to @code{long int}.  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}.)

In other systems, @code{time_t} might be either an integer or
floating-point type.
@end deftp

@comment time.h
@comment ANSI
@deftypefun double difftime (time_t @var{time1}, time_t @var{time0})
The @code{difftime} function returns the number of seconds elapsed
between time @var{time1} and time @var{time0}, as a value of type
@code{double}.  

In the GNU system, you can simply subtract @code{time_t} values.  But on
other systems, the @code{time_t} data type might use some other encoding
where subtraction doesn't work directly.
@end deftypefun

@comment time.h
@comment ANSI
@deftypefun time_t time (time_t *@var{result})
The @code{time} function returns the current time as a value of type
@code{time_t}.  If the argument @var{result} is not a null pointer, the
time value is also stored in @code{*@var{result}}.  If the calendar 
time is not available, the value @code{(time_t)(-1)} is returned.
@end deftypefun


@node High-Resolution Calendar
@subsection High-Resolution Calendar

The @code{time_t} data type used to represent calendar times has a 
resolution of only one second.  Some applications need more precision.

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 @file{sys/time.h}.
@pindex sys/time.h

@comment sys/time.h
@comment BSD
@deftp {Data Type} {struct timeval}
The @code{struct timeval} structure represents a calendar time.  It
has the following members:

@table @code
@item long int tv_sec
This represents the number of seconds since the epoch.  It is equivalent
to a normal @code{time_t} value.

@item long int tv_usec
This is the fractional second value, represented as the number of
microseconds.

Some times struct timeval values are used for time intervals.  Then the
@code{tv_sec} member is the number of seconds in the interval, and
@code{tv_usec} is the number of additional microseconds.
@end table
@end deftp

@comment sys/time.h
@comment BSD
@deftp {Data Type} {struct timezone}
The @code{struct timezone} structure is used to hold minimal information
about the local time zone.  It has the following members:

@table @code
@item int tz_minuteswest
This is the number of minutes west of GMT.

@item int tz_dsttime
If nonzero, daylight savings time applies during some part of the year.
@end table

The @code{struct timezone} type is obsolete and should never be used.
Instead, use the facilities described in @ref{Time Zone Functions}.
@end deftp

It is often necessary to subtract two values of type @w{@code{struct
timeval}}.  Here is the best way to do this.  It works even on some
peculiar operating systems where the @code{tv_sec} member has an
unsigned type.

@smallexample
/* @r{Subtract the `struct timeval' values X and Y,}
   @r{storing the result in RESULT.}
   @r{Return 1 if the difference is negative, otherwise 0.}  */

int
timeval_subtract (result, x, y)
     struct timeval *result, *x, *y;
@{
  /* @r{Perform the carry for the later subtraction by updating @var{y}.} */
  if (x->tv_usec < y->tv_usec) @{
    int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1;
    y->tv_usec -= 1000000 * nsec;
    y->tv_sec += nsec;
  @}
  if (x->tv_usec - y->tv_usec > 1000000) @{
    int nsec = (y->tv_usec - x->tv_usec) / 1000000;
    y->tv_usec += 1000000 * nsec;
    y->tv_sec -= nsec;
  @}

  /* @r{Compute the time remaining to wait.}
     @r{@code{tv_usec} is certainly positive.} */
  result->tv_sec = x->tv_sec - y->tv_sec;
  result->tv_usec = x->tv_usec - y->tv_usec;

  /* @r{Return 1 if result is negative.} */
  return x->tv_sec < y->tv_sec;
@}
@end smallexample

@comment sys/time.h
@comment BSD
@deftypefun int gettimeofday (struct timeval *@var{tp}, struct timezone *@var{tzp})
The @code{gettimeofday} function returns the current date and time in the
@code{struct timeval} structure indicated by @var{tp}.  Information about the
time zone is returned in the structure pointed at @var{tzp}.  If the @var{tzp}
argument is a null pointer, time zone information is ignored.

The return value is @code{0} on success and @code{-1} on failure.  The
following @code{errno} error condition is defined for this function:

@table @code
@item ENOSYS
The operating system does not support getting time zone information, and
@var{tzp} is not a null pointer.  The GNU operating system does not
support using @w{@code{struct timezone}} to represent time zone
information; that is an obsolete feature of 4.3 BSD.
Instead, use the facilities described in @ref{Time Zone Functions}.
@end table
@end deftypefun

@comment sys/time.h
@comment BSD
@deftypefun int settimeofday (const struct timeval *@var{tp}, const struct timezone *@var{tzp})
The @code{settimeofday} function sets the current date and time
according to the arguments.  As for @code{gettimeofday}, time zone
information is ignored if @var{tzp} is a null pointer.

You must be a privileged user in order to use @code{settimeofday}.

The return value is @code{0} on success and @code{-1} on failure.  The