From: Pádraig Brady <P@draigBrady.com>
Date: Tue, 12 Jan 2016 13:12:37 +0000 (+0000)
Subject: doc: mention the '0#' printf flags with stat %a
X-Git-Tag: v8.25~24
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a0c5313d60703c480014bfd810bf8f1cf9903299;p=thirdparty%2Fcoreutils.git

doc: mention the '0#' printf flags with stat %a

* src/stat.c (usage): Mention the '#' and '0' flags are useful with %a.
* doc/coreutils.texi (stat invocation): Likewise.  Also give an example
printing unambiguous octal output.
Reported at http://bugs.debian.org/810539
---

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index f7bdc4274c..eb5159a445 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -11738,7 +11738,7 @@ The valid @var{format} directives for files with @option{--format} and
 @option{--printf} are:
 
 @itemize @bullet
-@item %a - Access rights in octal
+@item %a - Access rights in octal (note @samp{#} and @samp{0} printf flags)
 @item %A - Access rights in human readable form
 @item %b - Number of blocks allocated (see @samp{%B})
 @item %B - The size in bytes of each block reported by @samp{%b}
@@ -11770,6 +11770,11 @@ The valid @var{format} directives for files with @option{--format} and
 @item %Z - Time of last status change as seconds since Epoch
 @end itemize
 
+The @samp{%a} format prints the octal mode, and so it is useful
+to control the zero padding of the output with the @samp{#} and @samp{0}
+printf flags. For example to pad to at least 3 wide while making larger
+numbers unambiguously octal, you can use @samp{%#03a}.
+
 The @samp{%t} and @samp{%T} formats operate on the st_rdev member of
 the stat(2) structure, and are only defined for character and block
 special files.  On some systems or file types, st_rdev may be used to
diff --git a/src/stat.c b/src/stat.c
index 3c6926448b..e11e4318f8 100644
--- a/src/stat.c
+++ b/src/stat.c
@@ -1453,7 +1453,7 @@ Display file or file system status.\n\
       fputs (_("\n\
 The valid format sequences for files (without --file-system):\n\
 \n\
-  %a   access rights in octal\n\
+  %a   access rights in octal (note '#' and '0' printf flags)\n\
   %A   access rights in human readable form\n\
   %b   number of blocks allocated (see %B)\n\
   %B   the size in bytes of each block reported by %b\n\