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.
Remove the unused 'char *name;' from the example.
Use write instead of putchar to write input as it is read.
Example tested on x86_64 by compiling and running the example.
Tested by building the manual pdf and reviewing the results.
Reviewed-by: Florian Weimer <fweimer@redhat.com>
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>
I used these shell commands:
../glibc/scripts/update-copyrights $PWD/../gnulib/build-aux/update-copyright
(cd ../glibc && git commit -am"[this commit message]")
and then ignored the output, which consisted lines saying "FOO: warning:
copyright statement not found" for each of 7061 files FOO.
I then removed trailing white space from math/tgmath.h,
support/tst-support-open-dev-null-range.c, and
sysdeps/x86_64/multiarch/strlen-vec.S, to work around the following
obscure pre-commit check failure diagnostics from Savannah. I don't
know why I run into these diagnostics whereas others evidently do not.
remote: *** 912-#endif
remote: *** 913:
remote: *** 914-
remote: *** error: lines with trailing whitespace found
...
remote: *** error: sysdeps/unix/sysv/linux/statx_cp.c: trailing lines
I used these shell commands:
../glibc/scripts/update-copyrights $PWD/../gnulib/build-aux/update-copyright
(cd ../glibc && git commit -am"[this commit message]")
and then ignored the output, which consisted lines saying "FOO: warning:
copyright statement not found" for each of 6694 files FOO.
I then removed trailing white space from benchtests/bench-pthread-locks.c
and iconvdata/tst-iconv-big5-hkscs-to-2ucs4.c, to work around this
diagnostic from Savannah:
remote: *** pre-commit check failed ...
remote: *** error: lines with trailing whitespace found
remote: error: hook declined to update refs/heads/master
Validation for pointer returned by backtrace_symbols () added.
Type of variables size and i is changed from size_t to int.
Variable size is used to collect the result from backtrace ()
that is an int. i is the loop counter variable so it can be an int.
Since, size_t size is changed to int size, in printf %zd is changed to %d.
Reviewed-by: DJ Delorie <dj@redhat.com>
The twalk function is very difficult to use in a multi-threaded
program because there is no way to pass external state to the
iterator function.
Reviewed-by: Carlos O'Donell <carlos@redhat.com>
Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org>
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.
The example did not work because the null byte was not converted, and
mbrtowc was called with a zero-length input string. This results in a
(size_t) -2 return value, so the function always returns NULL.
The size computation for the heap allocation of the result was
incorrect because it did not deal with integer overflow.
Error checking was missing, and the allocated memory was not freed on
error paths. All error returns now set errno. (Note that there is an
assumption that free does not clobber errno.)
The slightly unportable comparision against (size_t) -2 to catch both
(size_t) -1 and (size_t) -2 return values is gone as well.
A null wide character needs to be stored in the result explicitly, to
terminate it.
The description in the manual is updated to deal with these finer
points. The (size_t) -2 behavior (consuming the input bytes) matches
what is specified in ISO C11.
This patches fixes multiples issues on open_{w}memstream reported on both
BZ#18241 and BZ#20181:
- failed fseek does not set errno.
- negative offset in fseek fails even when resulting position is
a valid one.
- a flush after write if the current write position is not at the
end of the stream currupt data.
The main fix is on seek operation for memstream (_IO_{w}str_seekoff), where
both _IO_read_ptr and _IO_read_end pointer are updated if a write operation
has occured (similar to default file operations). Also, to calculate the
offset on both read and write pointers, a temporary value is instead of
updating the argument supplied value. Negative offset are valid if resulting
internal pointer is within the range of _IO_{read,write}_base and
_IO_{read,write}_end.
Also POSIX states that a null or wide null shall be appended to the current
buffer iff a write moves the position to a value larger than the current
lenght. Current implementation appends a null or wide null regardless
of this condition. This patch fixes it by removing the 'else' condition
on _IO_{w}mem_sync.
Checked on x86_64.
[BZ #18241]
[BZ #20181]
* libio/Makefile (test): Add tst-memstream3 and tst-wmemstream3.
* libio/memstream.c (_IO_mem_sync): Only append a null byte if
write position is at the end the buffer.
* libio/wmemstream.c (_IO_wmem_sync): Likewise.
* libio/strops.c (_IO_str_switch_to_get_mode): New function.
(_IO_str_seekoff): Set correct offset from negative displacement and
set EINVAL for invalid ones.
* libio/wstrops.c (enlarge_userbuf): Use correct function to calculate
buffer length.
(_IO_wstr_switch_to_get_mode): New function.
(_IO_wstr_seekoff): Set correct offset from negative displacement and
set EINVAL for invalid ones.
* libio/tst-memstream3.c: New file.
* libio/tst-wmemstream3.c: Likewise.
* manual/examples/memstrm.c: Remove warning when priting size_t.
Previously, application code had to set up the d_namlen member if
the target supported it, involving conditional compilation. After
this change, glob will use the length of the string in d_name instead
of d_namlen to determine the file name length. All glibc targets
provide the d_type and d_ino members, and setting them as needed for
gl_readdir is straightforward.
Changing the behavior with regards to d_ino is left to a future
cleanup.
* manual/examples/strncat.c: Remove.
This example was misleading, as the code would have undefined
behavior if "hello" was longer than SIZE. Anyway, the manual
shouldn't encourage strncpy+strncat for this sort of thing.
* manual/string.texi (Copying Strings and Arrays): Split into
three sections Copying Strings and Arrays, Concatenating Strings,
and Truncating Strings, as this section was way too long. All
cross-referenced changed. Add advice about string-truncation
functions. Remove misleading strncat example.
This automatically-generated patch converts 29 function definitions in
glibc (including one in an example in the manual) from old-style K&R
to prototype-style. Following my other recent such patches, this one
deals with the case of function definitions where one K&R parameter
declaration declares multiple parameters, as in:
void
foo (a, b)
int a, *b;
{
}
Tested for x86_64 and x86 (testsuite, and that installed stripped
shared libraries are unchanged by the patch).
* crypt/crypt.c (_ufc_doit_r): Convert to prototype-style function
definition.
(_ufc_doit_r): Likewise.
* crypt/crypt_util.c (_ufc_copymem): Likewise.
(_ufc_output_conversion_r): Likewise.
* inet/inet_mkadr.c (__inet_makeaddr): Likewise.
* inet/rcmd.c (rcmd_af): Likewise.
(rcmd): Likewise.
(ruserok_af): Likewise.
(ruserok): Likewise.
(ruserok2_sa): Likewise.
(ruserok_sa): Likewise.
(iruserok_af): Likewise.
(iruserok): Likewise.
(__ivaliduser): Likewise.
(__validuser2_sa): Likewise.
* inet/rexec.c (rexec_af): Likewise.
(rexec): Likewise.
* inet/ruserpass.c (ruserpass): Likewise.
* locale/programs/xmalloc.c (xcalloc): Likewise.
* manual/examples/timeval_subtract.c (timeval_subtract): Likewise.
* math/w_drem.c (__drem): Likewise.
* math/w_dremf.c (__dremf): Likewise.
* math/w_dreml.c (__dreml): Likewise.
* misc/daemon.c (daemon): Likewise.
* resolv/res_debug.c (p_fqnname): Likewise.
* stdlib/div.c (div): Likewise.
* string/memcmp.c (memcmp_bytes): Likewise.
* sunrpc/pmap_rmt.c (pmap_rmtcall): Likewise.
* sunrpc/svc_udp.c (svcudp_bufcreate): Likewise.
Open file description locks have been merged into the Linux kernel for
v3.15. Add the appropriate command-value definitions and an update to
the manual that describes their usage.
2002-11-04 Ulrich Drepper <drepper@redhat.com>
* manual/examples/dir.c: Don't include <stddef.h>.
* manual/examples/select.c: Include <errno.h> for TEMP_FAILURE_RETRY.
Reported by Frdric Delanoy <delanoy_f@yahoo.com>.
2002-11-02 H.J. Lu <hjl@gnu.org>
* stdio-common/reg-printf.c: Include <stddef.h>.
2002-02-02 Ulrich Drepper <drepper@redhat.com>
* manual/examples/mkfsock.c (make_named_socket): Make sure name is
always NUL-terminated. Patch by Chris D. Sloan <cds@cs.hmc.edu>.
2001-05-25 Bruce Mitchener <bruce@cubik.org>
* manual/ctype.texi: Minor fix.
* manual/install.texi: Likewise.
* manual/startup.texi: Likewise.
* manual/examples/dir.c: Use perror() rather than puts().
2001-05-25 David Mosberger <davidm@hpl.hp.com>
* sysdeps/unix/sysv/linux/ia64/bits/sigcontext.h: Put stuff following
#endif directive inside a comment to avoid compiler warnings.
2001-05-25 Philipp Thomas <pthomas@suse.de>
* nis/nis_print.c (nis_nstype2str): Don't mark names of
naming services for translation, only UNKNOWN needs it.
Add comment to prevent it for the future.
2001-05-25 Joseph S. Myers <jsm28@cam.ac.uk>
* misc/sys/cdefs.h (__restrict_arr): Define appropriately for GCC
3.1 and non-GCC C99 compilers.
2001-04-08 Hans-Peter Nilsson <hp@axis.com>
* sysdeps/unix/sysv/linux/cris/Dist: New file.
* sysdeps/unix/sysv/linux/cris/Makefile: New file.
* sysdeps/unix/sysv/linux/cris/_G_config.h: New file.
* sysdeps/unix/sysv/linux/cris/bits/fcntl.h: New file.
* sysdeps/unix/sysv/linux/cris/bits/mman.h: New file.
* sysdeps/unix/sysv/linux/cris/bits/resource.h: New file.
* sysdeps/unix/sysv/linux/cris/brk.c: New file.
* sysdeps/unix/sysv/linux/cris/chown.c: New file.
* sysdeps/unix/sysv/linux/cris/clone.S: New file.
* sysdeps/unix/sysv/linux/cris/fchown.c: New file.
* sysdeps/unix/sysv/linux/cris/fcntl.c: New file.
* sysdeps/unix/sysv/linux/cris/fxstat.c: New file.
* sysdeps/unix/sysv/linux/cris/getegid.c: New file.
* sysdeps/unix/sysv/linux/cris/geteuid.c: New file.
* sysdeps/unix/sysv/linux/cris/getgid.c: New file.
* sysdeps/unix/sysv/linux/cris/getgroups.c: New file.
* sysdeps/unix/sysv/linux/cris/getresgid.c: New file.
* sysdeps/unix/sysv/linux/cris/getresuid.c: New file.
* sysdeps/unix/sysv/linux/cris/getrlimit.c: New file.
* sysdeps/unix/sysv/linux/cris/getrlimit64.c: New file.
* sysdeps/unix/sysv/linux/cris/getuid.c: New file.
* sysdeps/unix/sysv/linux/cris/lchown.c: New file.
* sysdeps/unix/sysv/linux/cris/lockf64.c: New file.
* sysdeps/unix/sysv/linux/cris/lxstat.c: New file.
* sysdeps/unix/sysv/linux/cris/mmap.S: New file.
* sysdeps/unix/sysv/linux/cris/mmap64.S: New file.
* sysdeps/unix/sysv/linux/cris/msgctl.c: New file.
* sysdeps/unix/sysv/linux/cris/profil-counter.h: New file.
* sysdeps/unix/sysv/linux/cris/register-dump.h: New file.
* sysdeps/unix/sysv/linux/cris/semctl.c: New file.
* sysdeps/unix/sysv/linux/cris/setegid.c: New file.
* sysdeps/unix/sysv/linux/cris/seteuid.c: New file.
* sysdeps/unix/sysv/linux/cris/setfsgid.c: New file.
* sysdeps/unix/sysv/linux/cris/setfsuid.c: New file.
* sysdeps/unix/sysv/linux/cris/setgid.c: New file.
* sysdeps/unix/sysv/linux/cris/setgroups.c: New file.
* sysdeps/unix/sysv/linux/cris/setregid.c: New file.
* sysdeps/unix/sysv/linux/cris/setresgid.c: New file.
* sysdeps/unix/sysv/linux/cris/setresuid.c: New file.
* sysdeps/unix/sysv/linux/cris/setreuid.c: New file.
* sysdeps/unix/sysv/linux/cris/setrlimit.c: New file.
* sysdeps/unix/sysv/linux/cris/setuid.c: New file.
* sysdeps/unix/sysv/linux/cris/shmctl.c: New file.
* sysdeps/unix/sysv/linux/cris/socket.S: New file.
* sysdeps/unix/sysv/linux/cris/sys/ucontext.h: New file.
* sysdeps/unix/sysv/linux/cris/syscall.S: New file.
* sysdeps/unix/sysv/linux/cris/sysdep.S: New file.
* sysdeps/unix/sysv/linux/cris/sysdep.h: New file.
* sysdeps/unix/sysv/linux/cris/vfork.S: New file.
* sysdeps/unix/sysv/linux/cris/xstat.c: New file.
2001-04-08 Hans-Peter Nilsson <hp@axis.com>
* sysdeps/cris/Dist: New file.
* sysdeps/cris/Implies: New file.
* sysdeps/cris/Makefile: New file.
* sysdeps/cris/__longjmp.S: New file.
* sysdeps/cris/_mcount.S: New file.
* sysdeps/cris/bits/endian.h: New file.
* sysdeps/cris/bits/setjmp.h: New file.
* sysdeps/cris/bits/string.h: New file.
* sysdeps/cris/dl-machine.h: New file.
* sysdeps/cris/elf/start.S: New file.
* sysdeps/cris/machine-gmon.h: New file.
* sysdeps/cris/memcopy.h: New file.
* sysdeps/cris/memusage.h: New file.
* sysdeps/cris/setjmp.S: New file.
* sysdeps/cris/sysdep.h: New file.
* sysdeps/cris/wordcopy.c: New file.
2001-04-08 Hans-Peter Nilsson <hp@axis.com>
* elf/elf.h: Add new relocations for CRIS.
2001-04-08 Hans-Peter Nilsson <hp@axis.com>
* shlib-versions: Add cases for Linux on CRIS.
2001-04-08 Hans-Peter Nilsson <hp@axis.com>
* configure.in (ASM_LINE_SEP tests): Handle CRIS assembly, with
';' for comments and '@' for line separator.
2001-04-08 Hans-Peter Nilsson <hp@axis.com>
* sysdeps/unix/sysv/linux/hppa/sysdep.h (INLINE_SYSCALL): Fix
typo; s/==/=/ for assignment.
2001-04-08 Hans-Peter Nilsson <hp@axis.com>
* malloc/Makefile: Correct comment; mtrace is Perl, not AWK.
2001-04-08 Hans-Peter Nilsson <hp@axis.com>
* iconv/gconv_simple.c (internal_ucs4_loop_unaligned): Check for
empty input before checking full output.
2001-04-08 Hans-Peter Nilsson <hp@axis.com>
* iconv/gconv.c (__gconv): Don't derefer parameter cd before
checking if == -1L.
2001-04-08 Ulrich Drepper <drepper@redhat.com>
* inet/rexec.c (rexec_af): Avoid calling perror with errno being set.
2001-01-07 Ben Collins <bcollins@debian.org>
* manual/examples/longopt.c: Make the "struct option" a little
more like it should be, adding usage of required_argument,
noargument and such, and also setting the options string right.
* manual/sysinfo.texi (Load Average): New section, documents
getloadavg().
