POSIX.1-2024 (now official) specifies tm_gmtoff and tm_zone.
This is a good time to update the manual’s “Date and Time”
chapter so I went through it, fixed some outdated
stuff that had been in there for decades, and improved it to match
POSIX.1-2024 better and to clarify some implementation-defined
behavior. Glibc already conforms to POSIX.1-2024 in these matters, so
this is merely a documentation change.
* manual/examples/strftim.c: Use snprintf instead of now-deprecated
function asctime. Check for localtime failure. Simplify by using
puts instead of fputs. Prefer ‘buf, sizeof buf’ to less-obvious
‘buffer, SIZE’.
* manual/examples/timespec_subtract.c: Modernize to use struct
timespec not struct timeval, and rename from timeval_subtract.c.
All uses changed. Check for overflow. Do not check for negative
return value, which ought to be OK since negative time_t is OK.
Use GNU indenting style.
* manual/time.texi:
Document CLOCKS_PER_SEC, TIME_UTC, timespec_get, timespec_getres,
strftime_l.
Document the storage lifetime of tm_zone and of tzname.
Caution against use of tzname, timezone and daylight, saying that
these variables have unspecified values when TZ is geographic.
This is what glibc actually does (contrary to what the manual said
before this patch), and POSIX is planned to say the same thing
<https://austingroupbugs.net/view.php?id=1816>.
Also say that directly accessing the variables is not thread-safe.
Say that localtime_r and ctime_r don’t necessarily set time zone
state. Similarly, in the tzset documentation, say that it is called
by ctime, localtime, mktime, strftime, not that it is called by all
time conversion functions that depend on the time zone.
Say that tm_isdst is useful mostly just for mktime, and that
other uses should prefer tm_gmtoff and tm_zone instead.
Do not say that strftime ignores tm_gmtoff and tm_zone, because
it doesn’t do that.
Document what gmtime does to tm_gmtoff and tm_zone.
Say that the asctime, asctime_r, ctime, and ctime_r are now deprecated
and/or obsolescent, and that behavior is undefined if the year is <
1000 or > 9999. Document strftime before these now-obsolescent
functions, so that readers see the useful function first.
Coin the terms “geographical format” and “proleptic format” for the
two main formats of TZ settings, to simplify exposition. Use this
wording consistently.
Update top-level proleptic syntax to match POSIX.1-2024, which glibc
already implements. Document the angle-bracket quoted forms of time
zone abbreviations in proleptic TZ. Say that time zone abbreviations
can contain only ASCII alphanumerics, ‘+’, and ‘-’.
Document what happens if the proleptic form specifies a DST
abbreviation and offset but omits the rules. POSIX says this is
implementation-defined so we need to document it. Although this
documentation mentions ‘posixrules’ tersely, we need to rethink
‘posixrules’ since I think it stops working after 2038.
Clarify wording about TZ settings beginning with ‘;’.
Say that timegm is in ISO C (as of C23).
Say that POSIX.1-2024 removed gettimeofday.
Say that tm_gmtoff and tm_zone are extensions to ISO C, which is
clearer than saying they are invisible in a struct ISO C enviroment,
and gives us more wiggle room if we want to make them visible in
strict ISO C, something that ISO C allows.
Drop mention of old standards like POSIX.1c and POSIX.2-1992 in the
text when the history is so old that it’s no longer useful in a
general-purpose manual.
Define Coordinated Universal Time (UTC), time zone, time zone ruleset,
and POSIX Epoch, and use these phrases more consistently.
Improve TZ examples to show more variety, and to reflect current
practice and timestamps. Remove obsolete example about Argentina.
Add an example for Ireland.
Don’t rely on GCC extensions when explaining ctime_r.
Do not say that difftime produces the mathematically correct result,
since it might be inexact.
For clock_t don’t say “as in the example above” when there is no
such example, and don’t say that casting to double works “properly
and consistently no matter what”, as it suffers from rounding and
overflow.
Don’t say broken-down time is not useful for calculations; it’s
merely painful.
Say that UTC is not defined before 1960.
Rename Time Zone Functions to Time Zone State. All uses changed.
Update Internet RFC 822 → 5322, 1305 → 5905. Drop specific years of
ISO 8601 as they don’t matter.
Minor style changes: @code{"..."} → @t{"..."} to avoid overquoting in
info files, @code → @env for environment variables, Daylight Saving
Time → daylight saving time, white space → whitespace, prime meridian
→ Prime Meridian.
All the crypt related functions, cryptographic algorithms, and
make requirements are removed, with only the exception of md5
implementation which is moved to locale folder since it is
required by localedef for integrity protection (libc's
locale-reading code does not check these, but localedef does
generate them).
Besides thec code itself, both internal documentation and the
manual is also adjusted. This allows to remove both --enable-crypt
and --enable-nss-crypt configure options.
Checked with a build for all affected ABIs.
Co-authored-by: Zack Weinberg <zack@owlfolio.org>
Reviewed-by: Carlos O'Donell <carlos@redhat.com>
Thank Yinyu Cai for their maintainership of the LoongArch port.
Thank Vineet Gupta for their maintainership of the ARC port.
Thank Tulio Magno Quites Machado Filho for their past maintainership
of the PowerPC port.
Thank Rajalakshmi Srinivasaraghavan for their current maintainership
of the PowerPC port.
The @refill command has been obsolete for a while and now texinfo has
started warning about it.
Reviewed-by: Florian Weimer <fweimer@redhat.com>
Signed-off-by: Siddhesh Poyarekar <siddhesh@sourceware.org>
Move non-ASCII contributor names from installed headers
into contrib.texi when possible, and when it's not (the
copyright notice in sysdeps/unix/sysv/linux/mips/sys/user.h)
go back to ASCIIfied names. Problem reported by Joseph Myers in:
https://www.sourceware.org/ml/libc-alpha/2019-08/msg00646.html
* NEWS: Add the list of bugs fixed in 2.29.
* manual/contrib.texi: Update contributors list with some more
names.
* manual/install.texi: Update latest versions of packages
tested.
* INSTALL: Regenerated.
This is a major rewrite of the description of 'crypt', 'getentropy',
and 'getrandom'.
A few highlights of the content changes:
- Throughout the manual, public headers, and user-visible messages,
I replaced the term "password" with "passphrase", the term
"password database" with "user database", and the term
"encrypt(ion)" with "(one-way) hashing" whenever it was applied to
passphrases. I didn't bother making this change in internal code
or tests. The use of the term "password" in ruserpass.c survives,
because that refers to a keyword in netrc files, but it is adjusted
to make this clearer.
There is a note in crypt.texi explaining that they were
traditionally called passwords but single words are not good enough
anymore, and a note in users.texi explaining that actual passphrase
hashes are found in a "shadow" database nowadays.
- There is a new short introduction to the "Cryptographic Functions"
section, explaining how we do not intend to be a general-purpose
cryptography library, and cautioning that there _are_, or have
been, legal restrictions on the use of cryptography in many
countries, without getting into any kind of detail that we can't
promise to keep up to date.
- I added more detail about what a "one-way function" is, and why
they are used to obscure passphrases for storage. I removed the
paragraph saying that systems not connected to a network need no
user authentication, because that's a pretty rare situation
nowadays. (It still says "sometimes it is necessary" to
authenticate the user, though.)
- I added documentation for all of the hash functions that glibc
actually supports, but not for the additional hash functions
supported by libxcrypt. If we're going to keep this manual section
around after the transition is more advanced, it would probably
make sense to add them then.
- There is much more detailed discussion of how to generate a salt,
and the failure behavior for crypt is documented. (Returning an
invalid hash on failure is what libxcrypt does; Solar Designer's
notes say that this was done "for compatibility with old programs
that assume crypt can never fail".)
- As far as I can tell, the header 'crypt.h' is entirely a GNU
invention, and never existed on any other Unix lineage. The
function 'crypt', however, was in Issue 1 of the SVID and is now
in the XSI component of POSIX. I tried to make all of the
@standards annotations consistent with this, but I'm not sure I got
them perfectly right.
- The genpass.c example has been improved to use getentropy instead
of the current time to generate the salt, and to use a SHA-256 hash
instead of MD5. It uses more random bytes than is strictly
necessary because I didn't want to complicate the code with proper
base64 encoding.
- The testpass.c example has three hardwired hashes now, to
demonstrate that different one-way functions produce different
hashes for the same input. It also demonstrates how DES hashing
only pays attention to the first eight characters of the input.
- There is new text explaining in more detail how a CSPRNG differs
from a regular random number generator, and how
getentropy/getrandom are not exactly a CSPRNG. I tried not to make
specific falsifiable claims here. I also tried to make the
blocking/cancellation/error behavior of both getentropy and
getrandom clearer.
Since tile support has been removed from the Linux kernel for 4.17,
this patch removes the (unmaintained) port to tilegx from glibc (the
tilepro support having been previously removed). This reflects the
general principle that a glibc port needs upstream support for the
architecture in all the components it build-depends on (so binutils,
GCC and the Linux kernel, for the normal case of a port supporting the
Linux kernel but no other OS), in order to be maintainable.
Apart from removal of sysdeps/tile and sysdeps/unix/sysv/linux/tile,
there are updates to various comments referencing tile for which
removal of those references seemed appropriate. The configuration is
removed from README and from build-many-glibcs.py. contrib.texi keeps
mention of removed contributions, but I updated Chris Metcalf's entry
to reflect that he also contributed the non-removed support for the
generic Linux kernel syscall interface.
__ASSUME_FADVISE64_64_NO_ALIGN support is removed, as it was only used
by tile.
* sysdeps/tile: Remove.
* sysdeps/unix/sysv/linux/tile: Likewise.
* README (tilegx-*-linux-gnu): Remove from list of supported
configurations.
* manual/contrib.texi (Contributors): Mention Chris Metcalf's
contribution of support for generic Linux kernel syscall
interface.
* scripts/build-many-glibcs.py (Context.add_all_configs): Remove
tilegx configurations.
(Config.install_linux_headers): Do not handle tile.
* sysdeps/unix/sysv/linux/aarch64/ldsodefs.h: Do not mention Tile
in comment.
* sysdeps/unix/sysv/linux/nios2/Makefile: Likewise.
* sysdeps/unix/sysv/linux/posix_fadvise.c: Likewise.
[__ASSUME_FADVISE64_64_NO_ALIGN] (__ALIGNMENT_ARG): Remove
conditional undefine and redefine.
* sysdeps/unix/sysv/linux/posix_fadvise64.c: Do not mention Tile
in comment.
[__ASSUME_FADVISE64_64_NO_ALIGN] (__ALIGNMENT_ARG): Remove
conditional undefine and redefine.
This patch removes the Banner mechanism, with the last remaining
Banner file replaced by a contrib.texi entry. This accords with the
principle that the output of running libc.so.6 is not the place to
credit particular contributions (the manual is), and with all other
configuration options not mentioned there, it doesn't seem appropriate
to focus there on the one question of whether the one remaining piece
configured as an add-on was enabled or not.
Tested for x86_64.
* csu/Makefile (generated): Do not add version-info.h.
(before-compile): Likewise.
(all-Banner-files): Remove variable.
($(objpfx)version-info.h): Remove rule.
* csu/version.c (banner): Do not include "version-info.h".
* libidn/Banner: Remove.
* manual/contrib.texi (Simon Josefsson): New entry.
Various subdirectories of glibc include Banner files to put some text
in the output of executing libc.so.6, under "Available extensions".
Some of those subdirectories (e.g. crypt) may originally have been
add-ons (and so optional, so a particular glibc build might or might
not have included them), but except for libidn they aren't now (or if
only included in some builds, in the case of soft-fp, the inclusion
depends on the architecture for which glibc is configured rather than
having any glibc configuration for which it's an optional feature),
and it doesn't seem useful for the libc.so.6 output to call out a few
features like that.
This patch removes the non-add-on Banner files, updating contrib.texi
where they noted contributions not otherwise mentioned there.
Tested for x86_64.
* crypt/Banner: Remove file.
* nptl/Banner: Likewise.
* resolv/Banner: Likewise.
* soft-fp/Banner: Likewise.
* nptl/Makefile ($(objpfx)banner.h): Remove rule.
($(objpfx)version.d): Remove dependency on banner.h.
($(objpfx)version.os): Likewise.
* nptl/version.c (banner): Do not include banner.h.
* manual/contrib.texi: Update entries for Richard Henderson, Jakub
Jelinek and BIND code.
Update all translations.
Update contributions in the manual.
Update installation notes with information about newest working tools.
Reconfigure using exactly autoconf 2.69.
Regenerate INSTALL.
[BZ #13743]
A new class of installed headers has been documented for low-level
platform-specific functionality. PowerPC added the first instance with a
function to provide time base register access (__ppc_get_timebase). This
is required for applications that measure time at high frequencies with
high precision that can't afford a syscall.
* manual/contrib.texi (Contributors): Fix cross reference.
* manual/libc.texinfo (Copying): Include freemanuals.
* manual/Makefile (appendices): Add freemanuals.
* manual/freemanuals.texi: New file.
Patch by Brian Youmans <3diff@gnu.org>.
* manual/libm-err-tab.pl: Pretty print more platforms, print a
smaller table.
* manual/math.texi (Errors in Math Functions): Fix grammar, start
table on separate page.
Patch by Brian Youmans <3diff@gnu.org>.
1999-06-09 Jakub Jelinek <jj@ultra.linux.cz>
* stdlib/longlong.h: gas changed sethi handling when without
%hi(). Fix assembly.
* sysdeps/generic/dl-cache.c (_dl_cache_lookup): Allow
port specific cache id checks.
* sysdeps/generic/dl-cache.h: New file.
* sysdeps/unix/sysv/linux/sparc/sparc64/dl-cache.h: New file.
1998-03-18 00:25 Tim Waugh <tim@cyberelk.demon.co.uk>
* posix/wordexp.c (parse_comm): Allow quoting inside $(...).
(parse_param): Fold in Andreas' fixes to do with when the end of
the parameter name has been reached, and quoting inside ${...}.
(parse_dollars): Fix differentiation between $(((1+3)*(4-2))) and
$((echo);(ls)).
1998-03-16 22:10 Zack Weinberg <zack@rabi.phys.columbia.edu>
* manual/maint.texi: Split out installation and contribution
sections to their own appendices. Misc cleanups.
* manual/install.texi: New file. Mention add-ons. Refer to FAQ.
* manual/contrib.texi: New file.
* manual/libc.texinfo: Pull in new appendices.
* manual/header.texi: Correct node pointer.
1998-03-17 Andreas Jaeger <aj@arthur.rhein-neckar.de>
* manual/process.texi (Process Completion): Clarify return value
of waitpid a bit. Patch by Zack Weinberg. [PR libc/490]
