From ac342a8d0c4e50b5983631808ca6b7dc7508e17d Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 8 Jul 2010 19:23:42 -0400 Subject: [PATCH] Expand the g_sprintf docs As requested in bug 576833. --- glib/gprintf.c | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/glib/gprintf.c b/glib/gprintf.c index 7618c2d..06fb6cb 100644 --- a/glib/gprintf.c +++ b/glib/gprintf.c @@ -90,16 +90,21 @@ g_fprintf (FILE *file, /** * g_sprintf: - * @string: A pointer to a memory buffer to contain the resulting string. It - * is up to the caller to ensure that the allocated buffer is large + * @string: A pointer to a memory buffer to contain the resulting string. It + * is up to the caller to ensure that the allocated buffer is large * enough to hold the formatted result - * @format: a standard printf() format string, but notice + * @format: a standard printf() format string, but notice * string precision pitfalls. * @Varargs: the arguments to insert in the output. * - * An implementation of the standard sprintf() function which supports + * An implementation of the standard sprintf() function which supports * positional parameters, as specified in the Single Unix Specification. * + * Note that it is usually better to use g_snprintf(), to avoid the + * risk of buffer overflow. + * + * See also g_strdup_printf(). + * * Returns: the number of bytes printed. * * Since: 2.2 @@ -122,28 +127,28 @@ g_sprintf (gchar *string, /** * g_snprintf: * @string: the buffer to hold the output. - * @n: the maximum number of bytes to produce (including the + * @n: the maximum number of bytes to produce (including the * terminating nul character). - * @format: a standard printf() format string, but notice + * @format: a standard printf() format string, but notice * string precision pitfalls. * @Varargs: the arguments to insert in the output. * * A safer form of the standard sprintf() function. The output is guaranteed - * to not exceed @n characters (including the terminating nul character), so + * to not exceed @n characters (including the terminating nul character), so * it is easy to ensure that a buffer overflow cannot occur. - * + * * See also g_strdup_printf(). * - * In versions of GLib prior to 1.2.3, this function may return -1 if the - * output was truncated, and the truncated string may not be nul-terminated. - * In versions prior to 1.3.12, this function returns the length of the output + * In versions of GLib prior to 1.2.3, this function may return -1 if the + * output was truncated, and the truncated string may not be nul-terminated. + * In versions prior to 1.3.12, this function returns the length of the output * string. * * The return value of g_snprintf() conforms to the snprintf() - * function as standardized in ISO C99. Note that this is different from + * function as standardized in ISO C99. Note that this is different from * traditional snprintf(), which returns the length of the output string. * - * The format string may contain positional parameters, as specified in + * The format string may contain positional parameters, as specified in * the Single Unix Specification. * * Returns: the number of bytes which would be produced if the buffer -- 2.7.4