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 #ifdef HAVE_CONFIG_H
  21 #include <config.h>
  22 #endif
  23
  24 #include "glib.h"
  25 #include "gprintf.h"
  26 #include "gprintfint.h"
  27
  28 /**
  29  * g_printf:
  30  * @format: the format string. See the printf() documentation.
  31  * @Varargs: the arguments to insert in the output.
  32  *
  33  * An implementation of the standard printf() function which supports
  34  * positional parameters, as specified in the Single Unix Specification.
  35  *
  36  * Returns: the number of characters printed.
  37  **/
  38 gint
  39 g_printf (gchar const *fmt,
  40           ...)
  41 {
  42   va_list args;
  43   gint retval;
  44
  45   va_start (args, fmt);
  46   retval = g_vprintf (fmt, args);
  47   va_end (args);
  48
  49   return retval;
  50 }
  51
  52 /**
  53  * g_fprintf:
  54  * @file: the stream to write to.
  55  * @format: the format string. See the printf() documentation.
  56  * @Varargs: the arguments to insert in the output.
  57  *
  58  * An implementation of the standard fprintf() function which supports
  59  * positional parameters, as specified in the Single Unix Specification.
  60  *
  61  * Returns: the number of characters printed.
  62  **/
  63 gint
  64 g_fprintf (FILE *file,
  65            gchar const *fmt,
  66            ...)
  67 {
  68   va_list args;
  69   gint retval;
  70
  71   va_start (args, fmt);
  72   retval = g_vfprintf (file, fmt, args);
  73   va_end (args);
  74
  75   return retval;
  76 }
  77
  78 /**
  79  * g_sprintf:
  80  * @string: the buffer to hold the output.
  81  * @format: the format string. See the printf() documentation.
  82  * @Varargs: the arguments to insert in the output.
  83  *
  84  * An implementation of the standard sprintf() function which supports
  85  * positional parameters, as specified in the Single Unix Specification.
  86  *
  87  * Returns: the number of characters printed.
  88  **/
  89 gint
  90 g_sprintf (gchar        *str,
  91            gchar const *fmt,
  92            ...)
  93 {
  94   va_list args;
  95   gint retval;
  96
  97   va_start (args, fmt);
  98   retval = g_vsprintf (str, fmt, args);
  99   va_end (args);
 100
 101   return retval;
 102 }
 103
 104 /**
 105  * g_snprintf:
 106  * @string: the buffer to hold the output.
 107  * @n: the maximum number of characters to produce (including the
 108  *     terminating nul character).
 109  * @format: the format string. See the printf() documentation.
 110  * @Varargs: the arguments to insert in the output.
 111  *
 112  * A safer form of the standard sprintf() function. The output is guaranteed
 113  * to not exceed @n characters (including the terminating nul character), so
 114  * it is easy to ensure that a buffer overflow cannot occur.
 115  *
 116  * See also g_strdup_printf().
 117  *
 118  * In versions of GLib prior to 1.2.3, this function may return -1 if the
 119  * output was truncated, and the truncated string may not be nul-terminated.
 120  * In versions prior to 1.3.12, this function returns the length of the output
 121  * string.
 122  *
 123  * The return value of g_snprintf() conforms to the snprintf()
 124  * function as standardized in ISO C99. Note that this is different from
 125  * traditional snprintf(), which returns the length of the output string.
 126  *
 127  * The format string may contain positional parameters, as specified in
 128  * the Single Unix Specification.
 129  *
 130  * Returns: the number of characters which would be produced if the buffer
 131  *     was large enough.
 132  **/
 133 gint
 134 g_snprintf (gchar       *str,
 135             gulong       n,
 136             gchar const *fmt,
 137             ...)
 138 {
 139   va_list args;
 140   gint retval;
 141
 142   va_start (args, fmt);
 143   retval = g_vsnprintf (str, n, fmt, args);
 144   va_end (args);
 145
 146   return retval;
 147 }
 148
 149 /**
 150  * g_vprintf:
 151  * @format: the format string. See the printf() documentation.
 152  * @args: the list of arguments to insert in the output.
 153  *
 154  * An implementation of the standard vprintf() function which supports
 155  * positional parameters, as specified in the Single Unix Specification.
 156  *
 157  * Returns: the number of characters printed.
 158  **/
 159 gint
 160 g_vprintf (gchar const *fmt,
 161            va_list      args)
 162 {
 163   g_return_val_if_fail (fmt != NULL, 0);
 164
 165   return _g_vprintf (fmt, args);
 166 }
 167
 168 /**
 169  * g_vfprintf:
 170  * @file: the stream to write to.
 171  * @format: the format string. See the printf() documentation.
 172  * @args: the list of arguments to insert in the output.
 173  *
 174  * An implementation of the standard fprintf() function which supports
 175  * positional parameters, as specified in the Single Unix Specification.
 176  *
 177  * Returns: the number of characters printed.
 178  **/
 179 gint
 180 g_vfprintf (FILE *file,
 181             gchar const *fmt,
 182             va_list      args)
 183 {
 184   g_return_val_if_fail (fmt != NULL, 0);
 185
 186   return _g_vfprintf (file, fmt, args);
 187 }
 188
 189 /**
 190  * g_vsprintf:
 191  * @string: the buffer to hold the output.
 192  * @format: the format string. See the printf() documentation.
 193  * @args: the list of arguments to insert in the output.
 194  *
 195  * An implementation of the standard vsprintf() function which supports
 196  * positional parameters, as specified in the Single Unix Specification.
 197  *
 198  * Returns: the number of characters printed.
 199  **/
 200 gint
 201 g_vsprintf (gchar        *str,
 202             gchar const *fmt,
 203             va_list      args)
 204 {
 205   g_return_val_if_fail (str != NULL, 0);
 206   g_return_val_if_fail (fmt != NULL, 0);
 207
 208   return _g_vsprintf (str, fmt, args);
 209 }
 210
 211 /**
 212  * g_vsnprintf:
 213  * @string: the buffer to hold the output.
 214  * @n: the maximum number of characters to produce (including the
 215  *     terminating nul character).
 216  * @format: the format string. See the printf() documentation.
 217  * @args: the list of arguments to insert in the output.
 218  *
 219  * A safer form of the standard vsprintf() function. The output is guaranteed
 220  * to not exceed @n characters (including the terminating nul character), so
 221  * it is easy to ensure that a buffer overflow cannot occur.
 222  *
 223  * See also g_strdup_vprintf().
 224  *
 225  * In versions of GLib prior to 1.2.3, this function may return -1 if the
 226  * output was truncated, and the truncated string may not be nul-terminated.
 227  * In versions prior to 1.3.12, this function returns the length of the output
 228  * string.
 229  *
 230  * The return value of g_vsnprintf() conforms to the vsnprintf() function
 231  * as standardized in ISO C99. Note that this is different from traditional
 232  * vsnprintf(), which returns the length of the output string.
 233  *
 234  * The format string may contain positional parameters, as specified in
 235  * the Single Unix Specification.
 236  *
 237  * Returns: the number of characters which would be produced if the buffer
 238  *  was large enough.
 239  */
 240 gint
 241 g_vsnprintf (gchar       *str,
 242              gulong       n,
 243              gchar const *fmt,
 244              va_list      args)
 245 {
 246   g_return_val_if_fail (n == 0 || str != NULL, 0);
 247   g_return_val_if_fail (fmt != NULL, 0);
 248
 249   return _g_vsnprintf (str, n, fmt, args);
 250 }
 251
 252
 253