Re: [PATCH v2] lib: Documentation: Synchronize %p formatting documentation

[Shevchenko, Andriy]

On Thu, 2015-09-24 at 11:16 +0300, Andy Shevchenko wrote:
> On Thu, 2015-09-24 at 10:08 +0200, Martin Kletzander wrote:
> > Move all pointer-formatting documentation to one place in the code 
> > and
> > one place in the documentation instead of keeping it in three 
> > places
> > with different level of completeness.  Documentation/printk
> > -formats.txt
> > has detailed information about each modifier, docstring above 
> > pointer()
> > has short descriptions of them (as that is the function dealing 
> > with 
> > %p)
> > and docstring above vsprintf() is removed as redundant.  Both 
> > docstrings
> > in the code that were modified are updated with a reminder of 
> > updating
> > the documentation upon any further change.
> > 
> 
> Good for me!
> 
> Reviewed-by: Andy Shevchenko <andriy.shevchenko@xxxxxxxxxxxxxxx>
> 

Ah, sorry, it seems you have to distinguish %pn (which seems now as %p
+ n if I didn't miss anything) and %n.

After addressing this, take my above tag.

> > Signed-off-by: Martin Kletzander <mkletzan@xxxxxxxxxx>
> > ---
> >  Documentation/printk-formats.txt | 27 +++++++++++++++++++++++++
> >  lib/vsprintf.c                   | 43 ++++++++--------------------
> > --
> > ----------
> >  2 files changed, 35 insertions(+), 35 deletions(-)
> > 
> > diff --git a/Documentation/printk-formats.txt 
> > b/Documentation/printk
> > -formats.txt
> > index 2ec6d84f391c..c85e27264a2b 100644
> > --- a/Documentation/printk-formats.txt
> > +++ b/Documentation/printk-formats.txt
> > @@ -119,6 +119,7 @@ Raw buffer as an escaped string:
> >  	If field width is omitted the 1 byte only will be escaped.
> > 
> >  Raw buffer as a hex string:
> > +
> >  	%*ph	00 01 02  ...  3f
> >  	%*phC	00:01:02: ... :3f
> >  	%*phD	00-01-02- ... -3f
> > @@ -234,6 +235,7 @@ UUID/GUID addresses:
> >  	Passed by reference.
> > 
> >  dentry names:
> > +
> >  	%pd{,2,3,4}
> >  	%pD{,2,3,4}
> > 
> > @@ -264,6 +266,8 @@ struct va_format:
> >  		va_list *va;
> >  	};
> > 
> > +	Implements a "recursive vsnprintf".
> > +
> >  	Do not use this feature without some mechanism to verify 
> > the
> >  	correctness of the format string and va_list arguments.
> > 
> > @@ -292,6 +296,29 @@ bitmap and its derivatives such as cpumask and 
> > 
> > nodemask:
> > 
> >  	Passed by reference.
> > 
> > +Network device features:
> > +
> > +	%pNF	0x000000000000c000
> > +
> > +	For printing netdev_features_t.
> > +
> > +	Passed by reference.
> > +
> > +Command from struct task_struct
> > +
> > +	%pT	ls
> > +
> > +	For printing executable name excluding path from struct
> > +	task_struct.
> > +
> > +	Passed by reference.
> > +
> > +Ignored argument:
> > +
> > +	%pn
> > +
> > +	The argument passed will be ignored.
> > +
> >  Thank you for your cooperation and attention.
> > 
> > 
> > diff --git a/lib/vsprintf.c b/lib/vsprintf.c
> > index becd87facf48..9ab68775b840 100644
> > --- a/lib/vsprintf.c
> > +++ b/lib/vsprintf.c
> > @@ -1463,7 +1463,10 @@ int kptr_restrict __read_mostly;
> >   * - 'Cn' For a clock, it prints the name (Common Clock Framework) 
> > 
> > or address
> >   *        (legacy clock framework) of the clock
> >   * - 'Cr' For a clock, it prints the current rate of the clock
> > - * - 'T' task_struct->comm
> > + * - 'T' For task_struct->comm
> > + * - 'n' For ignored argument
> > + *
> > + * ** Please update Documentation/printk-formats.txt when making 
> > changes **
> >   *
> >   * Note: The difference between 'S' and 'F' is that on ia64 and 
> > ppc64
> >   * function pointers are really function descriptors, which 
> > contain 
> > a
> > @@ -1829,41 +1832,11 @@ qualifier:
> >   * @fmt: The format string to use
> >   * @args: Arguments for the format string
> >   *
> > - * This function follows C99 vsnprintf, but has some extensions:
> > - * %pS output the name of a text symbol with offset
> > - * %ps output the name of a text symbol without offset
> > - * %pF output the name of a function pointer with its offset
> > - * %pf output the name of a function pointer without its offset
> > - * %pB output the name of a backtrace symbol with its offset
> > - * %pR output the address range in a struct resource with decoded 
> > flags
> > - * %pr output the address range in a struct resource with raw 
> > flags
> > - * %pb output the bitmap with field width as the number of bits
> > - * %pbl output the bitmap as range list with field width as the 
> > number of bits
> > - * %pM output a 6-byte MAC address with colons
> > - * %pMR output a 6-byte MAC address with colons in reversed order
> > - * %pMF output a 6-byte MAC address with dashes
> > - * %pm output a 6-byte MAC address without colons
> > - * %pmR output a 6-byte MAC address without colons in reversed 
> > order
> > - * %pI4 print an IPv4 address without leading zeros
> > - * %pi4 print an IPv4 address with leading zeros
> > - * %pI6 print an IPv6 address with colons
> > - * %pi6 print an IPv6 address without colons
> > - * %pI6c print an IPv6 address as specified by RFC 5952
> > - * %pIS depending on sa_family of 'struct sockaddr *' print 
> > IPv4/IPv6 address
> > - * %piS depending on sa_family of 'struct sockaddr *' print 
> > IPv4/IPv6 address
> > - * %pU[bBlL] print a UUID/GUID in big or little endian using lower 
> > 
> > or upper
> > - *   case.
> > - * %*pE[achnops] print an escaped buffer
> > - * %*ph[CDN] a variable-length hex string with a separator 
> > (supports 
> > up to 64
> > - *           bytes of the input)
> > - * %pC output the name (Common Clock Framework) or address (legacy 
> > 
> > clock
> > - *     framework) of a clock
> > - * %pCn output the name (Common Clock Framework) or address 
> > (legacy 
> > clock
> > - *      framework) of a clock
> > - * %pCr output the current rate of a clock
> > - * %n is ignored
> > + * This function follows C99 vsnprintf, but has some extensions. 
> >  See
> > + * pointer() or Documentation/printk-formats.txt for all format
> > + * specifiers.
> >   *
> > - * ** Please update Documentation/printk-formats.txt when making 
> > changes **
> > + * ** Please update the documentation when making changes **
> >   *
> >   * The return value is the number of characters which would
> >   * be generated for the given input, excluding the trailing
> 

-- 
Andy Shevchenko <andriy.shevchenko@xxxxxxxxx>
Intel Finland Oy
---------------------------------------------------------------------
Intel Finland Oy
Registered Address: PL 281, 00181 Helsinki 
Business Identity Code: 0357606 - 4 
Domiciled in Helsinki 

This e-mail and any attachments may contain confidential material for
the sole use of the intended recipient(s). Any review or distribution
by others is strictly prohibited. If you are not the intended
recipient, please contact the sender and delete all copies.
N‹§²æ¸›yú²X¬¶ÇvØ–)Þ{.nlj·¥Š{±‘êX§¶›¡Ü}©ž²ÆzÚj:+v‰¨¾«‘êZ+€Êzf£¢·hšˆ§~†­†Ûÿû®w¥¢¸?™¨è&¢)ßf”ùy§m…á«a¶Úÿ0¶ìå