From b1b58be2b290ffa600988e747d29bd8759a61052 Mon Sep 17 00:00:00 2001
From: Bernhard Voelker <mail@bernhard-voelker.de>
Date: Sun, 28 Nov 2021 00:30:57 +0100
Subject: doc: add description for birth time in 'find -printf' format

find(1) supports both searching for and printing of the birth time
of a file since 2007, but the documenation lacked the description
for the latter.

* doc/find.texi (node Time Directives): Add item for %B.
(node Time Formats): Mention that the described formats also apply to
the %B directive.
* find/find.1 (-printf format): Add description of %B.
* NEWS (Documentation Changes): Mention the change.

Fixes https://savannah.gnu.org/bugs/?61327
---
 NEWS          |  2 ++
 doc/find.texi | 16 ++++++++++++++--
 find/find.1   |  8 ++++++++
 3 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/NEWS b/NEWS
index c7d58e67..02c1c55d 100644
--- a/NEWS
+++ b/NEWS
@@ -18,6 +18,8 @@ GNU findutils NEWS - User visible changes.      -*- outline -*- (allout)
 
   The find.1 man page and the Texinfo manual now show environment variables
   in a consistent style. [#59963]
+  Furthermore, both add the description of the -printf format directive '%B',
+  for a file's birth time, and its limitations. [#61327]
 
   The output of 'find --help' now reads better.
 
diff --git a/doc/find.texi b/doc/find.texi
index 8a12898e..5534c71a 100644
--- a/doc/find.texi
+++ b/doc/find.texi
@@ -2109,18 +2109,30 @@ Wed Nov  2 00:42:36 1994
 @item %a
 File's last access time in the format returned by the C @code{ctime}
 function.
+
 @item %A@var{k}
 File's last access time in the format specified by @var{k}
 (@pxref{Time Formats}).
+
+@item %B@var{k}
+File's birth time, i.e., its creation time, in the format specified by @var{k}
+(@pxref{Time Formats}).
+
+This directive produces an empty string if the underlying operating system or
+filesystem does not support birth times.
+
 @item %c
 File's last status change time in the format returned by the C
 @code{ctime} function.
+
 @item %C@var{k}
 File's last status change time in the format specified by @var{k}
 (@pxref{Time Formats}).
+
 @item %t
 File's last modification time in the format returned by the C
 @code{ctime} function.
+
 @item %T@var{k}
 File's last modification time in the format specified by @var{k}
 (@pxref{Time Formats}).
@@ -2154,8 +2166,8 @@ behaviour, because other directives may be added in the future.
 @node Time Formats
 @subsection Time Formats
 
-Below is an incomplete list of formats for the directives @samp{%A}, @samp{%C},
-and @samp{%T}, which print the file's timestamps.
+Below is an incomplete list of formats for the directives @samp{%A}, @samp{%B},
+@samp{%C}, and @samp{%T}, which print the file's timestamps.
 Please refer to the documentation of @code{strftime} for the full list.
 Some of these formats might not be available on all systems, due to differences
 in the implementation of the C @code{strftime} function.
diff --git a/find/find.1 b/find/find.1
index d5233def..5edfeb2c 100644
--- a/find/find.1
+++ b/find/find.1
@@ -1588,6 +1588,14 @@ year (1970...\&)
 The amount of disk space used for this file in 512-byte blocks.  Since disk
 space is allocated in multiples of the filesystem block size this is usually
 greater than %s/512, but it can also be smaller if the file is a sparse file.
+
+.IP %B\fIk\fP
+File's birth time, i.e., its creation time, in the format specified by
+.IR k ,
+which is the same as for %A.
+This directive produces an empty string if the underlying operating system or
+filesystem does not support birth times.
+
 .IP %c
 File's last status change time in the format returned by the C
 .BR ctime (3)
-- 
cgit v1.2.1