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