This is a thorough revision of all the material relating to the
functions time, stime, gettimeofday, settimeofday, clock_gettime,
clock_getres, clock_settime, and difftime, spilling over into the
discussion of time-related data types (which now get their own
section) and touching the adjtime family as well (which deserves its
own thorough revision, but I'd have to do a bunch of research first).
Substantive changes are:
* Document clock_gettime, clock_getres, and clock_settime. (Only
CLOCK_REALTIME and CLOCK_MONOTONIC are documented; the others are
either a bit too Linux-specific, or have more to do with measuring
CPU/processor time. That section _also_ deserves its own thorough
revision but again I'd have to do a bunch of research first.)
* Present gettimeofday, settimeofday, and struct timeval as obsolete
relative to clock_*.
* Remove the documentation of struct timezone. Matching POSIX,
say that the type of the second argument to gettimeofday and
settimeofday is [const] void *.
* Clarify ISO C and POSIX's requirements on time_t. Clarify the
circumstances under which difftime is equivalent to simple
subtraction.
* Consolidate documentation of most of the time-related data types
into a new section "Time Types," right after "Time Basics." (The
exceptions are struct tm, which stays in "Broken-down Time," and
struct times, which stays in "Processor And CPU Time."
* The "Elapsed Time" section is now called "Calculating Elapsed Time"
and includes only difftime and the discussion of how to compute
timeval differences by hand.
* Fold the "Simple Calendar Time," "High Resolution Calendar," and
"High Accuracy Clock" sections together into two new sections titled
"Getting the Time" and "Setting and Adjusting the Time."
C2X standardizes strftime %Ob and %OB support. This patch updates the
glibc manual to say these are C2X features, while noting that the
details of what is the alternative form of a month name are not
specified in C2X.
Note: C2X seems unclear to me about whether %h being equivalent to %b
means %Oh is thereby allowed and equivalent to %Ob; I've asked WG14.
Tested with "make info" and "make pdf".
* manual/time.texi (strftime): Document %Ob and %OB as C2X
features.
The full representation of the alternative calendar year (%EY)
typically includes an internal use of "%Ey". As a GNU extension,
apply any flags on "%EY" (e.g. "%_EY", "%-EY") to the internal "%Ey",
allowing users of "%EY" to control how the year is padded.
Reviewed-by: Rafal Luzynski <digitalfreak@lingonborough.com>
Reviewed-by: Zack Weinberg <zackw@panix.com>
ChangeLog:
[BZ #24096]
* manual/time.texi (strftime): Document "%EC" and "%EY".
* time/Makefile (tests): Add tst-strftime2.
(LOCALES): Add ja_JP.UTF-8, lo_LA.UTF-8, and th_TH.UTF-8.
* time/strftime_l.c (__strftime_internal): Add argument yr_spec to
override padding for "%Ey".
If an optional flag ('_' or '-') is specified to "%EY", interpret the
"%Ey" in the subformat as if decorated with that flag.
* time/tst-strftime2.c: New file.
In Japanese locales, strftime's alternative year format (%Ey) produces
a year numbered within a time period called an _era_. A new era
typically begins when a new emperor is enthroned. The result of "%Ey"
is therefore usually a one- or two-digit number.
Many programs that display Japanese era dates assume that the era year
is two digits wide. To improve how these programs display dates
during the first nine years of a new era, change "%Ey" to pad one-
digit numbers on the left with a zero. This change applies to all
locales. It is expected to be harmless for other locales that use the
alternative year format (e.g. lo_LA and th_TH, in which "%Ey" produces
the year of the Buddhist calendar) as those calendars' year numbers
are already more than two digits wide, and this is not expected to
change.
This change needs to be in place before 2019-05-01 CE, as a new era is
scheduled to begin on that date.
Reviewed-by: Zack Weinberg <zackw@panix.com>
Reviewed-by: Rafal Luzynski <digitalfreak@lingonborough.com>
ChangeLog:
[BZ #23758]
* manual/time.texi (strftime): Document "%Ey".
* time/strftime_l.c (__strftime_internal): Set the default width
padding with zero of "%Ey" to 2.
@var is intended for placeholders (such as function parameters).
Actual variables need to use @code because @var causes upper-case
output, resulting in a different C identifier.
"%OB" is considered a conversion specifier ("B" is the format
specifier), and the list of format specifiers for months in the
description of the optional "O" modifier was incomplete. A
cross-reference from the ALTMON_* constants to the strftime section
is also provided. Lastly, some grammatical fixes (commas) are made
and paragraphs refactored (rewrapped).
* manual/locale.texi (ALTMON_1, ALTMON_2, ALTMON_3, ALTMON_4,
ALTMON_5, ALTMON_6, ALTMON_7, ALTMON_8, ALTMON_9, ALTMON_10,
ALTMON_11, ALTMON_12): Improve documentation.
* manual/time.texi (strftime): Likewise.
[BZ #10871]
* manual/locale.texi: Document ALTMON_1..12 constants for
nl_langinfo. Specify when to use ALTMON instead of MON.
* manual/time.texi (strftime, strptime): Document GNU extension
permitting O modifier with %B and %b. Specify when to use
%OB instead of %B.
Reviewed-by: Carlos O'Donell <carlos@redhat.com>
The Summary is now generated from @standards, and syntax-checking is
performed. If invalid @standards syntax is detected, summary.pl will
fail, reporting all errors. Failure and error reporting is disabled
for now, however, since much of the manual is still incomplete
wrt. header and standards annotations.
Note that the sorting order of the Summary has changed; summary.pl
respects the locale, like summary.awk did, but the use of LC_ALL=C is
introduced in the Makefile. Other notable deviations are improved
detection of the annotated elements' names, which are used for
sorting, and improved detection of the @node used to reference into
the manual. The most noticeable difference in the rendered Summary is
that entries may now contain multiple lines, one for each header and
standard combination.
summary.pl accepts a `--help' option, which details the expected
syntax of @standards. If errors are reported, the user is directed to
this feature for further information.
* manual/Makefile: Generate summary.texi with summary.pl.
Force use of the C locale. Update Perl dependency comment.
* manual/header.texi: Update reference to summary.awk.
* manual/macros.texi: Refer authors to `summary.pl --help'.
* manual/summary.awk: Remove file.
* manual/summary.pl: New file. Generate summary.texi, and
check for @standards-related syntax errors.
* manual/argp.texi: Convert header and standards @comments to
@standards.
* manual/arith.texi: Likewise.
* manual/charset.texi: Likewise.
* manual/conf.texi: Likewise.
* manual/creature.texi: Likewise.
* manual/crypt.texi: Likewise.
* manual/ctype.texi: Likewise.
* manual/debug.texi: Likewise.
* manual/errno.texi: Likewise.
* manual/filesys.texi: Likewise.
* manual/getopt.texi: Likewise.
* manual/job.texi: Likewise.
* manual/lang.texi: Likewise.
* manual/llio.texi: Likewise.
* manual/locale.texi: Likewise.
* manual/math.texi: Likewise.
* manual/memory.texi: Likewise.
* manual/message.texi: Likewise.
* manual/pattern.texi: Likewise.
* manual/pipe.texi: Likewise.
* manual/process.texi: Likewise.
* manual/resource.texi: Likewise.
* manual/search.texi: Likewise.
* manual/setjmp.texi: Likewise.
* manual/signal.texi: Likewise.
* manual/socket.texi: Likewise.
* manual/startup.texi: Likewise.
* manual/stdio.texi: Likewise.
* manual/string.texi: Likewise.
* manual/sysinfo.texi: Likewise.
* manual/syslog.texi: Likewise.
* manual/terminal.texi: Likewise.
* manual/threads.texi: Likewise.
* manual/time.texi: Likewise.
* manual/users.texi: Likewise.
This commit handles exceptional cases of invalid syntax for the
@standards conversion script.
* manual/crypt.texi: Move a comment out of an @*x list.
* manual/filesys.texi: Refactor some comments, one of which
looks like a standard. Fix incorrectly separated standards.
* manual/locale.texi: Invert an annotation.
* manual/resource.texi: Fix incorrectly separated standards.
* manual/time.texi: Refactor a @vtable that obscures an
annotation.
* manual/users.texi: Refactor multiple headers to occupy a
single @comment.
Texinfo @vindex commands add entries to the Variable and Constant
Macro Index. Similarly, @items in @vtables are automatically indexed.
A number of @tables exist where all @items are @vindexed or all @items
are variables, but not indexed, suggesting an optimization by
converting such @tables to @vtables and dropping the @vindex.
Using a @vtable provides a context for processing @items whereby it
can be known the @items should have header and standards annotations.
This commit converts @tables of such @items to @vtables in order to
establish a framework for automated processing.
A pleasant consequence of these changes is that @items previously
lacking a @vindex are present in the Variable and Constant Macro Index
now. @vindex entries previously detected by summary.awk will still be
detected as @items with appropriate annotations.
The @vtable of the NSS databases is converted to a @table because 1)
those @items are not variables (and will no longer appear in the
Variable and Constant Macro Index) and 2) they do not need header and
standards annotations, so the incorrect context is fixed.
* manual/nss.texi: Change incorrect @vtable to @table.
* manual/arith.texi: Convert @tables of variables to @vtables
and remove unnecessary indexing.
* manual/filesys.texi: Likewise.
* manual/llio.texi: Likewise.
* manual/memory.texi: Likewise.
* manual/process.texi: Likewise.
* manual/resource.texi: Likewise.
* manual/search.texi: Likewise.
* manual/signal.texi: Likewise.
* manual/socket.texi: Likewise.
* manual/stdio.texi: Likewise.
* manual/sysinfo.texi: Likewise.
* manual/syslog.texi: Likewise.
* manual/terminal.texi: Likewise.
* manual/time.texi: Likewise.
* manual/users.texi: Likewise.
The tv_sec is of type time_t in both struct timeval and struct timespec.
This matches the implementation and also the relevant standard (checked
C11 for timespec and opengroup for timeval).
This is needed for version-3 tz-format files; it supports time
stamps past 2037 for America/Godthab (the only entry in the tz
database for which this change is relevant).
* manual/time.texi (TZ Variable): Document transition times
from -167:59:59 through -00:00:01.
* time/tzset.c (tz_rule): Time of day is now signed.
(__tzset_parse_tz): Parse negative time of day.
* manual/time.texi (TZ Variable): Document transition times from
25:00:00 through 167:59:59. These are already supported, and this
support will help with version-3 tz-format files.
[BZ #2636]
* manual/time.texi (Processor Time): Return type of times is
elapsed real time since an arbitrary point in the past.
(CPU Time): Move CLK_TCK from here...
(Processor Time): ...to here. Correct description.
* manual/conf.texi (Constants for Sysconf): Correct description of
_SC_CLK_TCK.
2007-10-28 Ulrich Drepper <drepper@redhat.com>
[BZ #5222]
* elf/dl-load.c (_dl_rtld_di_serinfo): Correct handling of short
path elements in counting mode.
2002-06-29 Ulrich Drepper <drepper@redhat.com>
* catgets/gencat.c (read_input_file): Handle more than one slash
at end of line correctly [PR libc/3926].
Based on a patch by Steven Kim <steven.kim@peregrine.com>.
* catgets/sample.SJIS: Add test case for above bug.
* catgets/test-gencat.c: Adjust test code.
* catgets/test-gencat.sh: Adjust expected results.
* elf/do-rel.h (elf_dynamic_do_rel): Avoid overflow in computation
to skip relative relocations.
Patch by Geoff Keating <geoffk@redhat.com>.
2002-03-14 Jakub Jelinek <jakub@redhat.com>
* locale/broken_cur_max.c (__ctype_get_mb_cur_max): Use nl_langinfo.
* locale/Versions (_nl_current_LC_COLLATE, _nl_current_LC_CTYPE):
Remove.
2002-03-14 Jakub Jelinek <jakub@redhat.com>
* sysdeps/generic/mp_clz_tab.c: New file.
* sysdeps/i386/mp_clz_tab.c: New file.
* sysdeps/hppa/mp_clz_tab.c: New file.
* sysdeps/powerpc/mp_clz_tab.c: New file.
* stdlib/Makefile (aux): Revert last patch.
* math/Makefile (gmp-objs): Likewise.
2002-03-13 Paul Eggert <eggert@twinsun.com>
* time/strftime.c: Comment fixes for references to obsolescent
standards, In most cases the simplest fix is to remove the
confusing comments. Cross-referencing all the standards properly
is a bit of a pain, and it should be enough to put that info in
the documentation as I did in my recent time.texi patch.
2002-03-13 Paul Eggert <eggert@twinsun.com>
* manual/time.texi (Formatting Calendar Time):
ISO C99 also specifies the E and O modifiers.
%P is a GNU extension, and is not in ISO C99.
Mention that %r is equivalent to %I:%M:%S %p in the POSIX locale.
%T is also in ISO C99.
The RFC 822 example is not valid in arbitrary locales.
Reword the POSIX.2 wording slightly, to make it a bit clearer
that POSIX.2 formats are also supported by later POSIX versions.
If a format was introduced in ISO C99 it is also required by
POSIX.1-2001.
2001-08-31 Ulrich Drepper <drepper@redhat.com>
* time/strptime.c (strptime_internal): Recognize 'l' format and
handle it like 'I' for symmatry with strftime.
* manual/message.texi (Advanced gettext functions): Change
description of plural forms for Slovak.
Reported by Marcel Telka <marcel@telka.sk>.
* manuaL/time.texi (Low-Level Time String Parsing): Fix description of
%z. Reported by C. Scott Ananian <cananian@lesser-magoo.lcs.mit.edu>.
2001-08-26 Jakub Jelinek <jakub@redhat.com>
* sysdeps/s390/s390-32/dl-machine.h (elf_machine_lazy_rel): Fix a
typo. Patch by Florian La Roche <laroche@redhat.com>.
2001-08-26 Ulrich Drepper <drepper@redhat.com>
Florian Weimer