svn commit: r318017 - head/share/man/man4

[Bruce Evans]

On Tue, 9 May 2017, Ian Lepore wrote:

> On Tue, 2017-05-09 at 08:36 +0000, Edward Tomasz Napierala wrote:
>> Author: trasz
>> Date: Tue May  9 08:36:09 2017
>> New Revision: 318017
>> URL: https://svnweb.freebsd.org/changeset/base/318017
>>
>> Log:
>>   Fix device paths for USB serial adapters: the formatting strings
>>   contain "%u", differently from eg uart(4) which uses "%r".
>>   
>
> What is %r and where is it documented?

In the source code.

It was a ddb internal (but supported by -fformat-extensions, except IIRC
for %jr (1)), but is now used by makedev().

For ddb, %r means to use ddb's radix.  All output in ddb must go through
db_printf().  db_printf() calls kvprintf() with ddb's radix as an arg.
Unlike printf(3), kvprintf(9) supports arbitrary radixes and special
formats like signed hex (%y format).  kvprintf() is of course
undocumented.  %y is another ddb internal, like %r except it is not
so useful or used outside of ddb.

make_dev() supports a dumbed down version of %r.  %r for make_dev()
always means radix 32.  This is implemented by calling vnsrprintf(9)
with a hard-coded 32 as an arg since kvprintf() is unsuitable.
vnsrprintf() is of course undocumented.

%r implies %d.  I think the strange-looking %dr works too, but the
normal-looking %rd might not.  db mostly use %...lr, but never a bare
%lr, so use of %r is a bit hard to grep for.  ddb rarely uses the long
long abomination or intmax_t (it assumes that plain long is long enough,
as was correct in C90), and never uses %...jr or %...yr, but I think
these work except for (1).  It might be a bug to hard-code hex or
decimal formats instead of using %r (this is sometimes done for
addresses, when the user's radix is not usually wanted, but is still
too hard-coded).

(1) kvprintf() handles extensions like %r and %y[r] in a general way that
should work if %d or %x[r] works.  But -fformat-extensions doesn't support
%r or %y for intmax_t, so these formats are unusable and unused in practice.

The serial driver man pages are still deficient in not documenting what
'?' and '*' mean.  '?' is not a general wild card, but means specifically
base 32 with 1 digit.  This naming scheme was familar since it was used
by ptys, to go up to 1024 with only 2 digits.  It is still documented
in pty(4) with enough details as 2 digits but not full range
([l-sL-S][0-9a-v]).  I'm not sure if the first digit is restricted by
the implementation or just by convention.

Bruce