doc/year2038.texi

   1 @node Avoiding the year 2038 problem
   2 @section Avoiding the year 2038 problem
   3
   4 The @dfn{year 2038 problem} denotes unpredictable behaviour that will
   5 likely occur in the year 2038, for programs that use a 32-bit signed
   6 integer @samp{time_t} type that cannot represent timestamps on or
   7 after 2038-01-19 03:14:08 UTC@.  See
   8 @url{https://en.wikipedia.org/wiki/Year_2038_problem, Year 2038
   9 problem} for details.
  10
  11 The Gnulib module @samp{year2038} fixes this problem on some
  12 platforms, by making @code{time_t} wide enough to represent timestamps
  13 after 2038.  This has no effect on most current platforms, which have
  14 timestamps that are already wide enough.  However, @samp{year2038} by
  15 default arranges for builds on legacy 32-bit Linux kernels running
  16 glibc 2.34 and later to compile with @samp{_TIME_BITS=64} to get wider
  17 timestamps.  On older platforms that do not support timestamps after
  18 the year 2038, @samp{year2038} causes @command{configure} to issue a
  19 warning but still proceed.  On platforms that appear to support
  20 post-2038 timestamps but where something prevents this from working,
  21 @command{configure} fails.
  22
  23 The default behavior of @samp{year2038} can be overridden by using the
  24 @command{configure} option @option{--disable-year2038}, which
  25 suppresses support for post-2038 timestamps.  This may be useful if
  26 the package links to other libraries whose user-facing ABIs still
  27 require @code{time_t} to be 32-bit on your platform.
  28
  29 The Gnulib module @samp{year2038-recommended} is like @samp{year2038},
  30 except it by default rejects platforms where @code{time_t} cannot represent
  31 timestamps after 2038.  If this module is used and a 32-platform cannot support
  32 64-bit @code{time_t}, one can still fix the year-2038 problem by using
  33 a 64-bit instead of a 32-bit build, as noted in the architecture list
  34 below.  If all else fails one can configure with
  35 @option{--disable-year2038}; however, the resulting programs will
  36 mishandle timestamps after 2038.
  37
  38 The Gnulib module @samp{year2038-recommended} is designed
  39 for packages intended for use on 32-bit platforms
  40 after the year 2038.  If your package is commonly built on
  41 32-bit platforms that will not be used after the year 2038,
  42 you can use the @samp{year2038} module instead, to save builders
  43 the trouble of configuring with @option{--disable-year2038}.
  44
  45 If the Gnulib module @samp{largefile} is used but neither
  46 @samp{year2038} nor @samp{year2038-recommended} is used,
  47 @command{configure} will have an option @option{--enable-year2038}
  48 that causes @code{configure} to behave as if @samp{year2038} was used.
  49 This is for packages that have long used @samp{largefile} but have not
  50 gotten around to upgrading their Gnulib module list to include
  51 @samp{year2038} or @samp{year2038-recommended}.
  52 @xref{Large File Support}.
  53
  54 With the @samp{year2038-recommended} module, @command{configure} by
  55 default should work on the following 32-bit platforms (or 32-bit ABIs
  56 in bi-arch systems):
  57
  58 @itemize
  59 @item
  60 Linux kernel 5.1 (2019) and later with glibc 2.34 (2021) and later on
  61 x86, arm, mips (o32 or n32 ABI), powerpc32, sparc32, s390, hppa, m68k, sh, csky, microblaze, nios2,
  62 @item
  63 Linux kernel 5.1 (2019) and later with musl libc 1.2 (2020) and later on x86,
  64 @item
  65 Linux on arc, loong32, ork1, riscv32 and x86_64-x32,
  66 @item
  67 NetBSD 6.0 (2012) and later on x86 and sparc,
  68 @item
  69 OpenBSD 5.5 (2014) and later on x86,
  70 @item
  71 FreeBSD/arm,
  72 @item
  73 Minix 3.3 (2014).
  74 @end itemize
  75
  76 @noindent
  77 Whereas with @samp{year2038-recommended}, @command{configure} should
  78 by default fail on earlier versions of the abovementioned platforms if
  79 a version is listed, and it should also by default fail on all
  80 versions of the following older 32-bit platforms or ABIs:
  81
  82 @itemize
  83 @item
  84 Android on ARMv7 or x86,
  85 @item
  86 Mac OS X 10.6 (2009) and earlier on x86 and powerpc,
  87 @item
  88 GNU/Hurd/x86,
  89 @item
  90 GNU/kFreeBSD/x86,
  91 @item
  92 FreeBSD/x86 (this port demoted to Tier 2 in FreeBSD 13 [2021]
  93 and planned to never have 64-bit @code{time_t}),
  94 @item
  95 MidnightBSD/x86,
  96 @item
  97 AIX/powerpc (to fix, configure with @samp{CC='gcc -maix64' AR='ar -X64'}),
  98 @item
  99 Solaris 11.4 (2018) and earlier on x86 and sparc
 100 (to fix, configure with @samp{CC='gcc -m64'}),
 101 @item
 102 Cygwin 3.3.6 (2022) and earlier on x86,
 103 @item
 104 Haiku/x86.
 105 @end itemize
 106
 107 If you use the @samp{year2038} or @samp{year2038-recommended} modules,
 108 and configure to support timestamps after the year 2038,
 109 your code should not include @samp{<utmp.h>} or @samp{<utmpx.h>}
 110 directly, because these include files do not work with 64-bit timestamps
 111 if the platform's @code{time_t} was traditionally 32 bits.
 112 Your code can instead use the @samp{readutmp} module,
 113 which works around this problem.