Skip to contentSkip to conversation

kbuild: doc: describe the error caused by pre-epoch timestamp

PATCH In review Gang Yan 2 participants 2 messages Oct 16, 2025

Subsystems (2)
lore
Share & tools
lore

Gang Yan

author
#0 lore raw

PATCH 1/1 kbuild: doc: describe the error caused by pre-epoch timestamp

From: Gang Yan <[email protected]>

This patch documents the compilation error that occurs with a pre-epoch KBUILD_BUILD_TIMESTAMP. By providing an example command and the resulting error, it helps users identify and avoid this issue.

---
 Documentation/kbuild/kbuild.rst | 9 +++++++++
 1 file changed, 9 insertions(+)
Documentation/kbuild/kbuild.rst +9 -0
index 3388a10f2dcc..1ffc782d2061 100644
@@ -331,6 +331,15 @@ UTS_VERSION definition (uname -v in the running kernel). The value has to
 be a string that can be passed to date -d. The default value
 is the output of the date command at one point during build.
 
+However, when the date command retrieves a timestamp that falls into
+pre-epoch times (i.e., dates before the Unix epoch, January 1, 1970),
+the kernel will raise an error during the compilation of initramfs. E.g.::
+
+    $ KBUILD_BUILD_TIMESTAMP="Sat Jan 1 00:00:00 UTC 0000" make
+    ...
+    ERROR: Timestamp out of range for cpio format'
+    ...
+
 KBUILD_BUILD_USER, KBUILD_BUILD_HOST
 ------------------------------------
 These two variables allow to override the user@host string displayed during
Signature · 1 line
2.43.0
Reviewed-by on v1 1/1
#1 lore raw
Quoted 5 lines · Gang Yan

From: Gang Yan <[email protected]>

This patch documents the compilation error that occurs with a pre-epoch KBUILD_BUILD_TIMESTAMP. By providing an example command and the resulting error, it helps users identify and avoid this issue.

Adding the example is helpful, but my preference would to use a valid one (which can be copied).

Documentation/kbuild/kbuild.rst UTS_VERSION definition (uname -v in the running kernel). The value has to · line 331

Quoted 12 lines
---
 Documentation/kbuild/kbuild.rst | 9 +++++++++
 1 file changed, 9 insertions(+)
Documentation/kbuild/kbuild.rst +0 -0
index 3388a10f2dcc..1ffc782d2061 100644
@@ -331,6 +331,15 @@ UTS_VERSION definition (uname -v in the running kernel). The value has to
 be a string that can be passed to date -d. E.g.:

<valid example here>

Documentation/kbuild/kbuild.rst UTS_VERSION definition (uname -v in the running kernel). The value has to · line 336

Quoted 6 lines

The default value
is the output of the date command at one point during build.

Documentation/kbuild/kbuild.rst +3 -0
+However, when the date command retrieves a timestamp that falls into
+pre-epoch times (i.e., dates before the Unix epoch, January 1, 1970),
+the kernel will raise an error during the compilation of initramfs. E.g.::

This assumes CONFIG_BLK_DEV_INITRD=y, and doesn't cover why initramfs uses the date in the first place. How about reworking it to something like the following:

If provided, this timestamp will also be used for mtime fields within any initramfs archive. Initramfs mtimes are 32-bit, so dates before the 1970 Unix epoch, or after 2106-02-07 06:28:15 UTC will fail.

With that, feel free to add:

Thanks, David