time.texi

一个C源代码分析器

following @code{errno} error conditions are defined for this function:

@table @code
@item EPERM
This process cannot set the time because it is not privileged.

@item ENOSYS
The operating system does not support setting time zone information, and
@var{tzp} is not a null pointer.
@end table
@end deftypefun

@comment sys/time.h
@comment BSD
@deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta})
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.

The @var{delta} 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.

If the @var{olddelta} argument is not a null pointer, the @code{adjtime}
function returns information about any previous time adjustment that
has not yet completed.

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} on success and @code{-1} on failure.  The
following @code{errno} error condition is defined for this function:

@table @code
@item EPERM
You do not have privilege to set the time.
@end table
@end deftypefun

@strong{Portability Note:}  The @code{gettimeofday}, @code{settimeofday},
and @code{adjtime} functions are derived from BSD.  


@node Broken-down Time
@subsection Broken-down Time
@cindex broken-down time
@cindex calendar time and broken-down time

Calendar 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} 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.

A broken-down time value is always relative to a choice of local time
zone, and it also indicates which time zone was used.

The symbols in this section are declared in the header file @file{time.h}.

@comment time.h
@comment ANSI
@deftp {Data Type} {struct tm}
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:

@table @code
@item int tm_sec
This is the number of seconds after the minute, normally in the range
@code{0} to @code{59}.  (The actual upper limit is @code{61}, to allow
for ``leap seconds''.)
@cindex leap second

@item int tm_min
This is the number of minutes after the hour, in the range @code{0} to
@code{59}.

@item int tm_hour
This is the number of hours past midnight, in the range @code{0} to
@code{23}.

@item int tm_mday
This is the day of the month, in the range @code{1} to @code{31}.

@item int tm_mon
This is the number of months since January, in the range @code{0} to
@code{11}.

@item int tm_year
This is the number of years since @code{1900}.

@item int tm_wday
This is the number of days since Sunday, in the range @code{0} to @code{6}.

@item int tm_yday
This is the number of days since January 1, in the range @code{0} to
@code{365}.

@item int tm_isdst
@cindex Daylight Saving Time
@cindex summer time
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.

@item long int tm_gmtoff
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} (@pxref{Time Zone Functions}).  You can
also think of this as the ``number of seconds west'' of GMT.  The
@code{tm_gmtoff} field is a GNU library extension.

@item const char *tm_zone
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.
@end table
@end deftp

@comment time.h
@comment ANSI
@deftypefun {struct tm *} localtime (const time_t *@var{time})
The @code{localtime} function converts the calendar time pointed to by
@var{time} to broken-down time representation, expressed relative to the
user's specified time zone.

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.)

Calling @code{localtime} has one other effect: it sets the variable
@code{tzname} with information about the current time zone.  @xref{Time
Zone Functions}.
@end deftypefun

@comment time.h
@comment ANSI
@deftypefun {struct tm *} gmtime (const time_t *@var{time})
This function is similar to @code{localtime}, 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.

Recall that calendar times are @emph{always} expressed in coordinated
universal time.
@end deftypefun

@comment time.h
@comment ANSI
@deftypefun time_t mktime (struct tm *@var{brokentime})
The @code{mktime} 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.

The @code{mktime} function ignores the specified contents of the
@code{tm_wday} and @code{tm_yday} 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} does is adjust the components of the @var{brokentime}
structure (including the @code{tm_wday} and @code{tm_yday}).

If the specified broken-down time cannot be represented as a calendar time,
@code{mktime} returns a value of @code{(time_t)(-1)} and does not modify
the contents of @var{brokentime}.

Calling @code{mktime} also sets the variable @code{tzname} with
information about the current time zone.  @xref{Time Zone Functions}.
@end deftypefun

@node Formatting Date and Time
@subsection Formatting Date and Time

The functions described in this section format time values as strings.
These functions are declared in the header file @file{time.h}.
@pindex time.h

@comment time.h
@comment ANSI
@deftypefun {char *} asctime (const struct tm *@var{brokentime})
The @code{asctime} function converts the broken-down time value that
@var{brokentime} points to into a string in a standard format:

@smallexample
"Tue May 21 13:46:22 1991\n"
@end smallexample

The abbreviations for the days of week are: @samp{Sun}, @samp{Mon},
@samp{Tue}, @samp{Wed}, @samp{Thu}, @samp{Fri}, and @samp{Sat}.

The abbreviations for the months are: @samp{Jan}, @samp{Feb},
@samp{Mar}, @samp{Apr}, @samp{May}, @samp{Jun}, @samp{Jul}, @samp{Aug},
@samp{Sep}, @samp{Oct}, @samp{Nov}, and @samp{Dec}.

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.)
@end deftypefun

@comment time.h
@comment ANSI
@deftypefun {char *} ctime (const time_t *@var{time})
The @code{ctime} function is similar to @code{asctime}, except that the
time value is specified as a @code{time_t} calendar time value rather
than in broken-down local time format.  It is equivalent to

@smallexample
asctime (localtime (@var{time}))
@end smallexample

@code{ctime} sets the variable @code{tzname}, because @code{localtime}
does so.  @xref{Time Zone Functions}.
@end deftypefun

@comment time.h
@comment ANSI
@deftypefun size_t strftime (char *@var{s}, size_t @var{size}, const char *@var{template}, const struct tm *@var{brokentime})
This function is similar to the @code{sprintf} function (@pxref{Formatted
Input}), but the conversion specifications that can appear in the format
template @var{template} are specialized for printing components of the date
and time @var{brokentime} according to the locale currently specified for
time conversion (@pxref{Locales}).

Ordinary characters appearing in the @var{template} are copied to the
output string @var{s}; this can include multibyte character sequences.
Conversion specifiers are introduced by a @samp{%} character, and are
replaced in the output string as follows:

@table @code
@item %a
The abbreviated weekday name according to the current locale.

@item %A
The full weekday name according to the current locale.

@item %b
The abbreviated month name according to the current locale.

@item %B
The full month name according to the current locale.

@item %c
The preferred date and time representation for the current locale.

@item %d
The day of the month as a decimal number (range @code{01} to @code{31}).

@item %H
The hour as a decimal number, using a 24-hour clock (range @code{00} to
@code{23}).

@item %I
The hour as a decimal number, using a 12-hour clock (range @code{01} to
@code{12}).

@item %j
The day of the year as a decimal number (range @code{001} to @code{366}).

@item %m
The month as a decimal number (range @code{01} to @code{12}).

@item %M
The minute as a decimal number.

@item %p
Either @samp{am} or @samp{pm}, according to the given time value; or the
corresponding strings for the current locale.

@item %S
The second as a decimal number.

@item %U
The week number of the current year as a decimal number, starting with
the first Sunday as the first day of the first week.

@item %W
The week number of the current year as a decimal number, starting with
the first Monday as the first day of the first week.

@item %w
The day of the week as a decimal number, Sunday being @code{0}.

@item %x
The preferred date representation for the current locale, but without the
time.

@item %X
The preferred time representation for the current locale, but with no date.

@item %y
The year as a decimal number, but without a century (range @code{00} to
@code{99}).

@item %Y
The year as a decimal number, including the century.

@item %Z
The time zone or name or abbreviation (empty if the time zone can't be
determined).

@item %%
A literal @samp{%} character.
@end table

The @var{size} parameter can be used to specify the maximum number of
characters to be stored in the array @var{s}, including the terminating
null character.  If the formatted time requires more than @var{size}
characters, the excess characters are discarded.  The return value from
@code{strftime} is the number of characters placed in the array @var{s},
not including the terminating null character.  If the value equals
@var{size}, it means that the array @var{s} was too small; you should
repeat the call, providing a bigger array.

If @var{s} is a null pointer, @code{strftime} does not actually write
anything, but instead returns the number of characters it would have written.

For an example of @code{strftime}, see @ref{Time Functions Example}.
@end deftypefun

@node TZ Variable
@subsection Specifying the Time Zone with @code{TZ}

In POSIX systems, a user can specify the time zone by means of the
@code{TZ} environment variable.  For information about how to set
environment variables, see @ref{Environment Variables}.  The functions
for accessing the time zone are declared in @file{time.h}.
@pindex time.h
@cindex time zone

You should not normally need to set @code{TZ}.  If the system is
configured properly, the default timezone will be correct.  You might
set @code{TZ} if you are using a computer over the network from a
different timezone, and would like times reported to you in the timezone
that local for you, rather than what is local for the computer.

In POSIX.1 systems the value of the @code{TZ} variable can be of one of
three formats.  With the GNU C library, the most common format is the
last one, which can specify a selection from a large database of time
zone information for many regions of the world.  The first two formats
are used to describe the time zone information directly, which is both
more cumbersome and less precise.  But the POSIX.1 standard only
specifies the details of the first two formats, so it is good to be
familiar with them in case you come across a POSIX.1 system that doesn't
support a time zone information database.

The first format is used when there is no Daylight Saving Time (or
summer time) in the local time zone:

@smallexample
@r{@var{std} @var{offset}}
@end smallexample

The @var{std} 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}, so these
restrictions are necessary to parse the specification correctly.

The @var{offset} specifies the time value one must add to the local time
to get a Coordinated Universal Time value.  It has syntax like
[@code{+}|@code{-}]@var{hh}[@code{:}@var{mm}[@code{:}@var{ss}]].  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} and
@code{24}, and the minute and seconds between @code{0} and @code{59}.

For example, here is how we would specify Eastern Standard Time, but
without any daylight savings time alternative:

@smallexample
EST+5
@end smallexample

The second format is used when there is Daylight Saving Time:

@smallexample
@r{@var{std} @var{offset} @var{dst} [@var{offset}]@code{,}@var{start}[@code{/}@var{time}]@code{,}@var{end}[@code{/}@var{time}]}
@end smallexample

The initial @var{std} and @var{offset} specify the standard time zone, as
described above.  The @var{dst} string and @var{offset} specify the name
and offset for the corresponding daylight savings time time zone; if the
@var{offset} is omitted, it defaults to one hour ahead of standard time.

The remainder of the specification describes when daylight savings time is
in effect.  The @var{start} field is when daylight savings time goes into
effect and the @var{end} field is when the change is made back to standard
time.  The following formats are recognized for these fields:

@table @code
@item J@var{n}