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, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 #include "config.h"
  21
  22 #ifndef _WIN32
  23 #define _GNU_SOURCE             /* For vasprintf */
  24 #endif
  25
  26 #include <stdarg.h>
  27 #include <stdlib.h>
  28 #include <stdio.h>
  29
  30 #include "glib.h"
  31 #include "gprintf.h"
  32 #include "gprintfint.h"
  33
  34 #include "galias.h"
  35
  36 /**
  37  * g_printf:
  38  * @format: a standard printf() format string, but notice
  39  *          <link linkend="string-precision">string precision pitfalls</link>.
  40  * @Varargs: the arguments to insert in the output.
  41  *
  42  * An implementation of the standard printf() function which supports
  43  * positional parameters, as specified in the Single Unix Specification.
  44  *
  45  * Returns: the number of bytes printed.
  46  *
  47  * Since: 2.2
  48  **/
  49 gint
  50 g_printf (gchar const *format,
  51           ...)
  52 {
  53   va_list args;
  54   gint retval;
  55
  56   va_start (args, format);
  57   retval = g_vprintf (format, args);
  58   va_end (args);
  59
  60   return retval;
  61 }
  62
  63 /**
  64  * g_fprintf:
  65  * @file: the stream to write to.
  66  * @format: a standard printf() format string, but notice
  67  *          <link linkend="string-precision">string precision pitfalls</link>.
  68  * @Varargs: the arguments to insert in the output.
  69  *
  70  * An implementation of the standard fprintf() function which supports
  71  * positional parameters, as specified in the Single Unix Specification.
  72  *
  73  * Returns: the number of bytes printed.
  74  *
  75  * Since: 2.2
  76  **/
  77 gint
  78 g_fprintf (FILE        *file,
  79            gchar const *format,
  80            ...)
  81 {
  82   va_list args;
  83   gint retval;
  84
  85   va_start (args, format);
  86   retval = g_vfprintf (file, format, args);
  87   va_end (args);
  88
  89   return retval;
  90 }
  91
  92 /**
  93  * g_sprintf:
  94  * @string: A pointer to a memory buffer to contain the resulting string. It
  95  *          is up to the caller to ensure that the allocated buffer is large
  96  *          enough to hold the formatted result
  97  * @format: a standard printf() format string, but notice
  98  *          <link linkend="string-precision">string precision pitfalls</link>.
  99  * @Varargs: the arguments to insert in the output.
 100  *
 101  * An implementation of the standard sprintf() function which supports
 102  * positional parameters, as specified in the Single Unix Specification.
 103  *
 104  * Returns: the number of bytes printed.
 105  *
 106  * Since: 2.2
 107  **/
 108 gint
 109 g_sprintf (gchar       *string,
 110            gchar const *format,
 111            ...)
 112 {
 113   va_list args;
 114   gint retval;
 115
 116   va_start (args, format);
 117   retval = g_vsprintf (string, format, args);
 118   va_end (args);
 119
 120   return retval;
 121 }
 122
 123 /**
 124  * g_snprintf:
 125  * @string: the buffer to hold the output.
 126  * @n: the maximum number of bytes to produce (including the
 127  *     terminating nul character).
 128  * @format: a standard printf() format string, but notice
 129  *          <link linkend="string-precision">string precision pitfalls</link>.
 130  * @Varargs: the arguments to insert in the output.
 131  *
 132  * A safer form of the standard sprintf() function. The output is guaranteed
 133  * to not exceed @n characters (including the terminating nul character), so
 134  * it is easy to ensure that a buffer overflow cannot occur.
 135  *
 136  * See also g_strdup_printf().
 137  *
 138  * In versions of GLib prior to 1.2.3, this function may return -1 if the
 139  * output was truncated, and the truncated string may not be nul-terminated.
 140  * In versions prior to 1.3.12, this function returns the length of the output
 141  * string.
 142  *
 143  * The return value of g_snprintf() conforms to the snprintf()
 144  * function as standardized in ISO C99. Note that this is different from
 145  * traditional snprintf(), which returns the length of the output string.
 146  *
 147  * The format string may contain positional parameters, as specified in
 148  * the Single Unix Specification.
 149  *
 150  * Returns: the number of bytes which would be produced if the buffer
 151  *     was large enough.
 152  **/
 153 gint
 154 g_snprintf (gchar       *string,
 155             gulong       n,
 156             gchar const *format,
 157             ...)
 158 {
 159   va_list args;
 160   gint retval;
 161
 162   va_start (args, format);
 163   retval = g_vsnprintf (string, n, format, args);
 164   va_end (args);
 165
 166   return retval;
 167 }
 168
 169 /**
 170  * g_vprintf:
 171  * @format: a standard printf() format string, but notice
 172  *          <link linkend="string-precision">string precision pitfalls</link>.
 173  * @args: the list of arguments to insert in the output.
 174  *
 175  * An implementation of the standard vprintf() function which supports
 176  * positional parameters, as specified in the Single Unix Specification.
 177  *
 178  * Returns: the number of bytes printed.
 179  *
 180  * Since: 2.2
 181  **/
 182 gint
 183 g_vprintf (gchar const *format,
 184            va_list      args)
 185 {
 186   g_return_val_if_fail (format != NULL, -1);
 187
 188   return _g_vprintf (format, args);
 189 }
 190
 191 /**
 192  * g_vfprintf:
 193  * @file: the stream to write to.
 194  * @format: a standard printf() format string, but notice
 195  *          <link linkend="string-precision">string precision pitfalls</link>.
 196  * @args: the list of arguments to insert in the output.
 197  *
 198  * An implementation of the standard fprintf() function which supports
 199  * positional parameters, as specified in the Single Unix Specification.
 200  *
 201  * Returns: the number of bytes printed.
 202  *
 203  * Since: 2.2
 204  **/
 205 gint
 206 g_vfprintf (FILE        *file,
 207             gchar const *format,
 208             va_list      args)
 209 {
 210   g_return_val_if_fail (format != NULL, -1);
 211
 212   return _g_vfprintf (file, format, args);
 213 }
 214
 215 /**
 216  * g_vsprintf:
 217  * @string: the buffer to hold the output.
 218  * @format: a standard printf() format string, but notice
 219  *          <link linkend="string-precision">string precision pitfalls</link>.
 220  * @args: the list of arguments to insert in the output.
 221  *
 222  * An implementation of the standard vsprintf() function which supports
 223  * positional parameters, as specified in the Single Unix Specification.
 224  *
 225  * Returns: the number of bytes printed.
 226  *
 227  * Since: 2.2
 228  **/
 229 gint
 230 g_vsprintf (gchar        *string,
 231             gchar const *format,
 232             va_list      args)
 233 {
 234   g_return_val_if_fail (string != NULL, -1);
 235   g_return_val_if_fail (format != NULL, -1);
 236
 237   return _g_vsprintf (string, format, args);
 238 }
 239
 240 /**
 241  * g_vsnprintf:
 242  * @string: the buffer to hold the output.
 243  * @n: the maximum number of bytes to produce (including the
 244  *     terminating nul character).
 245  * @format: a standard printf() format string, but notice
 246  *          <link linkend="string-precision">string precision pitfalls</link>.
 247  * @args: the list of arguments to insert in the output.
 248  *
 249  * A safer form of the standard vsprintf() function. The output is guaranteed
 250  * to not exceed @n characters (including the terminating nul character), so
 251  * it is easy to ensure that a buffer overflow cannot occur.
 252  *
 253  * See also g_strdup_vprintf().
 254  *
 255  * In versions of GLib prior to 1.2.3, this function may return -1 if the
 256  * output was truncated, and the truncated string may not be nul-terminated.
 257  * In versions prior to 1.3.12, this function returns the length of the output
 258  * string.
 259  *
 260  * The return value of g_vsnprintf() conforms to the vsnprintf() function
 261  * as standardized in ISO C99. Note that this is different from traditional
 262  * vsnprintf(), which returns the length of the output string.
 263  *
 264  * The format string may contain positional parameters, as specified in
 265  * the Single Unix Specification.
 266  *
 267  * Returns: the number of bytes which would be produced if the buffer
 268  *  was large enough.
 269  */
 270 gint
 271 g_vsnprintf (gchar       *string,
 272              gulong       n,
 273              gchar const *format,
 274              va_list      args)
 275 {
 276   g_return_val_if_fail (n == 0 || string != NULL, -1);
 277   g_return_val_if_fail (format != NULL, -1);
 278
 279   return _g_vsnprintf (string, n, format, args);
 280 }
 281
 282 /**
 283  * g_vasprintf:
 284  * @string: the return location for the newly-allocated string.
 285  * @format: a standard printf() format string, but notice
 286  *          <link linkend="string-precision">string precision pitfalls</link>.
 287  * @args: the list of arguments to insert in the output.
 288  *
 289  * An implementation of the GNU vasprintf() function which supports
 290  * positional parameters, as specified in the Single Unix Specification.
 291  * This function is similar to g_vsprintf(), except that it allocates a
 292  * string to hold the output, instead of putting the output in a buffer
 293  * you allocate in advance.
 294  *
 295  * Returns: the number of bytes printed.
 296  *
 297  * Since: 2.4
 298  **/
 299 gint
 300 g_vasprintf (gchar      **string,
 301              gchar const *format,
 302              va_list      args)
 303 {
 304   gint len;
 305   g_return_val_if_fail (string != NULL, -1);
 306
 307 #if !defined(HAVE_GOOD_PRINTF)
 308
 309   len = _g_gnulib_vasprintf (string, format, args);
 310   if (len < 0)
 311     *string = NULL;
 312
 313 #elif defined (HAVE_VASPRINTF)
 314
 315   len = vasprintf (string, format, args);
 316   if (len < 0)
 317     *string = NULL;
 318   else if (!g_mem_is_system_malloc ())
 319     {
 320       /* vasprintf returns malloc-allocated memory */
 321       gchar *string1 = g_strndup (*string, len);
 322       free (*string);
 323       *string = string1;
 324     }
 325
 326 #else
 327
 328   {
 329     va_list args2;
 330
 331     G_VA_COPY (args2, args);
 332
 333     *string = g_new (gchar, g_printf_string_upper_bound (format, args));
 334
 335     len = _g_vsprintf (*string, format, args2);
 336     va_end (args2);
 337   }
 338 #endif
 339
 340   return len;
 341 }
 342
 343 #define __G_PRINTF_C__
 344 #include "galiasdef.c"