Go to file
Paul Eggert ee768a30fe Modernize and fix doc’s “Date and Time” (BZ 31876)
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.
2024-06-15 08:53:50 -07:00
advisories Document CVE-2024-33599, CVE-2024-33600, CVE-2024-33601, CVE-2024-33602 2024-05-06 15:12:31 -04:00
argp Update copyright dates with scripts/update-copyrights 2024-01-01 10:53:40 -08:00
assert Update copyright dates with scripts/update-copyrights 2024-01-01 10:53:40 -08:00
benchtests Modernize and fix doc’s “Date and Time” (BZ 31876) 2024-06-15 08:53:50 -07:00
bits socket: Use may_alias on sockaddr structs (bug 19622) 2024-05-18 09:33:19 +02:00
catgets Update copyright dates not handled by scripts/update-copyrights 2024-01-01 10:53:40 -08:00
ChangeLog.old Create ChangeLog.old/ChangeLog.28 2024-01-31 01:34:58 +01:00
conform conform: Reformat Makefile. 2024-02-25 13:38:16 -05:00
csu Add crt1-2.0.o for glibc 2.0 compatibility tests 2024-05-06 07:49:40 -07:00
ctype ctype: Reformat Makefile. 2024-02-25 13:38:16 -05:00
debug Unify output from backtrace_symbols_fd with backtrace_symbols (bug 31730) 2024-05-14 12:55:06 +02:00
dirent powerpc: Remove duplicated versionsort from libm.a (BZ 31789) 2024-05-23 13:41:29 -03:00
dlfcn dlfcn: Reformat Makefile. 2024-02-25 13:38:16 -05:00
elf elf: Change module-names to modules-names in comments 2024-06-14 13:29:21 -07:00
gmon Define write_profiling functions only in profile library [BZ #31756] 2024-05-22 06:12:55 -07:00
gnulib Update copyright dates with scripts/update-copyrights 2024-01-01 10:53:40 -08:00
hesiod hesiod: Reformat Makefile. 2024-02-25 13:38:16 -05:00
htl htl: Implement some support for TLS_DTV_AT_TP 2024-03-23 23:00:30 +01:00
hurd hurd: Fix getxattr/listxattr returning ERANGE 2024-06-10 22:01:40 +02:00
iconv Update copyright dates not handled by scripts/update-copyrights 2024-01-01 10:53:40 -08:00
iconvdata iconv: ISO-2022-CN-EXT: fix out-of-bound writes when writing escape sequence (CVE-2024-2961) 2024-04-17 09:21:40 -03:00
include posix: Sync tempname with gnulib 2024-04-10 14:53:39 -03:00
inet socket: Use may_alias on sockaddr structs (bug 19622) 2024-05-18 09:33:19 +02:00
intl Update copyright dates with scripts/update-copyrights 2024-01-01 10:53:40 -08:00
io Always define __USE_TIME_BITS64 when 64 bit time_t is used 2024-04-02 15:28:36 -03:00
libio <stdio.h>: Acknowledge that getdelim/getline are in POSIX 2024-06-11 22:17:12 +01:00
locale locale: Handle loading a missing locale twice (Bug 14247) 2024-04-22 16:03:00 -04:00
localedata localedata: Lowercase day and abday in cs_CZ 2024-06-11 10:33:54 +02:00
login login: Use unsigned 32-bit types for seconds-since-epoch 2024-04-19 14:38:17 +02:00
mach mach: Drop some unnecessary vm_param.h includes 2024-01-03 21:59:54 +01:00
malloc malloc: New test to check malloc alternate path using memory obstruction 2024-06-04 18:00:29 +02:00
manual Modernize and fix doc’s “Date and Time” (BZ 31876) 2024-06-15 08:53:50 -07:00
math Don't provide scalb/significand _FloatN aliases [BZ #31760] 2024-05-22 06:10:54 -07:00
mathvec Update copyright dates with scripts/update-copyrights 2024-01-01 10:53:40 -08:00
misc socket: Use may_alias on sockaddr structs (bug 19622) 2024-05-18 09:33:19 +02:00
nis Update copyright dates with scripts/update-copyrights 2024-01-01 10:53:40 -08:00
nptl nptl: Add tst-pthread-key1-static for BZ #21777 2024-04-09 05:27:03 -07:00
nptl_db Update copyright dates with scripts/update-copyrights 2024-01-01 10:53:40 -08:00
nscd nscd: Use time_t for return type of addgetnetgrentX 2024-05-02 18:59:29 +02:00
nss getaddrinfo: translate ENOMEM to EAI_MEMORY (bug 31163) 2024-01-02 11:10:42 +01:00
po po: Update translations 2024-01-31 01:10:02 +01:00
posix getconf: Add NPROCESSORS_{CONF,ONLN} [BZ #31661] 2024-06-05 14:57:54 +02:00
resolv resolv: Track single-request fallback via _res._flags (bug 31476) 2024-06-13 18:56:30 +02:00
resource Always define __USE_TIME_BITS64 when 64 bit time_t is used 2024-04-02 15:28:36 -03:00
rt Always define __USE_TIME_BITS64 when 64 bit time_t is used 2024-04-02 15:28:36 -03:00
scripts tunables: sort tunables list (BZ 30027) 2024-06-12 14:45:18 -04:00
setjmp Update copyright dates with scripts/update-copyrights 2024-01-01 10:53:40 -08:00
signal Always define __USE_TIME_BITS64 when 64 bit time_t is used 2024-04-02 15:28:36 -03:00
socket socket: Use may_alias on sockaddr structs (bug 19622) 2024-05-18 09:33:19 +02:00
soft-fp soft-fp: Add brain format support 2024-02-01 19:06:54 +01:00
stdio-common Revert "Test fscanf of long double without <stdio.h>" 2024-05-24 16:24:49 -07:00
stdlib stdlib: Describe __cxa_finalize usage in function comment 2024-06-03 19:04:58 +02:00
string wcsmbs: Ensure wcstr worst-case linear execution time (BZ 23865) 2024-04-11 14:21:32 -03:00
sunrpc Update copyright dates with scripts/update-copyrights 2024-01-01 10:53:40 -08:00
support support: Fix typo in xgetsockname error message 2024-06-05 09:58:55 -04:00
sysdeps x86: Fix value for x86_memset_non_temporal_threshold when it is undesirable 2024-06-14 17:25:05 -05:00
sysvipc Always define __USE_TIME_BITS64 when 64 bit time_t is used 2024-04-02 15:28:36 -03:00
termios Update copyright dates with scripts/update-copyrights 2024-01-01 10:53:40 -08:00
time Modernize and fix doc’s “Date and Time” (BZ 31876) 2024-06-15 08:53:50 -07:00
timezone timezone: sync to TZDB 2024a 2024-04-07 13:35:48 -07:00
wcsmbs wcsmbs: Ensure wcstr worst-case linear execution time (BZ 23865) 2024-04-11 14:21:32 -03:00
wctype Update copyright dates with scripts/update-copyrights 2024-01-01 10:53:40 -08:00
.clang-format Update copyright dates with scripts/update-copyrights 2024-01-01 10:53:40 -08:00
.gitattributes Assume __NR_openat is always defined 2016-03-23 23:35:08 +01:00
.gitignore Add *.pyc to .gitignore 2015-05-18 15:26:26 +05:30
abi-tags Remove the bulk of the NaCl port. 2017-05-20 08:09:10 -04:00
aclocal.m4 configure: Use autoconf 2.71 2023-07-17 10:08:10 -04:00
config.h.in LoongArch: Add support for TLS Descriptors 2024-05-15 10:31:53 +08:00
config.make.in crypt: Remove libcrypt support 2023-10-30 13:03:59 -03:00
configure elf: Enable TLS descriptor tests on aarch64 2024-03-19 14:53:30 -03:00
configure.ac elf: Enable TLS descriptor tests on aarch64 2024-03-19 14:53:30 -03:00
CONTRIBUTED-BY crypt: Remove libcrypt support 2023-10-30 13:03:59 -03:00
COPYING Update to latest versions of GPL-2.0 and LGPL-2.1 2013-09-09 12:52:48 +10:00
COPYING.LIB Update to latest versions of GPL-2.0 and LGPL-2.1 2013-09-09 12:52:48 +10:00
extra-lib.mk Rename cppflags-iterator.mk to libof-iterator.mk, remove extra-modules.mk. 2017-05-09 07:06:29 -04:00
gen-locales.mk locale: Handle loading a missing locale twice (Bug 14247) 2024-04-22 16:03:00 -04:00
INSTALL Make sure INSTALL is ASCII plaintext again 2024-04-30 09:54:07 +02:00
libc-abis riscv: support GNU indirect function 2021-01-10 21:25:13 -05:00
libof-iterator.mk Rename cppflags-iterator.mk to libof-iterator.mk, remove extra-modules.mk. 2017-05-09 07:06:29 -04:00
LICENSES Relicense IBM portions of resolv/base64.c resolv/res_debug.c. 2024-01-26 13:33:36 -05:00
MAINTAINERS Add MAINTAINERS 2017-05-11 13:38:30 -04:00
Makeconfig tunables: sort tunables list (BZ 30027) 2024-06-12 14:45:18 -04:00
Makefile Pass -nostdlib -nostartfiles together with -r [BZ #31753] 2024-05-19 16:29:02 -07:00
Makefile.help math: Add support for auto static math tests 2024-05-21 16:53:27 -03:00
Makefile.in New make target to only build benchmark binaries 2016-04-20 10:23:28 +05:30
Makerules Support compiling .S files with additional options 2024-02-25 09:22:40 -08:00
NEWS Linux: Add epoll ioctls 2024-06-04 12:09:15 -05:00
o-iterator.mk Fri Mar 17 12:58:37 1995 Roland McGrath <roland@churchy.gnu.ai.mit.edu> 1995-03-17 18:42:51 +00:00
README Remove ia64-linux-gnu 2024-01-08 17:09:36 -03:00
Rules Add crt1-2.0.o for glibc 2.0 compatibility tests 2024-05-06 07:49:40 -07:00
SECURITY.md Adapt the security policy for the security page 2023-12-05 09:15:10 -05:00
SHARED-FILES localedata: Fix several issues with the set of characters considered 0-width [BZ #31370] 2024-05-15 14:31:06 +02:00
shlib-versions crypt: Remove libcrypt support 2023-10-30 13:03:59 -03:00
test-skeleton.c Update copyright dates with scripts/update-copyrights 2024-01-01 10:53:40 -08:00
version.h Open master branch for glibc 2.40 development 2024-01-31 02:07:20 +01:00

This directory contains the sources of the GNU C Library.
See the file "version.h" for what release version you have.

The GNU C Library is the standard system C library for all GNU systems,
and is an important part of what makes up a GNU system.  It provides the
system API for all programs written in C and C-compatible languages such
as C++ and Objective C; the runtime facilities of other programming
languages use the C library to access the underlying operating system.

In GNU/Linux systems, the C library works with the Linux kernel to
implement the operating system behavior seen by user applications.
In GNU/Hurd systems, it works with a microkernel and Hurd servers.

The GNU C Library implements much of the POSIX.1 functionality in the
GNU/Hurd system, using configurations i[4567]86-*-gnu and x86_64-gnu.

When working with Linux kernels, this version of the GNU C Library
requires Linux kernel version 3.2 or later.

Also note that the shared version of the libgcc_s library must be
installed for the pthread library to work correctly.

The GNU C Library supports these configurations for using Linux kernels:

	aarch64*-*-linux-gnu
	alpha*-*-linux-gnu
	arc*-*-linux-gnu
	arm-*-linux-gnueabi
	csky-*-linux-gnuabiv2
	hppa-*-linux-gnu
	i[4567]86-*-linux-gnu
	x86_64-*-linux-gnu	Can build either x86_64 or x32
	loongarch64-*-linux-gnu Hardware floating point, LE only.
	m68k-*-linux-gnu
	microblaze*-*-linux-gnu
	mips-*-linux-gnu
	mips64-*-linux-gnu
	or1k-*-linux-gnu
	powerpc-*-linux-gnu	Hardware or software floating point, BE only.
	powerpc64*-*-linux-gnu	Big-endian and little-endian.
	s390-*-linux-gnu
	s390x-*-linux-gnu
	riscv32-*-linux-gnu
	riscv64-*-linux-gnu
	sh[34]-*-linux-gnu
	sparc*-*-linux-gnu
	sparc64*-*-linux-gnu

If you are interested in doing a port, please contact the glibc
maintainers; see https://www.gnu.org/software/libc/ for more
information.

See the file INSTALL to find out how to configure, build, and install
the GNU C Library.  You might also consider reading the WWW pages for
the C library at https://www.gnu.org/software/libc/.

The GNU C Library is (almost) completely documented by the Texinfo manual
found in the `manual/' subdirectory.  The manual is still being updated
and contains some known errors and omissions; we regret that we do not
have the resources to work on the manual as much as we would like.  For
corrections to the manual, please file a bug in the `manual' component,
following the bug-reporting instructions below.  Please be sure to check
the manual in the current development sources to see if your problem has
already been corrected.

Please see https://www.gnu.org/software/libc/bugs.html for bug reporting
information.  We are now using the Bugzilla system to track all bug reports.
This web page gives detailed information on how to report bugs properly.

The GNU C Library is free software.  See the file COPYING.LIB for copying
conditions, and LICENSES for notices about a few contributions that require
these additional notices to be distributed.  License copyright years may be
listed using range notation, e.g., 1996-2015, indicating that every year in
the range, inclusive, is a copyrightable year that would otherwise be listed
individually.