Message-Id: <7e9387672bca3e6b336dcf20df5fba5531c33566.1443081807.git.mkletzan@redhat.com>
Date:	Thu, 24 Sep 2015 10:08:46 +0200
From:	Martin Kletzander <mkletzan@...hat.com>
To:	linux-doc@...r.kernel.org
Cc:	Jonathan Corbet <corbet@....net>,
	Andrew Morton <akpm@...ux-foundation.org>,
	Rasmus Villemoes <linux@...musvillemoes.dk>,
	Andy Shevchenko <andriy.shevchenko@...ux.intel.com>,
	Geert Uytterhoeven <geert+renesas@...der.be>,
	Kees Cook <keescook@...omium.org>,
	Tetsuo Handa <penguin-kernel@...ove.sakura.ne.jp>,
	Stephen Boyd <sboyd@...eaurora.org>, Tejun Heo <tj@...nel.org>,
	linux-kernel@...r.kernel.org
Subject: [PATCH v2] lib: Documentation: Synchronize %p formatting documentation

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.

Signed-off-by: Martin Kletzander <mkletzan@...hat.com>
---
 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
-- 
2.5.3

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

Powered by blists - more mailing lists