glib/gprintf.c

   1 /* GLIB - Library of useful routines for C programming
   2  * Copyright (C) 1995-1997, 2002  Peter Mattis, Red Hat, Inc.
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 #include "config.h"
  19
  20 #include <stdarg.h>
  21 #include <stdlib.h>
  22 #include <stdio.h>
  23
  24 #include "gprintf.h"
  25 #include "gprintfint.h"
  26
  27
  28 /**
  29  * g_printf:
  30  * @format: a standard printf() format string, but notice
  31  *          [string precision pitfalls][string-precision]
  32  * @...: the arguments to insert in the output.
  33  *
  34  * An implementation of the standard printf() function which supports
  35  * positional parameters, as specified in the Single Unix Specification.
  36  *
  37  * As with the standard printf(), this does not automatically append a trailing
  38  * new-line character to the message, so typically @format should end with its
  39  * own new-line character.
  40  *
  41  * Returns: the number of bytes printed.
  42  *
  43  * Since: 2.2
  44  **/
  45 gint
  46 g_printf (gchar const *format,
  47           ...)
  48 {
  49   va_list args;
  50   gint retval;
  51
  52   va_start (args, format);
  53   retval = g_vprintf (format, args);
  54   va_end (args);
  55
  56   return retval;
  57 }
  58
  59 /**
  60  * g_fprintf:
  61  * @file: (not nullable): the stream to write to.
  62  * @format: a standard printf() format string, but notice
  63  *          [string precision pitfalls][string-precision]
  64  * @...: the arguments to insert in the output.
  65  *
  66  * An implementation of the standard fprintf() function which supports
  67  * positional parameters, as specified in the Single Unix Specification.
  68  *
  69  * Returns: the number of bytes printed.
  70  *
  71  * Since: 2.2
  72  **/
  73 gint
  74 g_fprintf (FILE        *file,
  75            gchar const *format,
  76            ...)
  77 {
  78   va_list args;
  79   gint retval;
  80
  81   va_start (args, format);
  82   retval = g_vfprintf (file, format, args);
  83   va_end (args);
  84
  85   return retval;
  86 }
  87
  88 /**
  89  * g_sprintf:
  90  * @string: A pointer to a memory buffer to contain the resulting string. It
  91  *          is up to the caller to ensure that the allocated buffer is large
  92  *          enough to hold the formatted result
  93  * @format: a standard printf() format string, but notice
  94  *          [string precision pitfalls][string-precision]
  95  * @...: the arguments to insert in the output.
  96  *
  97  * An implementation of the standard sprintf() function which supports
  98  * positional parameters, as specified in the Single Unix Specification.
  99  *
 100  * Note that it is usually better to use g_snprintf(), to avoid the
 101  * risk of buffer overflow.
 102  *
 103  * See also g_strdup_printf().
 104  *
 105  * Returns: the number of bytes printed.
 106  *
 107  * Since: 2.2
 108  **/
 109 gint
 110 g_sprintf (gchar       *string,
 111            gchar const *format,
 112            ...)
 113 {
 114   va_list args;
 115   gint retval;
 116
 117   va_start (args, format);
 118   retval = g_vsprintf (string, format, args);
 119   va_end (args);
 120
 121   return retval;
 122 }
 123
 124 /**
 125  * g_snprintf:
 126  * @string: the buffer to hold the output.
 127  * @n: the maximum number of bytes to produce (including the
 128  *     terminating nul character).
 129  * @format: a standard printf() format string, but notice
 130  *          [string precision pitfalls][string-precision]
 131  * @...: the arguments to insert in the output.
 132  *
 133  * A safer form of the standard sprintf() function. The output is guaranteed
 134  * to not exceed @n characters (including the terminating nul character), so
 135  * it is easy to ensure that a buffer overflow cannot occur.
 136  *
 137  * See also g_strdup_printf().
 138  *
 139  * In versions of GLib prior to 1.2.3, this function may return -1 if the
 140  * output was truncated, and the truncated string may not be nul-terminated.
 141  * In versions prior to 1.3.12, this function returns the length of the output
 142  * string.
 143  *
 144  * The return value of g_snprintf() conforms to the snprintf()
 145  * function as standardized in ISO C99. Note that this is different from
 146  * traditional snprintf(), which returns the length of the output string.
 147  *
 148  * The format string may contain positional parameters, as specified in
 149  * the Single Unix Specification.
 150  *
 151  * Returns: the number of bytes which would be produced if the buffer
 152  *     was large enough.
 153  **/
 154 gint
 155 g_snprintf (gchar       *string,
 156             gulong       n,
 157             gchar const *format,
 158             ...)
 159 {
 160   va_list args;
 161   gint retval;
 162
 163   va_start (args, format);
 164   retval = g_vsnprintf (string, n, format, args);
 165   va_end (args);
 166
 167   return retval;
 168 }
 169
 170 /**
 171  * g_vprintf:
 172  * @format: a standard printf() format string, but notice
 173  *          [string precision pitfalls][string-precision]
 174  * @args: the list of arguments to insert in the output.
 175  *
 176  * An implementation of the standard vprintf() function which supports
 177  * positional parameters, as specified in the Single Unix Specification.
 178  *
 179  * Returns: the number of bytes printed.
 180  *
 181  * Since: 2.2
 182  **/
 183 gint
 184 g_vprintf (gchar const *format,
 185            va_list      args)
 186 {
 187   g_return_val_if_fail (format != NULL, -1);
 188
 189   return _g_vprintf (format, args);
 190 }
 191
 192 /**
 193  * g_vfprintf:
 194  * @file: (not nullable): the stream to write to.
 195  * @format: a standard printf() format string, but notice
 196  *          [string precision pitfalls][string-precision]
 197  * @args: the list of arguments to insert in the output.
 198  *
 199  * An implementation of the standard fprintf() function which supports
 200  * positional parameters, as specified in the Single Unix Specification.
 201  *
 202  * Returns: the number of bytes printed.
 203  *
 204  * Since: 2.2
 205  **/
 206 gint
 207 g_vfprintf (FILE        *file,
 208             gchar const *format,
 209             va_list      args)
 210 {
 211   g_return_val_if_fail (format != NULL, -1);
 212
 213   return _g_vfprintf (file, format, args);
 214 }
 215
 216 /**
 217  * g_vsprintf:
 218  * @string: the buffer to hold the output.
 219  * @format: a standard printf() format string, but notice
 220  *          [string precision pitfalls][string-precision]
 221  * @args: the list of arguments to insert in the output.
 222  *
 223  * An implementation of the standard vsprintf() function which supports
 224  * positional parameters, as specified in the Single Unix Specification.
 225  *
 226  * Returns: the number of bytes printed.
 227  *
 228  * Since: 2.2
 229  **/
 230 gint
 231 g_vsprintf (gchar        *string,
 232             gchar const *format,
 233             va_list      args)
 234 {
 235   g_return_val_if_fail (string != NULL, -1);
 236   g_return_val_if_fail (format != NULL, -1);
 237
 238   return _g_vsprintf (string, format, args);
 239 }
 240
 241 /**
 242  * g_vsnprintf:
 243  * @string: the buffer to hold the output.
 244  * @n: the maximum number of bytes to produce (including the
 245  *     terminating nul character).
 246  * @format: a standard printf() format string, but notice
 247  *          string precision pitfalls][string-precision]
 248  * @args: the list of arguments to insert in the output.
 249  *
 250  * A safer form of the standard vsprintf() function. The output is guaranteed
 251  * to not exceed @n characters (including the terminating nul character), so
 252  * it is easy to ensure that a buffer overflow cannot occur.
 253  *
 254  * See also g_strdup_vprintf().
 255  *
 256  * In versions of GLib prior to 1.2.3, this function may return -1 if the
 257  * output was truncated, and the truncated string may not be nul-terminated.
 258  * In versions prior to 1.3.12, this function returns the length of the output
 259  * string.
 260  *
 261  * The return value of g_vsnprintf() conforms to the vsnprintf() function
 262  * as standardized in ISO C99. Note that this is different from traditional
 263  * vsnprintf(), which returns the length of the output string.
 264  *
 265  * The format string may contain positional parameters, as specified in
 266  * the Single Unix Specification.
 267  *
 268  * Returns: the number of bytes which would be produced if the buffer
 269  *  was large enough.
 270  */
 271 gint
 272 g_vsnprintf (gchar       *string,
 273              gulong       n,
 274              gchar const *format,
 275              va_list      args)
 276 {
 277   g_return_val_if_fail (n == 0 || string != NULL, -1);
 278   g_return_val_if_fail (format != NULL, -1);
 279
 280   return _g_vsnprintf (string, n, format, args);
 281 }
 282
 283 /**
 284  * g_vasprintf:
 285  * @string: the return location for the newly-allocated string.
 286  * @format: a standard printf() format string, but notice
 287  *          [string precision pitfalls][string-precision]
 288  * @args: the list of arguments to insert in the output.
 289  *
 290  * An implementation of the GNU vasprintf() function which supports
 291  * positional parameters, as specified in the Single Unix Specification.
 292  * This function is similar to g_vsprintf(), except that it allocates a
 293  * string to hold the output, instead of putting the output in a buffer
 294  * you allocate in advance.
 295  *
 296  * Returns: the number of bytes printed.
 297  *
 298  * Since: 2.4
 299  **/
 300 gint
 301 g_vasprintf (gchar      **string,
 302              gchar const *format,
 303              va_list      args)
 304 {
 305   gint len;
 306   g_return_val_if_fail (string != NULL, -1);
 307
 308 #if !defined(HAVE_GOOD_PRINTF)
 309
 310   len = _g_gnulib_vasprintf (string, format, args);
 311   if (len < 0)
 312     *string = NULL;
 313
 314 #elif defined (HAVE_VASPRINTF)
 315
 316   len = vasprintf (string, format, args);
 317   if (len < 0)
 318     *string = NULL;
 319
 320 #else
 321
 322   {
 323     va_list args2;
 324
 325     G_VA_COPY (args2, args);
 326
 327     *string = g_new (gchar, g_printf_string_upper_bound (format, args));
 328
 329     len = _g_vsprintf (*string, format, args2);
 330     va_end (args2);
 331   }
 332 #endif
 333
 334   return len;
 335 }