library_19.html

Linux程序员的工作手册

<DL COMPACT>
<DT><CODE>EPERM</CODE>
<DD>This process cannot set the time because it is not privileged.
<P>
<DT><CODE>ENOSYS</CODE>
<DD>The operating system does not support setting time zone information, and
<VAR>tzp</VAR> is not a null pointer.
</DL>
<P>
<A NAME="IDX1375"></A>
<U>Function:</U> int <B>adjtime</B> <I>(const struct timeval *<VAR>delta</VAR>, struct timeval *<VAR>olddelta</VAR>)</I><P>
This function speeds up or slows down the system clock in order to make
gradual adjustments in the current time.  This ensures that the time
reported by the system clock is always monotonically increasing, which
might not happen if you simply set the current time.
<P>
The <VAR>delta</VAR> argument specifies a relative adjustment to be made to
the current time.  If negative, the system clock is slowed down for a
while until it has lost this much time.  If positive, the system clock
is speeded up for a while.
<P>
If the <VAR>olddelta</VAR> argument is not a null pointer, the <CODE>adjtime</CODE>
function returns information about any previous time adjustment that
has not yet completed.
<P>
This function is typically used to synchronize the clocks of computers
in a local network.  You must be a privileged user to use it.
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>EPERM</CODE>
<DD>You do not have privilege to set the time.
</DL>
<P>
<STRONG>Portability Note:</STRONG>  The <CODE>gettimeofday</CODE>, <CODE>settimeofday</CODE>,
and <CODE>adjtime</CODE> functions are derived from BSD.  
<P>
<A NAME="IDX1376"></A>
<A NAME="IDX1377"></A>
<H3><A NAME="SEC316" HREF="library_toc.html#SEC316" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC316">Broken-down Time</A></H3>
<P>
Calender time is represented as a number of seconds.  This is convenient
for calculation, but has no resemblance to the way people normally
represent dates and times.  By contrast, <DFN>broken-down time</DFN> is a binary
representation separated into year, month, day, and so on.  Broken down
time values are not useful for calculations, but they are useful for
printing human readable time.
<P>
A broken-down time value is always relative to a choice of local time
zone, and it also indicates which time zone was used.
<P>
The symbols in this section are declared in the header file <TT>`time.h'</TT>.
<P>
<A NAME="IDX1378"></A>
<U>Data Type:</U> <B>struct tm</B><P>
This is the data type used to represent a broken-down time.  The structure
contains at least the following members, which can appear in any order:
<P>
<DL COMPACT>
<DT><CODE>int tm_sec</CODE>
<DD>This is the number of seconds after the minute, normally in the range
<CODE>0</CODE> to <CODE>59</CODE>.  (The actual upper limit is <CODE>61</CODE>, to allow
for "leap seconds".)
<A NAME="IDX1379"></A>
<P>
<DT><CODE>int tm_min</CODE>
<DD>This is the number of minutes after the hour, in the range <CODE>0</CODE> to
<CODE>59</CODE>.
<P>
<DT><CODE>int tm_hour</CODE>
<DD>This is the number of hours past midnight, in the range <CODE>0</CODE> to
<CODE>23</CODE>.
<P>
<DT><CODE>int tm_mday</CODE>
<DD>This is the day of the month, in the range <CODE>1</CODE> to <CODE>31</CODE>.
<P>
<DT><CODE>int tm_mon</CODE>
<DD>This is the number of months since January, in the range <CODE>0</CODE> to
<CODE>11</CODE>.
<P>
<DT><CODE>int tm_year</CODE>
<DD>This is the number of years since <CODE>1900</CODE>.
<P>
<DT><CODE>int tm_wday</CODE>
<DD>This is the number of days since Sunday, in the range <CODE>0</CODE> to <CODE>6</CODE>.
<P>
<DT><CODE>int tm_yday</CODE>
<DD>This is the number of days since January 1, in the range <CODE>0</CODE> to
<CODE>365</CODE>.
<P>
<A NAME="IDX1380"></A>
<A NAME="IDX1381"></A>
<DT><CODE>int tm_isdst</CODE>
<DD>This is a flag that indicates whether Daylight Saving Time is (or was, or
will be) in effect at the time described.  The value is positive if
Daylight Saving Time is in effect, zero if it is not, and negative if the
information is not available.
<P>
<DT><CODE>long int tm_gmtoff</CODE>
<DD>This field describes the time zone that was used to compute this
broken-down time value; it is the amount you must add to the local time
in that zone to get GMT, in units of seconds.  The value is like that of
the variable <CODE>timezone</CODE> (see section <A HREF="library_19.html#SEC319" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC319">Functions and Variables for Time Zones</A>).  You can
also think of this as the "number of seconds west" of GMT.  The
<CODE>tm_gmtoff</CODE> field is a GNU library extension.
<P>
<DT><CODE>const char *tm_zone</CODE>
<DD>This field is the three-letter name for the time zone that was used to
compute this broken-down time value.  It is a GNU library extension.
</DL>
<P>
<A NAME="IDX1382"></A>
<U>Function:</U> struct tm * <B>localtime</B> <I>(const time_t *<VAR>time</VAR>)</I><P>
The <CODE>localtime</CODE> function converts the calendar time pointed to by
<VAR>time</VAR> to broken-down time representation, expressed relative to the
user's specified time zone.
<P>
The return value is a pointer to a static broken-down time structure, which
might be overwritten by subsequent calls to any of the date and time
functions.  (But no other library function overwrites the contents of this
object.)
<P>
Calling <CODE>localtime</CODE> has one other effect: it sets the variable
<CODE>tzname</CODE> with information about the current time zone.  See section <A HREF="library_19.html#SEC319" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC319">Functions and Variables for Time Zones</A>.
<P>
<A NAME="IDX1383"></A>
<U>Function:</U> struct tm * <B>gmtime</B> <I>(const time_t *<VAR>time</VAR>)</I><P>
This function is similar to <CODE>localtime</CODE>, except that the broken-down
time is expressed as Coordinated Universal Time (UTC)---that is, as
Greenwich Mean Time (GMT) rather than relative to the local time zone.
<P>
Recall that calendar times are <EM>always</EM> expressed in coordinated
universal time.
<P>
<A NAME="IDX1384"></A>
<U>Function:</U> time_t <B>mktime</B> <I>(struct tm *<VAR>brokentime</VAR>)</I><P>
The <CODE>mktime</CODE> function is used to convert a broken-down time structure
to a calendar time representation.  It also "normalizes" the contents of
the broken-down time structure, by filling in the day of week and day of
year based on the other date and time components.
<P>
The <CODE>mktime</CODE> function ignores the specified contents of the
<CODE>tm_wday</CODE> and <CODE>tm_yday</CODE> members of the broken-down time
structure.  It uses the values of the other components to compute the
calendar time; it's permissible for these components to have
unnormalized values outside of their normal ranges.  The last thing that
<CODE>mktime</CODE> does is adjust the components of the <VAR>brokentime</VAR>
structure (including the <CODE>tm_wday</CODE> and <CODE>tm_yday</CODE>).
<P>
If the specified broken-down time cannot be represented as a calendar time,
<CODE>mktime</CODE> returns a value of <CODE>(time_t)(-1)</CODE> and does not modify
the contents of <VAR>brokentime</VAR>.
<P>
Calling <CODE>mktime</CODE> also sets the variable <CODE>tzname</CODE> with
information about the current time zone.  See section <A HREF="library_19.html#SEC319" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC319">Functions and Variables for Time Zones</A>.
<P>
<H3><A NAME="SEC317" HREF="library_toc.html#SEC317" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC317">Formatting Date and Time</A></H3>
<P>
The functions described in this section format time values as strings.
These functions are declared in the header file <TT>`time.h'</TT>.
<A NAME="IDX1385"></A>
<P>
<A NAME="IDX1386"></A>
<U>Function:</U> char * <B>asctime</B> <I>(const struct tm *<VAR>brokentime</VAR>)</I><P>
The <CODE>asctime</CODE> function writes the broken-down time value pointed at by
<VAR>brokentime</VAR> into a string in a standard format:
<P>
<PRE>
"Tue May 21 13:46:22 1991\n"
</PRE>
<P>
The abbreviations for the days of week are: <SAMP>`Sun'</SAMP>, <SAMP>`Mon'</SAMP>,
<SAMP>`Tue'</SAMP>, <SAMP>`Wed'</SAMP>, <SAMP>`Thu'</SAMP>, <SAMP>`Fri'</SAMP>, and <SAMP>`Sat'</SAMP>.
<P>
The abbreviations for the months are: <SAMP>`Jan'</SAMP>, <SAMP>`Feb'</SAMP>,
<SAMP>`Mar'</SAMP>, <SAMP>`Apr'</SAMP>, <SAMP>`May'</SAMP>, <SAMP>`Jun'</SAMP>, <SAMP>`Jul'</SAMP>, <SAMP>`Aug'</SAMP>,
<SAMP>`Sep'</SAMP>, <SAMP>`Oct'</SAMP>, <SAMP>`Nov'</SAMP>, and <SAMP>`Dec'</SAMP>.
<P>
The return value points to a statically allocated string, which might be
overwritten by subsequent calls to any of the date and time functions.
(But no other library function overwrites the contents of this
string.)
<P>
<A NAME="IDX1387"></A>
<U>Function:</U> char * <B>ctime</B> <I>(const time_t *<VAR>time</VAR>)</I><P>
The <CODE>ctime</CODE> function is similar to <CODE>asctime</CODE>, except that
the time value is specified in calendar time (rather than local time)
format.  It is equivalent to
<P>
<PRE>
asctime (localtime (<VAR>time</VAR>))
</PRE>
<P>
<CODE>ctime</CODE> sets the variable <CODE>tzname</CODE>, because <CODE>localtime</CODE>
does so.  See section <A HREF="library_19.html#SEC319" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC319">Functions and Variables for Time Zones</A>.
<P>
<A NAME="IDX1388"></A>
<U>Function:</U> size_t <B>strftime</B> <I>(char *<VAR>s</VAR>, size_t <VAR>size</VAR>, const char *<VAR>template</VAR>, const struct tm *<VAR>brokentime</VAR>)</I><P>
This function is similar to the <CODE>sprintf</CODE> function (see section <A HREF="library_11.html#SEC145" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html#SEC145">Formatted Input</A>), but the conversion specifications that can appear in the format
template <VAR>template</VAR> are specialized for printing components of the date
and time <VAR>brokentime</VAR> according to the locale currently specified for
time conversion (see section <A HREF="library_7.html#SEC76" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_7.html#SEC76">Locales and Internationalization</A>).
<P>
Ordinary characters appearing in the <VAR>template</VAR> are copied to the
output string <VAR>s</VAR>; this can include multibyte character sequences.
Conversion specifiers are introduced by a <SAMP>`%'</SAMP> character, and are
replaced in the output string as follows:
<P>
<DL COMPACT>
<DT><CODE>%a</CODE>
<DD>The abbreviated weekday name according to the current locale.
<P>
<DT><CODE>%A</CODE>
<DD>The full weekday name according to the current locale.
<P>
<DT><CODE>%b</CODE>
<DD>The abbreviated month name according to the current locale.
<P>
<DT><CODE>%B</CODE>
<DD>The full month name according to the current locale.
<P>
<DT><CODE>%c</CODE>
<DD>The preferred date and time representation for the current locale.
<P>
<DT><CODE>%d</CODE>
<DD>The day of the month as a decimal number (range <CODE>01</CODE> to <CODE>31</CODE>).
<P>
<DT><CODE>%H</CODE>
<DD>The hour as a decimal number, using a 24-hour clock (range <CODE>00</CODE> to
<CODE>23</CODE>).
<P>
<DT><CODE>%I</CODE>
<DD>The hour as a decimal number, using a 12-hour clock (range <CODE>01</CODE> to
<CODE>12</CODE>).
<P>
<DT><CODE>%j</CODE>
<DD>The day of the year as a decimal number (range <CODE>001</CODE> to <CODE>366</CODE>).
<P>
<DT><CODE>%m</CODE>
<DD>The month as a decimal number (range <CODE>01</CODE> to <CODE>12</CODE>).
<P>
<DT><CODE>%M</CODE>
<DD>The minute as a decimal number.
<P>
<DT><CODE>%p</CODE>
<DD>Either <SAMP>`am'</SAMP> or <SAMP>`pm'</SAMP>, according to the given time value; or the
corresponding strings for the current locale.
<P>
<DT><CODE>%S</CODE>
<DD>The second as a decimal number.
<P>
<DT><CODE>%U</CODE>
<DD>The week number of the current year as a decimal number, starting with
the first Sunday as the first day of the first week.
<P>
<DT><CODE>%W</CODE>
<DD>The week number of the current year as a decimal number, starting with
the first Monday as the first day of the first week.
<P>
<DT><CODE>%w</CODE>
<DD>The day of the week as a decimal number, Sunday being <CODE>0</CODE>.
<P>
<DT><CODE>%x</CODE>
<DD>The preferred date representation for the current locale, but without the
time.
<P>
<DT><CODE>%X</CODE>
<DD>The preferred time representation for the current locale, but with no date.
<P>
<DT><CODE>%y</CODE>
<DD>The year as a decimal number, but without a century (range <CODE>00</CODE> to
<CODE>99</CODE>).
<P>
<DT><CODE>%Y</CODE>
<DD>The year as a decimal number, including the century.
<P>
<DT><CODE>%Z</CODE>
<DD>The time zone or name or abbreviation (empty if the time zone can't be
determined).
<P>
<DT><CODE>%%</CODE>
<DD>A literal <SAMP>`%'</SAMP> character.
</DL>
<P>
The <VAR>size</VAR> parameter can be used to specify the maximum number of
characters to be stored in the array <VAR>s</VAR>, including the terminating
null character.  If the formatted time requires more than <VAR>size</VAR>
characters, the excess characters are discarded.  The return value from
<CODE>strftime</CODE> is the number of characters placed in the array <VAR>s</VAR>,
not including the terminating null character.  If the value equals
<VAR>size</VAR>, it means that the array <VAR>s</VAR> was too small; you should
repeat the call, providing a bigger array.
<P>
For an example of <CODE>strftime</CODE>, see section <A HREF="library_19.html#SEC320" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC320">Time Functions Example</A>.
<P>
<H3><A NAME="SEC318" HREF="library_toc.html#SEC318" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC318">Specifying the Time Zone with <CODE>TZ</CODE></A></H3>
<P>
In the GNU system, a user can specify the time zone by means of the
<CODE>TZ</CODE> environment variable.  For information about how to set
environment variables, see section <A HREF="library_22.html#SEC392" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_22.html#SEC392">Environment Variables</A>.  The functions for
accessing the time zone are declared in <TT>`time.h'</TT>.
<A NAME="IDX1390"></A>
<A NAME="IDX1389"></A>
<P>
The value of the <CODE>TZ</CODE> variable can be of one of three formats.  The
first format is used when there is no Daylight Saving Time (or summer
time) in the local time zone:
<P>
<PRE>
<VAR>std</VAR> <VAR>offset</VAR>
</PRE>
<P>
The <VAR>std</VAR> string specifies the name of the time zone.  It must be
three or more characters long and must not contain a leading colon or
embedded digits, commas, or plus or minus signs.  There is no space
character separating the time zone name from the <VAR>offset</VAR>, so these
restrictions are necessary to parse the specification correctly.
<P>
The <VAR>offset</VAR> specifies the time value one must add to the local time
to get a Coordinated Universal Time value.  It has syntax like
[<CODE>+</CODE>|<CODE>-</CODE>]<VAR>hh</VAR>[<CODE>:</CODE><VAR>mm</VAR>[<CODE>:</CODE><VAR>ss</VAR>]].  This
is positive if the local time zone is west of the Prime Meridian and
negative if it is east.  The hour must be between <CODE>0</CODE> and
<CODE>24</CODE>, and the minute and seconds between <CODE>0</CODE> and <CODE>59</CODE>.
<P>
For example, here is how we would specify Eastern Standard Time, but
without any daylight savings time alternative:
<P>
<PRE>
EST+5
</PRE>