glib/gerror.c

   1 /* GLIB - Library of useful routines for C programming
   2  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
   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 /*
  21  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
  22  * file for a list of people on the GLib Team.  See the ChangeLog
  23  * files for a list of changes.  These files are distributed with
  24  * GLib at ftp://ftp.gtk.org/pub/gtk/.
  25  */
  26
  27 #include "config.h"
  28
  29 #include "gerror.h"
  30
  31 #include "gstrfuncs.h"
  32 #include "gtestutils.h"
  33
  34 /**
  35  * g_error_new_valist:
  36  * @domain: error domain
  37  * @code: error code
  38  * @format: printf()-style format for error message
  39  * @args: #va_list of parameters for the message format
  40  *
  41  * Creates a new #GError with the given @domain and @code,
  42  * and a message formatted with @format.
  43  *
  44  * Returns: a new #GError
  45  *
  46  * Since: 2.22
  47  */
  48 GError*
  49 g_error_new_valist (GQuark       domain,
  50                     gint         code,
  51                     const gchar *format,
  52                     va_list      args)
  53 {
  54   GError *error;
  55
  56   error = g_slice_new (GError);
  57
  58   error->domain = domain;
  59   error->code = code;
  60   error->message = g_strdup_vprintf (format, args);
  61
  62   return error;
  63 }
  64
  65 /**
  66  * g_error_new:
  67  * @domain: error domain
  68  * @code: error code
  69  * @format: printf()-style format for error message
  70  * @Varargs: parameters for message format
  71  *
  72  * Creates a new #GError with the given @domain and @code,
  73  * and a message formatted with @format.
  74  *
  75  * Return value: a new #GError
  76  */
  77 GError*
  78 g_error_new (GQuark       domain,
  79              gint         code,
  80              const gchar *format,
  81              ...)
  82 {
  83   GError* error;
  84   va_list args;
  85
  86   g_return_val_if_fail (format != NULL, NULL);
  87   g_return_val_if_fail (domain != 0, NULL);
  88
  89   va_start (args, format);
  90   error = g_error_new_valist (domain, code, format, args);
  91   va_end (args);
  92
  93   return error;
  94 }
  95
  96 /**
  97  * g_error_new_literal:
  98  * @domain: error domain
  99  * @code: error code
 100  * @message: error message
 101  *
 102  * Creates a new #GError; unlike g_error_new(), @message is
 103  * not a printf()-style format string. Use this function if
 104  * @message contains text you don't have control over,
 105  * that could include printf() escape sequences.
 106  *
 107  * Return value: a new #GError
 108  **/
 109 GError*
 110 g_error_new_literal (GQuark         domain,
 111                      gint           code,
 112                      const gchar   *message)
 113 {
 114   GError* err;
 115
 116   g_return_val_if_fail (message != NULL, NULL);
 117   g_return_val_if_fail (domain != 0, NULL);
 118
 119   err = g_slice_new (GError);
 120
 121   err->domain = domain;
 122   err->code = code;
 123   err->message = g_strdup (message);
 124
 125   return err;
 126 }
 127
 128 /**
 129  * g_error_free:
 130  * @error: a #GError
 131  *
 132  * Frees a #GError and associated resources.
 133  */
 134 void
 135 g_error_free (GError *error)
 136 {
 137   g_return_if_fail (error != NULL);
 138
 139   g_free (error->message);
 140
 141   g_slice_free (GError, error);
 142 }
 143
 144 /**
 145  * g_error_copy:
 146  * @error: a #GError
 147  *
 148  * Makes a copy of @error.
 149  *
 150  * Return value: a new #GError
 151  */
 152 GError*
 153 g_error_copy (const GError *error)
 154 {
 155   GError *copy;
 156
 157   g_return_val_if_fail (error != NULL, NULL);
 158
 159   copy = g_slice_new (GError);
 160
 161   *copy = *error;
 162
 163   copy->message = g_strdup (error->message);
 164
 165   return copy;
 166 }
 167
 168 /**
 169  * g_error_matches:
 170  * @error: a #GError or %NULL
 171  * @domain: an error domain
 172  * @code: an error code
 173  *
 174  * Returns %TRUE if @error matches @domain and @code, %FALSE
 175  * otherwise. In particular, when @error is %NULL, %FALSE will
 176  * be returned.
 177  *
 178  * Return value: whether @error has @domain and @code
 179  */
 180 gboolean
 181 g_error_matches (const GError *error,
 182                  GQuark        domain,
 183                  gint          code)
 184 {
 185   return error &&
 186     error->domain == domain &&
 187     error->code == code;
 188 }
 189
 190 #define ERROR_OVERWRITTEN_WARNING "GError set over the top of a previous GError or uninitialized memory.\n" \
 191                "This indicates a bug in someone's code. You must ensure an error is NULL before it's set.\n" \
 192                "The overwriting error message was: %s"
 193
 194 /**
 195  * g_set_error:
 196  * @err: a return location for a #GError, or %NULL
 197  * @domain: error domain
 198  * @code: error code
 199  * @format: printf()-style format
 200  * @Varargs: args for @format
 201  *
 202  * Does nothing if @err is %NULL; if @err is non-%NULL, then *@err
 203  * must be %NULL. A new #GError is created and assigned to *@err.
 204  */
 205 void
 206 g_set_error (GError      **err,
 207              GQuark        domain,
 208              gint          code,
 209              const gchar  *format,
 210              ...)
 211 {
 212   GError *new;
 213
 214   va_list args;
 215
 216   if (err == NULL)
 217     return;
 218
 219   va_start (args, format);
 220   new = g_error_new_valist (domain, code, format, args);
 221   va_end (args);
 222
 223   if (*err == NULL)
 224     *err = new;
 225   else
 226     g_warning (ERROR_OVERWRITTEN_WARNING, new->message);
 227 }
 228
 229 /**
 230  * g_set_error_literal:
 231  * @err: a return location for a #GError, or %NULL
 232  * @domain: error domain
 233  * @code: error code
 234  * @message: error message
 235  *
 236  * Does nothing if @err is %NULL; if @err is non-%NULL, then *@err
 237  * must be %NULL. A new #GError is created and assigned to *@err.
 238  * Unlike g_set_error(), @message is not a printf()-style format string.
 239  * Use this function if @message contains text you don't have control over,
 240  * that could include printf() escape sequences.
 241  *
 242  * Since: 2.18
 243  */
 244 void
 245 g_set_error_literal (GError      **err,
 246                      GQuark        domain,
 247                      gint          code,
 248                      const gchar  *message)
 249 {
 250   GError *new;
 251
 252   if (err == NULL)
 253     return;
 254
 255   new = g_error_new_literal (domain, code, message);
 256   if (*err == NULL)
 257     *err = new;
 258   else
 259     g_warning (ERROR_OVERWRITTEN_WARNING, new->message);
 260 }
 261
 262 /**
 263  * g_propagate_error:
 264  * @dest: error return location
 265  * @src: error to move into the return location
 266  *
 267  * If @dest is %NULL, free @src; otherwise, moves @src into *@dest.
 268  * The error variable @dest points to must be %NULL.
 269  */
 270 void
 271 g_propagate_error (GError **dest,
 272                    GError  *src)
 273 {
 274   g_return_if_fail (src != NULL);
 275
 276   if (dest == NULL)
 277     {
 278       if (src)
 279         g_error_free (src);
 280       return;
 281     }
 282   else
 283     {
 284       if (*dest != NULL)
 285         g_warning (ERROR_OVERWRITTEN_WARNING, src->message);
 286       else
 287         *dest = src;
 288     }
 289 }
 290
 291 /**
 292  * g_clear_error:
 293  * @err: a #GError return location
 294  *
 295  * If @err is %NULL, does nothing. If @err is non-%NULL,
 296  * calls g_error_free() on *@err and sets *@err to %NULL.
 297  */
 298 void
 299 g_clear_error (GError **err)
 300 {
 301   if (err && *err)
 302     {
 303       g_error_free (*err);
 304       *err = NULL;
 305     }
 306 }
 307
 308 static void
 309 g_error_add_prefix (gchar       **string,
 310                     const gchar  *format,
 311                     va_list       ap)
 312 {
 313   gchar *oldstring;
 314   gchar *prefix;
 315
 316   prefix = g_strdup_vprintf (format, ap);
 317   oldstring = *string;
 318   *string = g_strconcat (prefix, oldstring, NULL);
 319   g_free (oldstring);
 320   g_free (prefix);
 321 }
 322
 323 /**
 324  * g_prefix_error:
 325  * @err: a return location for a #GError, or %NULL
 326  * @format: printf()-style format string
 327  * @...: arguments to @format
 328  *
 329  * Formats a string according to @format and
 330  * prefix it to an existing error message.  If
 331  * @err is %NULL (ie: no error variable) then do
 332  * nothing.
 333  *
 334  * If *@err is %NULL (ie: an error variable is
 335  * present but there is no error condition) then
 336  * also do nothing.  Whether or not it makes
 337  * sense to take advantage of this feature is up
 338  * to you.
 339  *
 340  * Since: 2.16
 341  */
 342 void
 343 g_prefix_error (GError      **err,
 344                 const gchar  *format,
 345                 ...)
 346 {
 347   if (err && *err)
 348     {
 349       va_list ap;
 350
 351       va_start (ap, format);
 352       g_error_add_prefix (&(*err)->message, format, ap);
 353       va_end (ap);
 354     }
 355 }
 356
 357 /**
 358  * g_propagate_prefixed_error:
 359  * @dest: error return location
 360  * @src: error to move into the return location
 361  * @format: printf()-style format string
 362  * @...: arguments to @format
 363  *
 364  * If @dest is %NULL, free @src; otherwise,
 365  * moves @src into *@dest. *@dest must be %NULL.
 366  * After the move, add a prefix as with
 367  * g_prefix_error().
 368  *
 369  * Since: 2.16
 370  **/
 371 void
 372 g_propagate_prefixed_error (GError      **dest,
 373                             GError       *src,
 374                             const gchar  *format,
 375                             ...)
 376 {
 377   g_propagate_error (dest, src);
 378
 379   if (dest && *dest)
 380     {
 381       va_list ap;
 382
 383       va_start (ap, format);
 384       g_error_add_prefix (&(*dest)->message, format, ap);
 385       va_end (ap);
 386     }
 387 }