1 /* GLIB - Library of useful routines for C programming

     2  * Copyright (C) 1995-1997, 2002  Peter Mattis, Red Hat, Inc.

     3  * Portions copyright (c) 2006 Nokia Corporation.  All rights reserved.

     4  *

     5  * This library is free software; you can redistribute it and/or

     6  * modify it under the terms of the GNU Lesser General Public

     7  * License as published by the Free Software Foundation; either

     8  * version 2 of the License, or (at your option) any later version.

     9  *

    10  * This library is distributed in the hope that it will be useful,

    11  * but WITHOUT ANY WARRANTY; without even the implied warranty of

    12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

    13  * Lesser General Public License for more details.

    14  *

    15  * You should have received a copy of the GNU Lesser General Public

    16  * License along with this library; if not, write to the

    17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,

    18  * Boston, MA 02111-1307, USA.

    19  */

    20 

    21 #ifdef HAVE_CONFIG_H

    22 #include <config.h>

    23 #endif

    24 

    25 #define _GNU_SOURCE		/* For vasprintf */

    26 

    27 #include <stdarg.h>

    28 #include <stdlib.h>

    29 #include <stdio.h>

    30 

    31 #include "glib.h"

    32 #include "gprintf.h"

    33 #include "gprintfint.h"

    34 

    35 #include "galias.h"

    36 

    37 /**

    38  * g_printf:

    39  * @format: a standard printf() format string, but notice 

    40  *          <link linkend="string-precision">string precision pitfalls</link>.

    41  * @Varargs: the arguments to insert in the output.

    42  *

    43  * An implementation of the standard printf() function which supports 

    44  * positional parameters, as specified in the Single Unix Specification.

    45  *

    46  * Returns: the number of characters printed.

    47  *

    48  * Since: 2.2

    49  **/

    50 EXPORT_C 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: the stream to write to.

    67  * @format: a standard printf() format string, but notice 

    68  *          <link linkend="string-precision">string precision pitfalls</link>.

    69  * @Varargs: 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  * Returns: the number of characters printed.

    75  *

    76  * Since: 2.2

    77  **/

    78 EXPORT_C gint

    79 g_fprintf (FILE        *file, 

    80            gchar const *format,

    81 	   ...)

    82 {

    83   va_list args;

    84   gint retval;

    85 

    86   va_start (args, format);

    87   retval = g_vfprintf (file, format, args);

    88   va_end (args);

    89   

    90   return retval;

    91 }

    92 

    93 /**

    94  * g_sprintf:

    95  * @string: the buffer to hold the output.

    96  * @format: a standard printf() format string, but notice 

    97  *          <link linkend="string-precision">string precision pitfalls</link>.

    98  * @Varargs: the arguments to insert in the output.

    99  *

   100  * An implementation of the standard sprintf() function which supports 

   101  * positional parameters, as specified in the Single Unix Specification.

   102  *

   103  * Returns: the number of characters printed.

   104  *

   105  * Since: 2.2

   106  **/

   107 EXPORT_C gint

   108 g_sprintf (gchar       *string,

   109 	   gchar const *format,

   110 	   ...)

   111 {

   112   va_list args;

   113   gint retval;

   114 

   115   va_start (args, format);

   116   retval = g_vsprintf (string, format, args);

   117   va_end (args);

   118   

   119   return retval;

   120 }

   121 

   122 /**

   123  * g_snprintf:

   124  * @string: the buffer to hold the output.

   125  * @n: the maximum number of characters to produce (including the 

   126  *     terminating nul character).

   127  * @format: a standard printf() format string, but notice 

   128  *          <link linkend="string-precision">string precision pitfalls</link>.

   129  * @Varargs: the arguments to insert in the output.

   130  *

   131  * A safer form of the standard sprintf() function. The output is guaranteed

   132  * to not exceed @n characters (including the terminating nul character), so 

   133  * it is easy to ensure that a buffer overflow cannot occur.

   134  * 

   135  * See also g_strdup_printf().

   136  *

   137  * In versions of GLib prior to 1.2.3, this function may return -1 if the 

   138  * output was truncated, and the truncated string may not be nul-terminated. 

   139  * In versions prior to 1.3.12, this function returns the length of the output 

   140  * string.

   141  *

   142  * The return value of g_snprintf() conforms to the snprintf()

   143  * function as standardized in ISO C99. Note that this is different from 

   144  * traditional snprintf(), which returns the length of the output string.

   145  *

   146  * The format string may contain positional parameters, as specified in 

   147  * the Single Unix Specification.

   148  *

   149  * Returns: the number of characters which would be produced if the buffer 

   150  *     was large enough.

   151  **/

   152 EXPORT_C gint

   153 g_snprintf (gchar	*string,

   154 	    gulong	 n,

   155 	    gchar const *format,

   156 	    ...)

   157 {

   158   va_list args;

   159   gint retval;

   160 

   161   va_start (args, format);

   162   retval = g_vsnprintf (string, n, format, args);

   163   va_end (args);

   164   

   165   return retval;

   166 }

   167 

   168 /**

   169  * g_vprintf:

   170  * @format: a standard printf() format string, but notice 

   171  *          <link linkend="string-precision">string precision pitfalls</link>.

   172  * @args: the list of arguments to insert in the output.

   173  *

   174  * An implementation of the standard vprintf() function which supports 

   175  * positional parameters, as specified in the Single Unix Specification.

   176  *

   177  * Returns: the number of characters printed.

   178  *

   179  * Since: 2.2

   180  **/

   181 EXPORT_C gint

   182 g_vprintf (gchar const *format,

   183 	   va_list      args)

   184 {

   185   g_return_val_if_fail (format != NULL, -1);

   186 

   187   return _g_vprintf (format, args);

   188 }

   189 

   190 /**

   191  * g_vfprintf:

   192  * @file: the stream to write to.

   193  * @format: a standard printf() format string, but notice 

   194  *          <link linkend="string-precision">string precision pitfalls</link>.

   195  * @args: the list of arguments to insert in the output.

   196  *

   197  * An implementation of the standard fprintf() function which supports 

   198  * positional parameters, as specified in the Single Unix Specification.

   199  *

   200  * Returns: the number of characters printed.

   201  *

   202  * Since: 2.2

   203  **/

   204 EXPORT_C gint

   205 g_vfprintf (FILE        *file,

   206             gchar const *format,

   207 	    va_list      args)

   208 {

   209   g_return_val_if_fail (format != NULL, -1);

   210 

   211   return _g_vfprintf (file, format, args);

   212 }

   213 

   214 /**

   215  * g_vsprintf:

   216  * @string: the buffer to hold the output.

   217  * @format: a standard printf() format string, but notice 

   218  *          <link linkend="string-precision">string precision pitfalls</link>.

   219  * @args: the list of arguments to insert in the output.

   220  *

   221  * An implementation of the standard vsprintf() function which supports 

   222  * positional parameters, as specified in the Single Unix Specification.

   223  *

   224  * Returns: the number of characters printed.

   225  *

   226  * Since: 2.2

   227  **/

   228 EXPORT_C gint

   229 g_vsprintf (gchar	 *string,

   230 	    gchar const *format,

   231 	    va_list      args)

   232 {

   233   g_return_val_if_fail (string != NULL, -1);

   234   g_return_val_if_fail (format != NULL, -1);

   235 

   236   return _g_vsprintf (string, format, args);

   237 }

   238 

   239 /** 

   240  * g_vsnprintf:

   241  * @string: the buffer to hold the output.

   242  * @n: the maximum number of characters to produce (including the 

   243  *     terminating nul character).

   244  * @format: a standard printf() format string, but notice 

   245  *          <link linkend="string-precision">string precision pitfalls</link>.

   246  * @args: the list of arguments to insert in the output.

   247  *

   248  * A safer form of the standard vsprintf() function. The output is guaranteed

   249  * to not exceed @n characters (including the terminating nul character), so 

   250  * it is easy to ensure that a buffer overflow cannot occur.

   251  *

   252  * See also g_strdup_vprintf().

   253  *

   254  * In versions of GLib prior to 1.2.3, this function may return -1 if the 

   255  * output was truncated, and the truncated string may not be nul-terminated.

   256  * In versions prior to 1.3.12, this function returns the length of the output 

   257  * string.

   258  *

   259  * The return value of g_vsnprintf() conforms to the vsnprintf() function 

   260  * as standardized in ISO C99. Note that this is different from traditional 

   261  * vsnprintf(), which returns the length of the output string.

   262  *

   263  * The format string may contain positional parameters, as specified in 

   264  * the Single Unix Specification.

   265  *

   266  * Returns: the number of characters which would be produced if the buffer 

   267  *  was large enough.

   268  */

   269 EXPORT_C gint

   270 g_vsnprintf (gchar	 *string,

   271 	     gulong	  n,

   272 	     gchar const *format,

   273 	     va_list      args)

   274 {

   275   g_return_val_if_fail (n == 0 || string != NULL, -1);

   276   g_return_val_if_fail (format != NULL, -1);

   277 

   278   return _g_vsnprintf (string, n, format, args);

   279 }

   280 

   281 /**

   282  * g_vasprintf:

   283  * @string: the return location for the newly-allocated string.

   284  * @format: a standard printf() format string, but notice

   285  *          <link linkend="string-precision">string precision pitfalls</link>.

   286  * @args: the list of arguments to insert in the output.

   287  *

   288  * An implementation of the GNU vasprintf() function which supports 

   289  * positional parameters, as specified in the Single Unix Specification.

   290  * This function is similar to g_vsprintf(), except that it allocates a 

   291  * string to hold the output, instead of putting the output in a buffer 

   292  * you allocate in advance.

   293  *

   294  * Returns: the number of characters printed.

   295  *

   296  * Since: 2.4

   297  **/

   298 EXPORT_C gint 

   299 g_vasprintf (gchar      **string,

   300 	     gchar const *format,

   301 	     va_list      args)

   302 {

   303   gint len;

   304   g_return_val_if_fail (string != NULL, -1);

   305 

   306 #if !defined(HAVE_GOOD_PRINTF)

   307 

   308   len = _g_gnulib_vasprintf (string, format, args);

   309   if (len < 0)

   310     *string = NULL;

   311 

   312 #elif defined (HAVE_VASPRINTF)

   313 

   314   len = vasprintf (string, format, args);

   315   if (len < 0)

   316     *string = NULL;

   317   else if (!g_mem_is_system_malloc ()) 

   318     {

   319       /* vasprintf returns malloc-allocated memory */

   320       gchar *string1 = g_strndup (*string, len);

   321       free (*string);

   322       *string = string1;

   323     }

   324 

   325 #else

   326 

   327   {

   328     va_list args2;

   329 

   330     G_VA_COPY (args2, args);

   331     *string = g_new (gchar, g_printf_string_upper_bound (format, args));

   332 

   333     len = _g_vsprintf (*string, format, args2);

   334     va_end (args2);

   335   }

   336 #endif

   337 

   338   return len;

   339 }

   340 

   341 #define __G_PRINTF_C__

   342 #include "galiasdef.c"