From patchwork Tue Oct 18 23:36:25 2011 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 120538 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from theia.denx.de (theia.denx.de [85.214.87.163]) by ozlabs.org (Postfix) with ESMTP id 98B42B71AB for ; Wed, 19 Oct 2011 10:38:56 +1100 (EST) Received: from localhost (localhost [127.0.0.1]) by theia.denx.de (Postfix) with ESMTP id 4916528B24; Wed, 19 Oct 2011 01:38:51 +0200 (CEST) X-Virus-Scanned: Debian amavisd-new at theia.denx.de Received: from theia.denx.de ([127.0.0.1]) by localhost (theia.denx.de [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id hO-lJmc5+Dho; Wed, 19 Oct 2011 01:38:51 +0200 (CEST) Received: from theia.denx.de (localhost [127.0.0.1]) by theia.denx.de (Postfix) with ESMTP id 4775D28C21; Wed, 19 Oct 2011 01:38:36 +0200 (CEST) Received: from localhost (localhost [127.0.0.1]) by theia.denx.de (Postfix) with ESMTP id 020B628BBE for ; Wed, 19 Oct 2011 01:38:24 +0200 (CEST) X-Virus-Scanned: Debian amavisd-new at theia.denx.de Received: from theia.denx.de ([127.0.0.1]) by localhost (theia.denx.de [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id qX7x3POSRbIg for ; Wed, 19 Oct 2011 01:38:22 +0200 (CEST) X-policyd-weight: NOT_IN_SBL_XBL_SPAMHAUS=-1.5 NOT_IN_SPAMCOP=-1.5 NOT_IN_BL_NJABL=-1.5 (only DNSBL check requested) Received: from smtp-out.google.com (smtp-out.google.com [216.239.44.51]) by theia.denx.de (Postfix) with ESMTPS id 0A58128332 for ; Wed, 19 Oct 2011 01:38:20 +0200 (CEST) Received: from wpaz21.hot.corp.google.com (wpaz21.hot.corp.google.com [172.24.198.85]) by smtp-out.google.com with ESMTP id p9INcIWW025671; Tue, 18 Oct 2011 16:38:18 -0700 Received: from sglass.mtv.corp.google.com (sglass.mtv.corp.google.com [172.22.72.144]) by wpaz21.hot.corp.google.com with ESMTP id p9INcG0l014817; Tue, 18 Oct 2011 16:38:16 -0700 Received: by sglass.mtv.corp.google.com (Postfix, from userid 121222) id 5FC2A14116C; Tue, 18 Oct 2011 16:38:16 -0700 (PDT) From: Simon Glass To: U-Boot Mailing List Date: Tue, 18 Oct 2011 16:36:25 -0700 Message-Id: <1318980986-20843-5-git-send-email-sjg@chromium.org> X-Mailer: git-send-email 1.7.3.1 In-Reply-To: <1318980986-20843-1-git-send-email-sjg@chromium.org> References: <1318980986-20843-1-git-send-email-sjg@chromium.org> X-System-Of-Record: true Subject: [U-Boot] [PATCH v4 4/5] vsprintf: Move function documentation into header file X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.9 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: u-boot-bounces@lists.denx.de Errors-To: u-boot-bounces@lists.denx.de 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 --- 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 245cbaf..229afe0 100644 --- a/lib/vsprintf.c +++ b/lib/vsprintf.c @@ -63,32 +63,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; @@ -536,25 +510,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) { @@ -751,21 +706,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; @@ -779,20 +719,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; @@ -805,20 +731,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; @@ -850,18 +762,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;