library_19.html

Linux程序员的工作手册

<P>
The second format is used when there is Daylight Saving Time:
<P>
<PRE>
<VAR>std</VAR> <VAR>offset</VAR> <VAR>dst</VAR> [<VAR>offset</VAR>]<CODE>,</CODE><VAR>start</VAR>[<CODE>/</CODE><VAR>time</VAR>]<CODE>,</CODE><VAR>end</VAR>[<CODE>/</CODE><VAR>time</VAR>]
</PRE>
<P>
The initial <VAR>std</VAR> and <VAR>offset</VAR> specify the standard time zone, as
described above.  The <VAR>dst</VAR> string and <VAR>offset</VAR> specify the name
and offset for the corresponding daylight savings time time zone; if the
<VAR>offset</VAR> is omitted, it defaults to one hour ahead of standard time.
<P>
The remainder of the specification describes when daylight savings time is
in effect.  The <VAR>start</VAR> field is when daylight savings time goes into
effect and the <VAR>end</VAR> field is when the change is made back to standard
time.  The following formats are recognized for these fields:
<P>
<DL COMPACT>
<DT><CODE>J<VAR>n</VAR></CODE>
<DD>This specifies the Julian day, with <VAR>n</VAR> between <CODE>1</CODE> and <CODE>365</CODE>.
February 29 is never counted, even in leap years.
<P>
<DT><CODE><VAR>n</VAR></CODE>
<DD>This specifies the Julian day, with <VAR>n</VAR> between <CODE>0</CODE> and <CODE>365</CODE>.
February 29 is counted in leap years.
<P>
<DT><CODE>M<VAR>m</VAR>.<VAR>w</VAR>.<VAR>d</VAR></CODE>
<DD>This specifies day <VAR>d</VAR> of week <VAR>w</VAR> of month <VAR>m</VAR>.  The day
<VAR>d</VAR> must be between <CODE>0</CODE> (Sunday) and <CODE>6</CODE>.  The week
<VAR>w</VAR> must be between <CODE>1</CODE> and <CODE>5</CODE>; week <CODE>1</CODE> is the
first week in which day <VAR>d</VAR> occurs, and week <CODE>5</CODE> specifies the
<EM>last</EM> <VAR>d</VAR> day in the month.  The month <VAR>m</VAR> should be
between <CODE>1</CODE> and <CODE>12</CODE>.
</DL>
<P>
The <VAR>time</VAR> fields specify when, in the local time currently in
effect, the change to the other time occurs.  If omitted, the default is
<CODE>02:00:00</CODE>.
<P>
For example, here is how one would specify the Eastern time zone in the
United States, including the appropriate daylight saving time and its dates
of applicability.  The normal offset from GMT is 5 hours; since this is
west of the prime meridian, the sign is positive.  Summer time begins on
the first Sunday in April at 2:00am, and ends on the last Sunday in October
at 2:00am.
<P>
<PRE>
EST+5EDT,M4.1.0/M10.5.0
</PRE>
<P>
The schedule of daylight savings time in any particular jurisdiction has
changed over the years.  To be strictly correct, the conversion of dates
and times in the past should be based on the schedule that was in effect
then.  However, the system has no facilities to let you specify how the
schedule has changed from year to year.  The most you can do is specify
one particular schedule--usually the present day schedule--and this is
used to convert any date, no matter when.
<P>
The third format looks like this:
<P>
<PRE>
:<VAR>characters</VAR>
</PRE>
<P>
Each operating system interprets this format differently; in the GNU C
library, <VAR>characters</VAR> is the name of a file which describes the time
zone.
<P>
If the <CODE>TZ</CODE> environment variable does not have a value, the
operation chooses a time zone by default.  Each operating system has its
own rules for choosing the default time zone, so there is little we can
say about them.
<P>
<H3><A NAME="SEC319" HREF="library_toc.html#SEC319" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC319">Functions and Variables for Time Zones</A></H3>
<P>
<A NAME="IDX1391"></A>
<U>Variable:</U> char <B>*tzname[2]</B><P>
The array <CODE>tzname</CODE> contains two strings, which are the standard
three-letter names of the pair of time zones (standard and daylight
savings) that the user has selected.  <CODE>tzname[0]</CODE> is the name of
the standard time zone (for example, <CODE>"EST"</CODE>), and <CODE>tzname[1]</CODE>
is the name for the time zone when daylight savings time is in use (for
example, <CODE>"EDT"</CODE>).  These correspond to the <VAR>std</VAR> and <VAR>dst</VAR>
strings (respectively) from the <CODE>TZ</CODE> environment variable.
<P>
The <CODE>tzname</CODE> array is initialized from the <CODE>TZ</CODE> environment
variable whenever <CODE>tzset</CODE>, <CODE>ctime</CODE>, <CODE>strftime</CODE>,
<CODE>mktime</CODE>, or <CODE>localtime</CODE> is called.
<P>
<A NAME="IDX1392"></A>
<U>Function:</U> void <B>tzset</B> <I>(void)</I><P>
The <CODE>tzset</CODE> function initializes the <CODE>tzname</CODE> variable from
the value of the <CODE>TZ</CODE> environment variable.  It is not usually
necessary for your program to call this function, because it is called
automatically when you use the other time conversion functions that
depend on the time zone.
<P>
The following variables are defined for compatibility with System V
Unix.  These variables are set by calling <CODE>localtime</CODE>.
<P>
<A NAME="IDX1393"></A>
<U>Variable:</U> long int <B>timezone</B><P>
This contains the difference between GMT and local standard time, in
seconds.  For example, in the U.S. Eastern time zone, the value is
<CODE>5*60*60</CODE>.
<P>
<A NAME="IDX1394"></A>
<U>Variable:</U> int <B>daylight</B><P>
This variable has a nonzero value if the standard U.S. daylight savings
time rules apply.
<P>
<H3><A NAME="SEC320" HREF="library_toc.html#SEC320" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC320">Time Functions Example</A></H3>
<P>
Here is an example program showing the use of some of the local time and
calendar time functions.
<P>
<PRE>
#include &#60;time.h&#62;
#include &#60;stdio.h&#62;

#define SIZE 256

int
main (void)
{
  char buffer[SIZE];
  time_t curtime;
  struct tm *loctime;

  /* Get the current time.  */
  curtime = time (NULL);

  /* Convert it to local time representation.  */
  loctime = localtime (&#38;curtime);

  /* Print out the date and time in the standard format.  */
  fputs (asctime (loctime), stdout);

  /* Print it out in a nice format.  */
  strftime (buffer, SIZE, "Today is %A, %B %d.\n", loctime);
  fputs (buffer, stdout);
  strftime (buffer, SIZE, "The time is %I:%M %p.\n", loctime);
  fputs (buffer, stdout);

  return 0;
}
</PRE>
<P>
It produces output like this:
<P>
<PRE>
Wed Jul 31 13:02:36 1991
Today is Wednesday, July 31.
The time is 01:02 PM.
</PRE>
<P>
<H2><A NAME="SEC321" HREF="library_toc.html#SEC321" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC321">Setting an Alarm</A></H2>
<P>
The <CODE>alarm</CODE> and <CODE>setitimer</CODE> functions provide a mechanism for a
process to interrupt itself at some future time.  They do this by setting a
timer; when the timer expires, the process recieves a signal.
<A NAME="IDX1395"></A>
<A NAME="IDX1396"></A>
<A NAME="IDX1397"></A>
<A NAME="IDX1398"></A>
<P>
Each process has three independent interval timers available:
<P>
<UL>
<LI>
A real-time timer that counts clock time.  This timer sends a
<CODE>SIGALRM</CODE> signal to the process when it expires.
<A NAME="IDX1399"></A>
<P>
<LI>
A virtual timer that counts CPU time used by the process.  This timer
sends a <CODE>SIGVTALRM</CODE> signal to the process when it expires.
<A NAME="IDX1400"></A>
<P>
<LI>
A profiling timer that counts both CPU time used by the process, and CPU
time spent in system calls on behalf of the process.  This timer sends a
<CODE>SIGPROF</CODE> signal to the process when it expires.
<A NAME="IDX1401"></A>
</UL>
<P>
You can only have one timer of each kind set at any given time.  If you
set a timer that has not yet expired, that timer is simply reset to the
new value.
<P>
You should establish a handler for the appropriate alarm signal using
<CODE>signal</CODE> or <CODE>sigaction</CODE> before issuing a call to <CODE>setitimer</CODE>
or <CODE>alarm</CODE>.  Otherwise, an unusual chain of events could cause the
timer to expire before your program establishes the handler, and in that
case it would be terminated, since that is the default action for the alarm
signals.  See section <A HREF="library_21.html#SEC330" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC330">Signal Handling</A>.
<P>
The <CODE>setitimer</CODE> function is the primary means for setting an alarm.
This facility is declared in the header file <TT>`sys/time.h'</TT>.  The
<CODE>alarm</CODE> function, declared in <TT>`unistd.h'</TT>, provides a somewhat
simpler interface for setting the real-time timer.
<A NAME="IDX1403"></A>
<A NAME="IDX1402"></A>
<P>
<A NAME="IDX1404"></A>
<U>Data Type:</U> <B>struct itimerval</B><P>
This structure is used to specify when a timer should expire.  It contains
the following members:
<DL COMPACT>
<DT><CODE>struct timeval it_interval</CODE>
<DD>This is the interval between successive timer interrupts.  If zero, the
alarm will only be sent once.
<P>
<DT><CODE>struct timeval it_value</CODE>
<DD>This is the interval to the first timer interrupt.  If zero, the alarm is
disabled.
</DL>
<P>
The <CODE>struct timeval</CODE> data type is described in section <A HREF="library_19.html#SEC315" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC315">High-Resolution Calendar</A>.
<P>
<A NAME="IDX1405"></A>
<U>Function:</U> int <B>setitimer</B> <I>(int <VAR>which</VAR>, struct itimerval *<VAR>old</VAR>, struct itimerval *<VAR>new</VAR>)</I><P>
The <CODE>setitimer</CODE> function sets the timer specified by <VAR>which</VAR> 
according to <VAR>new</VAR>.  The <VAR>which</VAR> argument can have a value of
<CODE>ITIMER_REAL</CODE>, <CODE>ITIMER_VIRTUAL</CODE>, or <CODE>ITIMER_PROF</CODE>.
<P>
If <VAR>old</VAR> is not a null pointer, <CODE>setitimer</CODE> returns information
about any previous unexpired timer of the same kind in the structure it
points to.
<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>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>The timer interval was too large.
</DL>
<P>
<A NAME="IDX1406"></A>
<U>Function:</U> int <B>getitimer</B> <I>(int <VAR>which</VAR>, struct itimerval *<VAR>old</VAR>)</I><P>
The <CODE>getitimer</CODE> function stores information about the timer specified
by <VAR>which</VAR> in the structure pointed at by <VAR>old</VAR>.
<P>
The return value and error conditions are the same as for <CODE>setitimer</CODE>.
<P>
<DL COMPACT>
<A NAME="IDX1407"></A>
<DT><CODE>ITIMER_REAL</CODE>
<DD>This constant can be used as the <VAR>which</VAR> argument to the
<CODE>setitimer</CODE> and <CODE>getitimer</CODE> functions to specify the real-time
timer.
<P>
<A NAME="IDX1408"></A>
<DT><CODE>ITIMER_VIRTUAL</CODE>
<DD>This constant can be used as the <VAR>which</VAR> argument to the
<CODE>setitimer</CODE> and <CODE>getitimer</CODE> functions to specify the virtual
timer.
<P>
<A NAME="IDX1409"></A>
<DT><CODE>ITIMER_PROF</CODE>
<DD>This constant can be used as the <VAR>which</VAR> argument to the
<CODE>setitimer</CODE> and <CODE>getitimer</CODE> functions to specify the profiling
timer.
</DL>
<P>
<A NAME="IDX1410"></A>
<U>Function:</U> unsigned int <B>alarm</B> <I>(unsigned int <VAR>seconds</VAR>)</I><P>
The <CODE>alarm</CODE> function sets the real-time timer to expire in
<VAR>seconds</VAR> seconds.  If you want to cancel any existing alarm, you
can do this by calling <CODE>alarm</CODE> with a <VAR>seconds</VAR> argument of
zero.
<P>
The return value indicates how many seconds remain before the previous
alarm would have been sent.  If there is no previous alarm, <CODE>alarm</CODE>
returns zero.
<P>
The <CODE>alarm</CODE> function could be defined in terms of <CODE>setitimer</CODE>
like this:
<P>
<PRE>
unsigned int
alarm (unsigned int seconds)
{
  struct itimerval old, new;
  new.it_interval.tv_usec = 0;
  new.it_interval.tv_sec = 0;
  new.it_value.tv_usec = 0;
  new.it_value.tv_sec = (long int) seconds;
  if (setitimer (ITIMER_REAL, &#38;new, &#38;old) &#60; 0)
    return 0;
  else
    return old.it_value.tv_sec;
}
</PRE>
<P>
There is an example showing the use of the <CODE>alarm</CODE> function in
section <A HREF="library_21.html#SEC352" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC352">Signal Handlers That Return</A>.
<P>
If you simply want your process to wait for a given number of seconds,
you should use the <CODE>sleep</CODE> function.  See section <A HREF="library_19.html#SEC322" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC322">Sleeping</A>.
<P>
You shouldn't count on the signal arriving precisely when the timer
expires.  In a multiprocessing environment there is typically some
amount of delay involved.
<P>
<STRONG>Portability Note:</STRONG> The <CODE>setitimer</CODE> and <CODE>getitimer</CODE>
functions are derived from BSD Unix, while the <CODE>alarm</CODE> function is
specified by the POSIX.1 standard.  <CODE>setitimer</CODE> is more powerful than
<CODE>alarm</CODE>, but <CODE>alarm</CODE> is more widely used.
<P>
<H2><A NAME="SEC322" HREF="library_toc.html#SEC322" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC322">Sleeping</A></H2>
<P>
The function <CODE>sleep</CODE> gives a simple way to make the program wait
for short periods of time.  If your program doesn't use signals (except
to terminate), then you can expect <CODE>sleep</CODE> to wait reliably for
the specified amount of time.  Otherwise, <CODE>sleep</CODE> can return sooner
if a signal arrives; if you want to wait for a given period regardless
of signals, use <CODE>select</CODE> (see section <A HREF="library_12.html#SEC180" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC180">Waiting for Input or Output</A>) and don't
specify any descriptors to wait for.
<P>
<A NAME="IDX1411"></A>
<U>Function:</U> unsigned int <B>sleep</B> <I>(unsigned int <VAR>seconds</VAR>)</I><P>
The <CODE>sleep</CODE> function waits for <VAR>seconds</VAR> or until a signal
is delivered, whichever happens first.  
<P>
If <CODE>sleep</CODE> function returns because the requested time has
elapsed, it returns a value of zero.  If it returns because of delivery
of a signal, its return value is the remaining time in the sleep period.
<P>
The <CODE>sleep</CODE> function is declared in <TT>`unistd.h'</TT>.
<P>
Resist the temptation to implement a sleep for a fixed amount of time by