find needs doco (and code?) fix re format strings

[Chris Chittleborough]

Dan Jacobson recently pointed out a documentation problem regarding 
find's format strings.  Here is a fuller explanation of the situation as 
of find 4.1.20.  (I sent this to bug-findutils back in August but got no 
response; maybe sending it during the summer vacation period for you 
Northern Hemisphere dwellers wasn't such a great move ...)

I have written a patch which adds a new format code (%M -> ls-style 
10-character mode string) and a new time format (%T+ -> 
yyyy-mm-dd+HH:MM:SS) to find.  Thanks to the really clean internal 
structure of the source, coding this enhancement was quite easy.  But I 
have run into some problems while documenting the new format features.

In find.texi, the "Print File Information" node says about "-printf" that
   Field widths and precisions can be specified as with the
   `printf' C function
which is true but quite incomplete.  On the other hand, the "Format
Directives" node says that
   [u]nlike the C `printf' function, ["-printf" and
   "-fprintf"] do not support field width specifiers
which is quite untrue.

Here's the full truth as of version 4.1.20. Find accepts the syntax
   '%' {'-' | '0' | '#' | '+' | ' ' } Number [ '.' Number ] Directive
for format conversions, but only honors the '0', '#', '+' and ' ' flags
with two directives, %d (depth) and %m (mode).  You might expect numeric
directives like %s, %n and %i to behave like %d, but they don't.  In a
closely-related development, with %d and %m a precision specification
(eg., the ".4" in "%.4m") specifies the minimum number of digits to be
output, but with all other directives (even %s!) it specifies the
maximum output length.  (The reason for this is that %d and %m are
implemented using fprintf's numeric conversions -- %d (decimal) and %o
(octal) respectively -- while all the other directives use fprintf's %s
(string) conversion.)

There is another complication with %m.  You might expect that it would
always output 3 octal digits or 4 iff the setuid, setgid or sticky bits
are set.  However, a file with mode 044 (unlikely, but I've done ... er,
that is, *seen* ... stranger things), causes "%m" to output "44", not
"044".

All this is confusing and hard to document.  Perhaps %d and %o should be
brought into line with the other directives?  But this might break
existing scripts.  Does the fact that these details were not documented
make it acceptable to change them?  Perhaps more importantly, what does
POSIX say about this stuff?  (Having never even seen any POSIX
specification, I have no idea.)

If the people on this list can reach some sort of consensus, I'm willing
to try to produce a patch.