Updated documentation.

Shaved around 100 bytes off vsprintf.o.  It's now 50 bytes smaller than
the old implementation and provides much more conformant semantics,
including the ability to return the number of characters that would have
been printed to the string had the buffer been big enough.  (iSCSI needs
this functionality).

1 files changed, 22 insertions, 35 deletions

diff --git a/src/include/vsprintf.h b/src/include/vsprintf.h
index 3683fba16..99d6683e1 100644
--- a/src/include/vsprintf.h
+++ b/src/include/vsprintf.h
@@ -3,44 +3,31 @@
 
 /** @file
  *
- * printf and friends.
+ * printf() and friends
  *
- * Etherboot's printf() functions understand the following format
- * specifiers:
+ * Etherboot's printf() functions understand the following subset of
+ * the standard C printf()'s format specifiers:
  *
- *	- Hexadecimal integers
- *		- @c %[#]x	- 4 bytes int (8 hex digits, lower case)
- *		- @c %[#]X	- 4 bytes int (8 hex digits, upper case)
- *		- @c %[#]lx	- 8 bytes long (16 hex digits, lower case)
- *		- @c %[#]lX	- 8 bytes long (16 hex digits, upper case)
- *		- @c %[#]hx	- 2 bytes int (4 hex digits, lower case)
- *		- @c %[#]hX	- 2 bytes int (4 hex digits, upper case)
- *		- @c %[#]hhx	- 1 byte int (2 hex digits, lower case)
- *		- @c %[#]hhX	- 1 byte int (2 hex digits, upper case)
- *		.
- *		If the optional # prefix is specified, the output will
- *		be prefixed with 0x (or 0X).
+ *	- Flag characters
+ *		- '#'		- Alternate form (i.e. "0x" prefix)
+ *		- '0'		- Zero-pad
+ *	- Field widths
+ *	- Length modifiers
+ *		- 'hh'		- Signed / unsigned char
+ *		- 'h'		- Signed / unsigned short
+ *		- 'l'		- Signed / unsigned long
+ *		- 'll'		- Signed / unsigned long long
+ *		- 'z'		- Signed / unsigned size_t
+ *	- Conversion specifiers
+ *		- 'd'		- Signed decimal
+ *		- 'x','X'	- Unsigned hexadecimal
+ *		- 'c'		- Character
+ *		- 's'		- String
+ *		- 'p'		- Pointer
  *
- *	- Other integers
- *		- @c %d		- decimal int
- *	.
- *	Note that any width specification (e.g. the @c 02 in @c %02x)
- *	will be accepted but ignored.
- *
- *	- Strings and characters
- *		- @c %c		- char
- *		- @c %s		- string
- *		- @c %m		- error message text (i.e. strerror(errno))
- *
- *	- Etherboot-specific specifiers
- *		- @c %@		- IP address in ddd.ddd.ddd.ddd notation
- *		- @c %!		- MAC address in xx:xx:xx:xx:xx:xx notation
- *
- *
- * @note Unfortunately, we cannot use <tt> __attribute__ (( format (
- * printf, ... ) )) </tt> to get automatic type checking on arguments,
- * because we use non-standard format characters such as @c %! and
- * @c %@.
+ * Hexadecimal numbers are always zero-padded to the specified field
+ * width (if any); decimal numbers are always space-padded.  Decimal
+ * long longs are not supported.
  *
  */