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