use the simple word ``time'' for is to talk about the abstract concept.
A @dfn{calendar time} is a point in the time continuum, for example
-November 4, 1990 at 18:02.5 UTC. Sometimes this is called ``absolute
+November 4, 1990, at 18:02.5 UTC. Sometimes this is called ``absolute
time''.
@cindex calendar time
type, as with the following function to compute the elapsed time between
two calendar times. This function is declared in @file{time.h}.
-@comment time.h
-@comment ISO
@deftypefun double difftime (time_t @var{time1}, time_t @var{time0})
+@standards{ISO, time.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{difftime} function returns the number of seconds of elapsed
time between calendar time @var{time1} and calendar time @var{time0}, as
except that one has a resolution in microseconds, and the other, newer
one, is in nanoseconds.
-@comment sys/time.h
-@comment BSD
@deftp {Data Type} {struct timeval}
+@standards{BSD, sys/time.h}
@cindex timeval
The @code{struct timeval} structure represents an elapsed time. It is
declared in @file{sys/time.h} and has the following members:
@table @code
-@item long int tv_sec
+@item time_t tv_sec
This represents the number of whole seconds of elapsed time.
@item long int tv_usec
@end table
@end deftp
-@comment sys/time.h
-@comment POSIX.1
@deftp {Data Type} {struct timespec}
+@standards{POSIX.1, sys/time.h}
@cindex timespec
The @code{struct timespec} structure represents an elapsed time. It is
declared in @file{time.h} and has the following members:
@table @code
-@item long int tv_sec
+@item time_t tv_sec
This represents the number of whole seconds of elapsed time.
@item long int tv_nsec
to have a resolution somewhere between a hundredth and millionth of a
second.
-@comment time.h
-@comment ISO
@deftypevr Macro int CLOCKS_PER_SEC
+@standards{ISO, time.h}
The value of this macro is the number of clock ticks per second measured
by the @code{clock} function. POSIX requires that this value be one
million independent of the actual resolution.
@end deftypevr
-@comment time.h
-@comment ISO
@deftp {Data Type} clock_t
+@standards{ISO, time.h}
This is the type of the value returned by the @code{clock} function.
Values of type @code{clock_t} are numbers of clock ticks.
@end deftp
-@comment time.h
-@comment ISO
@deftypefun clock_t clock (void)
+@standards{ISO, time.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c On Hurd, this calls task_info twice and adds user and system time
@c from both basic and thread time info structs. On generic posix,
@cindex CPU time
@pindex sys/times.h
-@comment sys/times.h
-@comment POSIX.1
@deftp {Data Type} {struct tms}
+@standards{POSIX.1, sys/times.h}
The @code{tms} structure is used to return information about process
times. It contains at least the following members:
@item clock_t tms_cstime
This is similar to @code{tms_cutime}, but represents the total processor
-time system has used on behalf of all the terminated child processes
+time the system has used on behalf of all the terminated child processes
of the calling process.
@end table
@xref{Creating a Process}.
@end deftp
-@comment time.h
-@comment POSIX.1
@deftypevr Macro int CLK_TCK
+@standards{POSIX.1, time.h}
This is an obsolete name for the number of clock ticks per second. Use
@code{sysconf (_SC_CLK_TCK)} instead.
@end deftypevr
-@comment sys/times.h
-@comment POSIX.1
@deftypefun clock_t times (struct tms *@var{buffer})
+@standards{POSIX.1, sys/times.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c On HURD, this calls task_info twice, for basic and thread times info,
@c adding user and system times into tms, and then gettimeofday, to
@pindex time.h
@cindex epoch
-@comment time.h
-@comment ISO
@deftp {Data Type} time_t
+@standards{ISO, time.h}
This is the data type used to represent simple time. Sometimes, it also
represents an elapsed time. When interpreted as a calendar time value,
it represents the number of seconds elapsed since 00:00:00 on January 1,
simple calendar times, which is not always as easy to compute as just
subtracting. @xref{Elapsed Time}.
-@comment time.h
-@comment ISO
@deftypefun time_t time (time_t *@var{result})
+@standards{ISO, time.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{time} function returns the current calendar time as a value of
type @code{time_t}. If the argument @var{result} is not a null pointer,
@c The GNU C library implements stime() with a call to settimeofday() on
@c Linux.
-@comment time.h
-@comment SVID, XPG
@deftypefun int stime (const time_t *@var{newtime})
+@standards{SVID, time.h}
+@standards{XPG, time.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c On unix, this is implemented in terms of settimeofday.
@code{stime} sets the system clock, i.e., it tells the system that the
declared in @file{sys/time.h}.
@pindex sys/time.h
-@comment sys/time.h
-@comment BSD
@deftp {Data Type} {struct timezone}
+@standards{BSD, sys/time.h}
The @code{struct timezone} structure is used to hold minimal information
about the local time zone. It has the following members:
Instead, use the facilities described in @ref{Time Zone Functions}.
@end deftp
-@comment sys/time.h
-@comment BSD
@deftypefun int gettimeofday (struct timeval *@var{tp}, struct timezone *@var{tzp})
+@standards{BSD, sys/time.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c On most GNU/Linux systems this is a direct syscall, but the posix/
@c implementation (not used on GNU/Linux or GNU/Hurd) relies on time and
the elapsed time since the epoch in the @code{struct timeval} structure
indicated by @var{tp}. (@pxref{Elapsed Time} for a description of
@code{struct timeval}). Information about the time zone is returned in
-the structure pointed at @var{tzp}. If the @var{tzp} argument is a null
+the structure pointed to by @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
@end table
@end deftypefun
-@comment sys/time.h
-@comment BSD
@deftypefun int settimeofday (const struct timeval *@var{tp}, const struct timezone *@var{tzp})
+@standards{BSD, sys/time.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c On HURD, it calls host_set_time with a privileged port. On other
@c unix systems, it's a syscall.
@end deftypefun
@c On Linux, GNU libc implements adjtime() as a call to adjtimex().
-@comment sys/time.h
-@comment BSD
@deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta})
+@standards{BSD, sys/time.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c On hurd and mach, call host_adjust_time with a privileged port. On
@c Linux, it's implemented in terms of adjtimex. On other unixen, it's
Symbols for the following function are declared in @file{sys/timex.h}.
-@comment sys/timex.h
-@comment GNU
@deftypefun int adjtimex (struct timex *@var{timex})
+@standards{GNU, sys/timex.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c It's a syscall, only available on linux.
The symbols in this section are declared in the header file @file{time.h}.
-@comment time.h
-@comment ISO
@deftp {Data Type} {struct tm}
+@standards{ISO, time.h}
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.
@end deftp
-@comment time.h
-@comment ISO
@deftypefun {struct tm *} localtime (const time_t *@var{time})
+@standards{ISO, time.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
@c Calls tz_convert with a static buffer.
@c localtime @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
programs. The result is returned in a static buffer and this is used in
all threads. POSIX.1c introduced a variant of this function.
-@comment time.h
-@comment POSIX.1c
@deftypefun {struct tm *} localtime_r (const time_t *@var{time}, struct tm *@var{resultp})
+@standards{POSIX.1c, time.h}
@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
@c localtime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
@c tz_convert(use_localtime) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
@end deftypefun
-@comment time.h
-@comment ISO
@deftypefun {struct tm *} gmtime (const time_t *@var{time})
+@standards{ISO, time.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
@c gmtime @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
@c tz_convert dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
is placed in a static variable. POSIX.1c also provides a replacement for
@code{gmtime}.
-@comment time.h
-@comment POSIX.1c
@deftypefun {struct tm *} gmtime_r (const time_t *@var{time}, struct tm *@var{resultp})
+@standards{POSIX.1c, time.h}
@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
@c You'd think tz_convert could avoid some safety issues with
@c !use_localtime, but no such luck: tzset_internal will always bring
@end deftypefun
-@comment time.h
-@comment ISO
@deftypefun time_t mktime (struct tm *@var{brokentime})
+@standards{ISO, time.h}
@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
@c mktime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
@c passes a static localtime_offset to mktime_internal; it is read
members. @xref{Time Zone Functions}.
@end deftypefun
-@comment time.h
-@comment ???
@deftypefun time_t timelocal (struct tm *@var{brokentime})
+@standards{???, time.h}
@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
@c Alias to mktime.
@end deftypefun
-@comment time.h
-@comment ???
@deftypefun time_t timegm (struct tm *@var{brokentime})
+@standards{???, time.h}
@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
@c timegm @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
@c gmtime_offset triggers the same caveats as localtime_offset in mktime.
@end table
@end deftp
-@comment sys/timex.h
-@comment GNU
@deftypefun int ntp_gettime (struct ntptimeval *@var{tptr})
+@standards{GNU, sys/timex.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c Wrapper for adjtimex.
The @code{ntp_gettime} function sets the structure pointed to by
@var{tptr} to current values. The elements of the structure afterwards
contain the values the timer implementation in the kernel assumes. They
-might or might not be correct. If they are not a @code{ntp_adjtime}
+might or might not be correct. If they are not, an @code{ntp_adjtime}
call is necessary.
The return value is @code{0} on success and other values on failure. The
following @code{errno} error conditions are defined for this function:
-@table @code
+@vtable @code
@item TIME_ERROR
The precision clock model is not properly set up at the moment, thus the
clock must be considered unsynchronized, and the values should be
treated with care.
-@end table
+@end vtable
@end deftypefun
@tindex struct timex
@end table
@end deftp
-@comment sys/timex.h
-@comment GNU
@deftypefun int ntp_adjtime (struct timex *@var{tptr})
+@standards{GNU, sys/timex.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c Alias to adjtimex syscall.
The @code{ntp_adjtime} function sets the structure specified by
strings. These functions are declared in the header file @file{time.h}.
@pindex time.h
-@comment time.h
-@comment ISO
@deftypefun {char *} asctime (const struct tm *@var{brokentime})
+@standards{ISO, time.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:asctime} @mtslocale{}}@asunsafe{}@acsafe{}}
@c asctime @mtasurace:asctime @mtslocale
@c Uses a static buffer.
string.)
@end deftypefun
-@comment time.h
-@comment POSIX.1c
@deftypefun {char *} asctime_r (const struct tm *@var{brokentime}, char *@var{buffer})
+@standards{POSIX.1c, time.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
@c asctime_r @mtslocale
@c asctime_internal dup @mtslocale
If no error occurred the function returns a pointer to the string the
result was written into, i.e., it returns @var{buffer}. Otherwise
-return @code{NULL}.
+it returns @code{NULL}.
@end deftypefun
-@comment time.h
-@comment ISO
@deftypefun {char *} ctime (const time_t *@var{time})
+@standards{ISO, time.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtasurace{:asctime} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
@c ctime @mtasurace:tmbuf @mtasurace:asctime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
@c localtime dup @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
@code{tzset} were called. @xref{Time Zone Functions}.
@end deftypefun
-@comment time.h
-@comment POSIX.1c
@deftypefun {char *} ctime_r (const time_t *@var{time}, char *@var{buffer})
+@standards{POSIX.1c, time.h}
@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
@c ctime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
@c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
If no error occurred the function returns a pointer to the string the
result was written into, i.e., it returns @var{buffer}. Otherwise
-return @code{NULL}.
+it returns @code{NULL}.
@end deftypefun
-@comment time.h
-@comment ISO
@deftypefun size_t strftime (char *@var{s}, size_t @var{size}, const char *@var{template}, const struct tm *@var{brokentime})
+@standards{ISO, time.h}
@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
@c strftime @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
@c strftime_l @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
Following the flag an optional specification of the width is possible.
This is specified in decimal notation. If the natural size of the
-output is of the field has less than the specified number of characters,
+output of the field has less than the specified number of characters,
the result is written right adjusted and space padded to the given
size.
@table @code
@item E
-Use the locale's alternate representation for date and time. This
+Use the locale's alternative representation for date and time. This
modifier applies to the @code{%c}, @code{%C}, @code{%x}, @code{%X},
@code{%y} and @code{%Y} format specifiers. In a Japanese locale, for
example, @code{%Ex} might yield a date format based on the Japanese
Emperors' reigns.
@item O
-Use the locale's alternate numeric symbols for numbers. This modifier
-applies only to numeric format specifiers.
+With all format specifiers that produce numbers: use the locale's
+alternative numeric symbols.
+
+With @code{%B}, @code{%b}, and @code{%h}: use the grammatical form for
+month names that is appropriate when the month is named by itself,
+rather than the form that is appropriate when the month is used as
+part of a complete date. This is a GNU extension.
@end table
-If the format supports the modifier but no alternate representation
+If the format supports the modifier but no alternative representation
is available, it is ignored.
The conversion specifier ends with a format specifier taken from the
The full weekday name according to the current locale.
@item %b
-The abbreviated month name according to the current locale.
+The abbreviated month name according to the current locale, in the
+grammatical form used when the month is part of a complete date.
+As a GNU extension, the @code{O} modifier can be used (@code{%Ob})
+to get the grammatical form used when the month is named by itself.
@item %B
-The full month name according to the current locale.
+The full month name according to the current locale, in the
+grammatical form used when the month is part of a complete date.
+As a GNU extension, the @code{O} modifier can be used (@code{%OB})
+to get the grammatical form used when the month is named by itself.
-Using @code{%B} together with @code{%d} produces grammatically
-incorrect results for some locales.
+Note that not all languages need two different forms of the month
+names, so the text produced by @code{%B} and @code{%OB}, and by
+@code{%b} and @code{%Ob}, may or may not be the same, depending on
+the locale.
@item %c
The preferred calendar time representation for the current locale.
The century of the year. This is equivalent to the greatest integer not
greater than the year divided by 100.
+If the @code{E} modifier is specified (@code{%EC}), instead produces
+the name of the period for the year (e.g.@: an era name) in the
+locale's alternative calendar.
+
This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
@item %d
This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
@item %e
-The day of the month like with @code{%d}, but padded with blank (range
+The day of the month like with @code{%d}, but padded with spaces (range
@code{ 1} through @code{31}).
This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
@item %k
The hour as a decimal number, using a 24-hour clock like @code{%H}, but
-padded with blank (range @code{ 0} through @code{23}).
+padded with spaces (range @code{ 0} through @code{23}).
This format is a GNU extension.
@item %l
The hour as a decimal number, using a 12-hour clock like @code{%I}, but
-padded with blank (range @code{ 1} through @code{12}).
+padded with spaces (range @code{ 1} through @code{12}).
This format is a GNU extension.
The year without a century as a decimal number (range @code{00} through
@code{99}). This is equivalent to the year modulo 100.
+If the @code{E} modifier is specified (@code{%Ey}), instead produces
+the year number according to a locale-specific alternative calendar.
+Unlike @code{%y}, the number is @emph{not} reduced modulo 100.
+However, by default it is zero-padded to a minimum of two digits (this
+can be overridden by an explicit field width or by the @code{_} and
+@code{-} flags).
+
@item %Y
The year as a decimal number, using the Gregorian calendar. Years
before the year @code{1} are numbered @code{0}, @code{-1}, and so on.
+If the @code{E} modifier is specified (@code{%EY}), instead produces a
+complete representation of the year according to the locale's
+alternative calendar. Generally this will be some combination of the
+information produced by @code{%EC} and @code{%Ey}. As a GNU
+extension, the formatting flags @code{_} or @code{-} may be used with
+this conversion specifier; they affect how the year number is printed.
+
@item %z
@w{RFC 822}/@w{ISO 8601:1988} style numeric time zone (e.g.,
@code{-0600} or @code{+0100}), or nothing if no time zone is
For an example of @code{strftime}, see @ref{Time Functions Example}.
@end deftypefun
-@comment time.h
-@comment ISO/Amend1
@deftypefun size_t wcsftime (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, const struct tm *@var{brokentime})
+@standards{ISO/Amend1, time.h}
@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
@c wcsftime @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
@c wcsftime_l @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
strings. The buffer where the result is stored, pointed to by @var{s},
must be an array of wide characters. The parameter @var{size} which
specifies the size of the output buffer gives the number of wide
-character, not the number of bytes.
+characters, not the number of bytes.
Also the format string @var{template} is a wide character string. Since
all characters needed to specify the format string are in the basic
implementation are heavily influenced by the @code{getdate} function,
which is defined and implemented in terms of calls to @code{strptime}.
-@comment time.h
-@comment XPG4
@deftypefun {char *} strptime (const char *@var{s}, const char *@var{fmt}, struct tm *@var{tp})
+@standards{XPG4, time.h}
@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
@c strptime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
@c strptime_internal @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
@item %b
@itemx %B
@itemx %h
-The month name according to the current locale, in abbreviated form or
-the full name.
+A month name according to the current locale. All three specifiers
+will recognize both abbreviated and full month names. If the
+locale provides two different grammatical forms of month names,
+all three specifiers will recognize both forms.
+
+As a GNU extension, the @code{O} modifier can be used with these
+specifiers; it has no effect, as both grammatical forms of month
+names are recognized.
@item %c
The date and time representation for the current locale.
@item
Before calling the @code{strptime} function for a new input string, you
should prepare the @var{tm} structure you pass. Normally this will mean
-initializing all values are to zero. Alternatively, you can set all
+initializing all values to zero. Alternatively, you can set all
fields to values like @code{INT_MAX}, allowing you to determine which
elements were set by the function call. Zero does not work here since
it is a valid value for many of the fields.
structure in-between, you can construct a complete broken-down time.
@end itemize
-The following example shows a function which parses a string which is
+The following example shows a function which parses a string which
contains the date information in either US style or @w{ISO 8601} form:
@smallexample
a static variable, and uses a global variable and global state (an
environment variable).
-@comment time.h
-@comment Unix98
@defvar getdate_err
+@standards{Unix98, time.h}
This variable of type @code{int} contains the error code of the last
unsuccessful call to @code{getdate}. Defined values are:
@end table
@end defvar
-@comment time.h
-@comment Unix98
@deftypefun {struct tm *} getdate (const char *@var{string})
+@standards{Unix98, time.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:getdate} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
@c getdate @mtasurace:getdate @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
@c getdate_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
@item
If only the weekday is specified the selected day depends on the current
-date. If the current weekday is greater or equal to the @code{tm_wday}
+date. If the current weekday is greater than or equal to the @code{tm_wday}
value the current week's day is chosen, otherwise the day next week is chosen.
@item
As you can see, the template list can contain very specific strings like
@code{run job at %I %p,%B %dnd}. Using the above list of templates and
-assuming the current time is Mon Sep 22 12:19:47 EDT 1986 we can obtain the
+assuming the current time is Mon Sep 22 12:19:47 EDT 1986, we can obtain the
following results for the given input.
@multitable {xxxxxxxxxxxx} {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
(such as a binary file) the program will crash.
@end deftypefun
-@comment time.h
-@comment GNU
@deftypefun int getdate_r (const char *@var{string}, struct tm *@var{tp})
+@standards{GNU, time.h}
@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
@c getdate_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
@c getenv dup @mtsenv
about them.
@cindex time zone database
-@pindex /share/lib/zoneinfo
+@pindex /usr/share/zoneinfo
@pindex zoneinfo
If @var{characters} begins with a slash, it is an absolute file name;
otherwise the library looks for the file
-@w{@file{/share/lib/zoneinfo/@var{characters}}}. The @file{zoneinfo}
+@w{@file{/usr/share/zoneinfo/@var{characters}}}. The @file{zoneinfo}
directory contains data files describing local time zones in many
different parts of the world. The names represent major cities, with
subdirectories for geographical areas; for example,
@file{America/New_York}, @file{Europe/London}, @file{Asia/Hong_Kong}.
These data files are installed by the system administrator, who also
sets @file{/etc/localtime} to point to the data file for the local time
-zone. @Theglibc{} comes with a large database of time zone
+zone. The files typically come from the @url{http://www.iana.org/time-zones,
+Time Zone Database} of time zone and daylight saving time
information for most regions of the world, which is maintained by a
community of volunteers and put in the public domain.
@node Time Zone Functions
@subsection Functions and Variables for Time Zones
-@comment time.h
-@comment POSIX.1
@deftypevar {char *} tzname [2]
+@standards{POSIX.1, time.h}
The array @code{tzname} contains two strings, which are the standard
names of the pair of time zones (standard and Daylight
Saving) that the user has selected. @code{tzname[0]} is the name of
@end deftypevar
-@comment time.h
-@comment POSIX.1
@deftypefun void tzset (void)
+@standards{POSIX.1, time.h}
@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
@c tzset @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
@c libc_lock_lock dup @asulock @aculock
Unix. Like @code{tzname}, these variables are set by calling
@code{tzset} or the other time conversion functions.
-@comment time.h
-@comment SVID
@deftypevar {long int} timezone
+@standards{SVID, time.h}
This contains the difference between UTC and the latest local standard
time, in seconds west of UTC. For example, in the U.S. Eastern time
zone, the value is @code{5*60*60}. Unlike the @code{tm_gmtoff} member
it is not the latest one.
@end deftypevar
-@comment time.h
-@comment SVID
@deftypevar int daylight
+@standards{SVID, time.h}
This variable has a nonzero value if Daylight Saving Time rules apply.
A nonzero value does not necessarily mean that Daylight Saving Time is
now in effect; it means only that Daylight Saving Time is sometimes in
might block otherwise indefinitely it is important to @emph{not} set the
@code{SA_RESTART} flag when registering the signal handler using
@code{sigaction}. When not using @code{sigaction} things get even
-uglier: the @code{signal} function has to fixed semantics with respect
+uglier: the @code{signal} function has fixed semantics with respect
to restarts. The BSD semantics for this function is to set the flag.
Therefore, if @code{sigaction} for whatever reason cannot be used, it is
necessary to use @code{sysv_signal} and not @code{signal}.
@pindex unistd.h
@pindex sys/time.h
-@comment sys/time.h
-@comment BSD
@deftp {Data Type} {struct itimerval}
+@standards{BSD, sys/time.h}
This structure is used to specify when a timer should expire. It contains
the following members:
@table @code
The @code{struct timeval} data type is described in @ref{Elapsed Time}.
@end deftp
-@comment sys/time.h
-@comment BSD
@deftypefun int setitimer (int @var{which}, const struct itimerval *@var{new}, struct itimerval *@var{old})
+@standards{BSD, sys/time.h}
@safety{@prelim{}@mtsafe{@mtstimer{}}@assafe{}@acsafe{}}
@c This function is marked with @mtstimer because the same set of timers
@c is shared by all threads of a process, so calling it in one thread
@end table
@end deftypefun
-@comment sys/time.h
-@comment BSD
@deftypefun int getitimer (int @var{which}, struct itimerval *@var{old})
+@standards{BSD, sys/time.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{getitimer} function stores information about the timer specified
by @var{which} in the structure pointed at by @var{old}.
The return value and error conditions are the same as for @code{setitimer}.
@end deftypefun
-@comment sys/time.h
-@comment BSD
@vtable @code
@item ITIMER_REAL
+@standards{BSD, sys/time.h}
This constant can be used as the @var{which} argument to the
@code{setitimer} and @code{getitimer} functions to specify the real-time
timer.
-@comment sys/time.h
-@comment BSD
@item ITIMER_VIRTUAL
+@standards{BSD, sys/time.h}
This constant can be used as the @var{which} argument to the
@code{setitimer} and @code{getitimer} functions to specify the virtual
timer.
-@comment sys/time.h
-@comment BSD
@item ITIMER_PROF
+@standards{BSD, sys/time.h}
This constant can be used as the @var{which} argument to the
@code{setitimer} and @code{getitimer} functions to specify the profiling
timer.
@end vtable
-@comment unistd.h
-@comment POSIX.1
@deftypefun {unsigned int} alarm (unsigned int @var{seconds})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{@mtstimer{}}@assafe{}@acsafe{}}
@c Wrapper for setitimer.
The @code{alarm} function sets the real-time timer to expire in
zero.
The return value indicates how many seconds remain before the previous
-alarm would have been sent. If there is no previous alarm, @code{alarm}
+alarm would have been sent. If there was no previous alarm, @code{alarm}
returns zero.
@end deftypefun
any descriptors to wait for.
@c !!! select can get EINTR; using SA_RESTART makes sleep win too.
-@comment unistd.h
-@comment POSIX.1
@deftypefun {unsigned int} sleep (unsigned int @var{seconds})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtunsafe{@mtascusig{:SIGCHLD/linux}}@asunsafe{}@acunsafe{}}
@c On Mach, it uses ports and calls time. On generic posix, it calls
@c nanosleep. On Linux, it temporarily blocks SIGCHLD, which is MT- and
@c AS-Unsafe, and in a way that makes it AC-Unsafe (C-unsafe, even!).
-The @code{sleep} function waits for @var{seconds} or until a signal
+The @code{sleep} function waits for @var{seconds} seconds or until a signal
is delivered, whichever happens first.
-If @code{sleep} function returns because the requested interval is over,
+If @code{sleep} returns because the requested interval is over,
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 interval.
the same program, because @code{sleep} does not work by means of
@code{SIGALRM}.
-@comment time.h
-@comment POSIX.1
@deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining})
+@standards{POSIX.1, time.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c On Linux, it's a syscall. On Mach, it calls gettimeofday and uses
@c ports.
@code{struct timespec} is described in @xref{Elapsed Time}.
If the function returns because the interval is over the return value is
-zero. If the function returns @math{-1} the global variable @var{errno}
+zero. If the function returns @math{-1} the global variable @code{errno}
is set to the following values:
@table @code