Skip to contentSkip to conversation

lib/vsprintf.c: update documentation

PATCH In review Rasmus Villemoes 3 participants 3 messages Oct 2, 2015

Subsystems (3)
lore
Share & tools
lore

Rasmus Villemoes

author reviewer
#0 lore raw

PATCH 1/1 lib/vsprintf.c: update documentation

%n is no longer just ignored; it results in early return from vsnprintf. Also add a request to add test cases for future %p extensions.

---
applies on top of lib-documentation-synchronize-%p-formatting-documentation.patch and its -fix.

 Documentation/printk-formats.txt | 12 ++++++------
 lib/vsprintf.c                   |  7 ++++---
 2 files changed, 10 insertions(+), 9 deletions(-)
Documentation/printk-formats.txt +6 -6
index 9b8d7f746b1a..b784c270105f 100644
@@ -23,6 +23,10 @@ Example:
 
 Reminder: sizeof() result is of type size_t.
 
+The kernel's printf does not support %n. For obvious reasons, floating
+point formats (%e, %f, %g, %a) are also not recognized. Use of any
+unsupported specifier or length qualifier results in a WARN and early
+return from vsnprintf.
 
 Raw pointer value SHOULD be printed with %p. The kernel supports
 the following extended format specifiers for pointer types:
@@ -305,13 +309,9 @@ Command from struct task_struct
 
 	Passed by reference.
 
-Ignored argument:
+If you add other %p extensions, please extend lib/test_printf.c with
+one or more test cases, if at all feasible.
 
-	%n	%n
-
-	The argument passed will be ignored.  In other words, literal "%n" will
-	be in the output and the argument will be considered for next format
-	specifier.
 
 Thank you for your cooperation and attention.
 
lib/vsprintf.c +4 -3
index 5028b044d0e5..488ee489279a 100644
@@ -1448,7 +1448,6 @@ 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
- * - 'n' For ignored argument
  *
  * ** Please update also Documentation/printk-formats.txt when making changes **
  *
@@ -1814,8 +1813,10 @@ qualifier:
  * @fmt: The format string to use
  * @args: Arguments for the format string
  *
- * This function follows C99 vsnprintf, but has some extensions:
- * %n is ignored
+ * This function generally follows C99 vsnprintf, but has some
+ * extensions and a few limitations:
+ *
+ * %n is unsupported
  * %p* is handled by pointer()
  *
  * See pointer() or Documentation/printk-formats.txt for more
Signature · 1 line
2.1.3
reviewer Reviewed-by on v1 1/1
#1 lore raw
Quoted 3 lines · Rasmus Villemoes

%n is no longer just ignored; it results in early return from vsnprintf. Also add a request to add test cases for future %p extensions.

Nice!

Quoted 74 lines

---
applies on top of lib-documentation-synchronize-%p-formatting-documentation.patch and its -fix.

 Documentation/printk-formats.txt | 12 ++++++------
 lib/vsprintf.c                   |  7 ++++---
 2 files changed, 10 insertions(+), 9 deletions(-)
Documentation/printk renamed from Documentation/printk-formats.txt +0 -1
-formats.txt

index 9b8d7f746b1a..b784c270105f 100644

Documentation/printk-formats.txt +1 -0
@@ -23,6 +23,10 @@ Example:
 
 Reminder: sizeof() result is of type size_t.
 
+The kernel's printf does not support %n. For obvious reasons, 

floating

Documentation/printk-formats.txt +2 -0
+point formats (%e, %f, %g, %a) are also not recognized. Use of any
+unsupported specifier or length qualifier results in a WARN and 

early

Documentation/printk-formats.txt +3 -4
+return from vsnprintf.
 
 Raw pointer value SHOULD be printed with %p. The kernel supports
 the following extended format specifiers for pointer types:
@@ -305,13 +309,9 @@ Command from struct task_struct
 
 	Passed by reference.
 
-Ignored argument:
+If you add other %p extensions, please extend lib/test_printf.c with
+one or more test cases, if at all feasible.
 
-	%n	%n
-
-	The argument passed will be ignored.  In other words, 

literal "%n" will

Documentation/printk-formats.txt +0 -1
-	be in the output and the argument will be considered for 

next format

Documentation/printk-formats.txt +0 -1
-	specifier.
 
 Thank you for your cooperation and attention.
lib/vsprintf.c +0 -0
index 5028b044d0e5..488ee489279a 100644
@@ -1448,7 +1448,6 @@ 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
- * - 'n' For ignored argument
*
* ** Please update also Documentation/printk-formats.txt when
making changes **
*

lib/vsprintf.c +4 -2
@@ -1814,8 +1813,10 @@ qualifier:
  * @fmt: The format string to use
  * @args: Arguments for the format string
  *
- * This function follows C99 vsnprintf, but has some extensions:
- * %n is ignored
+ * This function generally follows C99 vsnprintf, but has some
+ * extensions and a few limitations:
+ *
+ * %n is unsupported
  * %p* is handled by pointer()
  *
  * See pointer() or Documentation/printk-formats.txt for more
Signature · 2 lines
Andy Shevchenko <[email protected]>
Intel Finland Oy