Now that this is not in common.h, perhaps it is acceptable to move this documentation into the header file.
Signed-off-by: Simon Glass sjg@chromium.org --- Changes in v3: - Move function documentation into header file
include/vsprintf.h | 125 +++++++++++++++++++++++++++++++++++++++++++++++++++- lib/vsprintf.c | 100 ----------------------------------------- 2 files changed, 124 insertions(+), 101 deletions(-)
diff --git a/include/vsprintf.h b/include/vsprintf.h index 8f26923..d59496f 100644 --- a/include/vsprintf.h +++ b/include/vsprintf.h @@ -25,14 +25,69 @@ #define __VSPRINTF_H
ulong simple_strtoul(const char *cp, char **endp, unsigned int base); + +/** + * strict_strtoul - convert a string to an unsigned long strictly + * @param cp The string to be converted + * @param base The number base to use + * @param res The converted result value + * @return 0 if conversion is successful and *res is set to the converted + * value, otherwise it returns -EINVAL and *res is set to 0. + * + * strict_strtoul converts a string to an unsigned long only if the + * string is really an unsigned long string, any string containing + * any invalid char at the tail will be rejected and -EINVAL is returned, + * only a newline char at the tail is acceptible because people generally + * change a module parameter in the following way: + * + * echo 1024 > /sys/module/e1000/parameters/copybreak + * + * echo will append a newline to the tail. + * + * simple_strtoul just ignores the successive invalid characters and + * return the converted value of prefix part of the string. + * + * Copied this function from Linux 2.6.38 commit ID: + * 521cb40b0c44418a4fd36dc633f575813d59a43d + * + */ int strict_strtoul(const char *cp, unsigned int base, unsigned long *res); unsigned long long simple_strtoull(const char *cp, char **endp, unsigned int base); long simple_strtol(const char *cp, char **endp, unsigned int base); void panic(const char *fmt, ...) __attribute__ ((format (__printf__, 1, 2), noreturn)); + +/** + * Format a string and place it in a buffer + * + * @param buf The buffer to place the result into + * @param fmt The format string to use + * @param ... Arguments for the format string + * + * The function returns the number of characters written + * into @buf. + * + * See the vsprintf() documentation for format string extensions over C99. + */ int sprintf(char *buf, const char *fmt, ...) __attribute__ ((format (__printf__, 2, 3))); + +/** + * Format a string and place it in a buffer (va_list version) + * + * @param buf The buffer to place the result into + * @param size The size of the buffer, including the trailing null space + * @param fmt The format string to use + * @param args Arguments for the format string + * @return the number of characters which have been written into + * the @buf not including the trailing '\0'. If @size is == 0 the function + * returns 0. + * + * If you're not already dealing with a va_list consider using scnprintf(). + * + * See the vsprintf() documentation for format string extensions over C99. + */ int vsprintf(char *buf, const char *fmt, va_list args);
#ifdef CONFIG_SYS_NO_VSNPRINT @@ -46,12 +101,80 @@ int vsprintf(char *buf, const char *fmt, va_list args); #define vsnprintf(buf, size, fmt, args...) vsprintf(buf, fmt, ##args) #define vscnprintf(buf, size, fmt, args...) vsprintf(buf, fmt, ##args) #else +/** + * Format a string and place it in a buffer + * + * @param buf The buffer to place the result into + * @param size The size of the buffer, including the trailing null space + * @param fmt The format string to use + * @param ... Arguments for the format string + * @return the number of characters which would be + * generated for the given input, excluding the trailing null, + * as per ISO C99. If the return is greater than or equal to + * @size, the resulting string is truncated. + * + * See the vsprintf() documentation for format string extensions over C99. + */ int snprintf(char *buf, size_t size, const char *fmt, ...) __attribute__ ((format (__printf__, 3, 4))); + +/** + * Format a string and place it in a buffer + * + * @param buf The buffer to place the result into + * @param size The size of the buffer, including the trailing null space + * @param fmt The format string to use + * @param ... Arguments for the format string + * + * The return value is the number of characters written into @buf not including + * the trailing '\0'. If @size is == 0 the function returns 0. + * + * See the vsprintf() documentation for format string extensions over C99. + */ int scnprintf(char *buf, size_t size, const char *fmt, ...) __attribute__ ((format (__printf__, 3, 4))); + +/** + * Format a string and place it in a buffer (base function) + * + * @param buf The buffer to place the result into + * @param size The size of the buffer, including the trailing null space + * @param fmt The format string to use + * @param args Arguments for the format string + * @return The number characters which would be generated for the given + * input, excluding the trailing '\0', as per ISO C99. Note that fewer + * characters may be written if this number of characters is >= size. + * + * This function follows C99 vsnprintf, but has some extensions: + * %pS output the name of a text symbol + * %pF output the name of a function pointer + * %pR output the address range in a struct resource + * + * The function returns the number of characters which would be + * generated for the given input, excluding the trailing '\0', + * as per ISO C99. + * + * Call this function if you are already dealing with a va_list. + * You probably want snprintf() instead. + */ int vsnprintf(char *buf, size_t size, const char *fmt, va_list args); + +/** + * Format a string and place it in a buffer (va_list version) + * + * @param buf The buffer to place the result into + * @param size The size of the buffer, including the trailing null space + * @param fmt The format string to use + * @param args Arguments for the format string + * @return the number of characters which have been written into + * the @buf not including the trailing '\0'. If @size is == 0 the function + * returns 0. + * + * If you're not already dealing with a va_list consider using scnprintf(). + * + * See the vsprintf() documentation for format string extensions over C99. + */ int vscnprintf(char *buf, size_t size, const char *fmt, va_list args); -#endif +#endif /* CONFIG_SYS_NO_VSNPRINT */
#endif diff --git a/lib/vsprintf.c b/lib/vsprintf.c index e3ee588..95bc093 100644 --- a/lib/vsprintf.c +++ b/lib/vsprintf.c @@ -65,32 +65,6 @@ unsigned long simple_strtoul(const char *cp,char **endp,unsigned int base) return result; }
-/** - * strict_strtoul - convert a string to an unsigned long strictly - * @cp: The string to be converted - * @base: The number base to use - * @res: The converted result value - * - * strict_strtoul converts a string to an unsigned long only if the - * string is really an unsigned long string, any string containing - * any invalid char at the tail will be rejected and -EINVAL is returned, - * only a newline char at the tail is acceptible because people generally - * change a module parameter in the following way: - * - * echo 1024 > /sys/module/e1000/parameters/copybreak - * - * echo will append a newline to the tail. - * - * It returns 0 if conversion is successful and *res is set to the converted - * value, otherwise it returns -EINVAL and *res is set to 0. - * - * simple_strtoul just ignores the successive invalid characters and - * return the converted value of prefix part of the string. - * - * Copied this function from Linux 2.6.38 commit ID: - * 521cb40b0c44418a4fd36dc633f575813d59a43d - * - */ int strict_strtoul(const char *cp, unsigned int base, unsigned long *res) { char *tail; @@ -538,25 +512,6 @@ static char *pointer(const char *fmt, char *buf, char *end, void *ptr, precision, flags); }
-/** - * Format a string and place it in a buffer (base function) - * - * @param buf The buffer to place the result into - * @param size The size of the buffer, including the trailing null space - * @param fmt The format string to use - * @param args Arguments for the format string - * @return The number characters which would be generated for the given - * input, excluding the trailing '\0', as per ISO C99. Note that fewer - * characters may be written if this number of characters is >= size. - * - * This function follows C99 vsnprintf, but has some extensions: - * %pS output the name of a text symbol - * %pF output the name of a function pointer - * %pR output the address range in a struct resource - * - * Call this function if you are already dealing with a va_list. - * You probably want snprintf() instead. - */ static int vsnprintf_internal(char *buf, size_t size, const char *fmt, va_list args) { @@ -753,21 +708,6 @@ int vsnprintf(char *buf, size_t size, const char *fmt, return vsnprintf_internal(buf, size, fmt, args); }
-/** - * Format a string and place it in a buffer (va_list version) - * - * @param buf The buffer to place the result into - * @param size The size of the buffer, including the trailing null space - * @param fmt The format string to use - * @param args Arguments for the format string - * @return the number of characters which have been written into - * the @buf not including the trailing '\0'. If @size is == 0 the function - * returns 0. - * - * If you're not already dealing with a va_list consider using scnprintf(). - * - * See the vsprintf() documentation for format string extensions over C99. - */ int vscnprintf(char *buf, size_t size, const char *fmt, va_list args) { int i; @@ -781,20 +721,6 @@ int vscnprintf(char *buf, size_t size, const char *fmt, va_list args) return 0; }
-/** - * Format a string and place it in a buffer - * - * @param buf The buffer to place the result into - * @param size The size of the buffer, including the trailing null space - * @param fmt The format string to use - * @param ... Arguments for the format string - * @return the number of characters which would be - * generated for the given input, excluding the trailing null, - * as per ISO C99. If the return is greater than or equal to - * @size, the resulting string is truncated. - * - * See the vsprintf() documentation for format string extensions over C99. - */ int snprintf(char *buf, size_t size, const char *fmt, ...) { va_list args; @@ -807,20 +733,6 @@ int snprintf(char *buf, size_t size, const char *fmt, ...) return i; }
-/** - * Format a string and place it in a buffer - * - * @param buf The buffer to place the result into - * @param size The size of the buffer, including the trailing null space - * @param fmt The format string to use - * @param ... Arguments for the format string - * - * The return value is the number of characters written into @buf not including - * the trailing '\0'. If @size is == 0 the function returns 0. - * - * See the vsprintf() documentation for format string extensions over C99. - */ - int scnprintf(char *buf, size_t size, const char *fmt, ...) { va_list args; @@ -852,18 +764,6 @@ int vsprintf(char *buf, const char *fmt, va_list args) return vsnprintf_internal(buf, INT_MAX, fmt, args); }
-/** - * Format a string and place it in a buffer - * - * @param buf The buffer to place the result into - * @param fmt The format string to use - * @param ... Arguments for the format string - * - * The function returns the number of characters written - * into @buf. - * - * See the vsprintf() documentation for format string extensions over C99. - */ int sprintf(char * buf, const char *fmt, ...) { va_list args;