luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-24 14:36:13 +01:00
Code Issues Packages Projects Releases Wiki Activity

Drop the warnings.sgml template

Browse Source
This commit is contained in:
Matthias Clasen 2011-07-19 20:40:28 -04:00
parent d1e5161ab0
commit 4c64e75ec5
6 changed files with 238 additions and 285 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/glib/tmpl/.gitignore vendored
View File

@ -46,3 +46,4 @@ timers.sgml
timezone.sgml
unicode.sgml
version.sgml
warnings.sgml

236
docs/reference/glib/tmpl/warnings.sgml
View File

@ -1,236 +0,0 @@
<!-- ##### SECTION Title ##### -->
Message Output and Debugging Functions
<!-- ##### SECTION Short_Description ##### -->
functions to output messages and help debug applications
<!-- ##### SECTION Long_Description ##### -->
<para>
These functions provide support for outputting messages.
</para>
<para>
The <function>g_return</function> family of macros (g_return_if_fail(),
g_return_val_if_fail(), g_return_if_reached(), g_return_val_if_reached())
should only be used for programming errors, a typical use case is
checking for invalid parameters at the beginning of a public function.
They should not be used if you just mean "if (error) return", they
should only be used if you mean "if (bug in program) return".
The program behavior is generally considered undefined after one of these
checks fails. They are not intended for normal control flow, only to
give a perhaps-helpful warning before giving up.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### FUNCTION g_print ##### -->
<para>
Outputs a formatted message via the print handler.
The default print handler simply outputs the message to stdout.
</para>
<para>
g_print() should not be used from within libraries for debugging messages,
since it may be redirected by applications to special purpose message
windows or even files.
Instead, libraries should use g_log(), or the convenience functions
g_message(), g_warning() and g_error().
</para>
@format: the message format. See the printf() documentation.
@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_set_print_handler ##### -->
<para>
Sets the print handler.
Any messages passed to g_print() will be output via the new handler.
The default handler simply outputs the message to stdout.
By providing your own handler you can redirect the output, to a GTK+
widget or a log file for example.
</para>
@func: the new print handler.
@Returns: the old print handler.
<!-- ##### USER_FUNCTION GPrintFunc ##### -->
<para>
Specifies the type of the print handler functions.
These are called with the complete formatted string to output.
</para>
@string: the message to be output.
<!-- ##### FUNCTION g_printerr ##### -->
<para>
Outputs a formatted message via the error message handler.
The default handler simply outputs the message to stderr.
</para>
<para>
g_printerr() should not be used from within libraries. Instead g_log() should
be used, or the convenience functions g_message(), g_warning() and g_error().
</para>
@format: the message format. See the printf() documentation.
@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_set_printerr_handler ##### -->
<para>
Sets the handler for printing error messages.
Any messages passed to g_printerr() will be output via the new handler.
The default handler simply outputs the message to stderr.
By providing your own handler you can redirect the output, to a GTK+
widget or a log file for example.
</para>
@func: the new error message handler.
@Returns: the old error message handler.
<!-- ##### MACRO g_return_if_fail ##### -->
<para>
Returns from the current function if the expression is not true.
If the expression evaluates to %FALSE, a critical message is logged and
the function returns. This can only be used in functions which do not return
a value.
</para>
@expr: the expression to check.
<!-- ##### MACRO g_return_val_if_fail ##### -->
<para>
Returns from the current function, returning the value @val, if the expression
is not true.
If the expression evaluates to %FALSE, a critical message is logged and
@val is returned.
</para>
@expr: the expression to check.
@val: the value to return from the current function if the expression is not
true.
<!-- ##### MACRO g_return_if_reached ##### -->
<para>
Logs a critical message and returns from the current function.
This can only be used in functions which do not return a value.
</para>
<!-- ##### MACRO g_return_val_if_reached ##### -->
<para>
Logs a critical message and returns @val.
</para>
@val: the value to return from the current function.
<!-- ##### MACRO g_warn_if_fail ##### -->
<para>
Logs a warning if the expression is not true.
</para>
@expr: the expression to check
@Since: 2.16
<!-- ##### MACRO g_warn_if_reached ##### -->
<para>
Logs a critical warning.
</para>
@Since: 2.16
<!-- ##### FUNCTION g_on_error_query ##### -->
<para>
Prompts the user with <computeroutput>[E]xit, [H]alt, show [S]tack trace or [P]roceed</computeroutput>.
This function is intended to be used for debugging use only. The following
example shows how it can be used together with the g_log() functions.
</para>
<informalexample><programlisting>
&num;include &lt;glib.h&gt;
static void
log_handler (const gchar *log_domain,
GLogLevelFlags log_level,
const gchar *message,
gpointer user_data)
{
g_log_default_handler (log_domain, log_level, message, user_data);
g_on_error_query (MY_PROGRAM_NAME);
}
int main (int argc, char *argv[])
{
g_log_set_handler (MY_LOG_DOMAIN,
G_LOG_LEVEL_WARNING |
G_LOG_LEVEL_ERROR |
G_LOG_LEVEL_CRITICAL,
log_handler,
NULL);
/* ... */
</programlisting></informalexample>
<para>
If [E]xit is selected, the application terminates with a call to
<function>_exit(0)</function>.
</para>
<para>
If [H]alt is selected, the application enters an infinite loop.
The infinite loop can only be stopped by killing the application,
or by setting #glib_on_error_halt to %FALSE (possibly via a debugger).
</para>
<para>
If [S]tack trace is selected, g_on_error_stack_trace() is called. This
invokes <command>gdb</command>, which attaches to the current process and shows a stack trace.
The prompt is then shown again.
</para>
<para>
If [P]roceed is selected, the function returns.
</para>
<para>
This function may cause different actions on non-UNIX platforms.
</para>
@prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.
If @prg_name is %NULL, g_get_prgname() is called to get the program name
(which will work correctly if gdk_init() or gtk_init() has been called).
<!-- ##### FUNCTION g_on_error_stack_trace ##### -->
<para>
Invokes <command>gdb</command>, which attaches to the current process and shows a stack trace.
Called by g_on_error_query() when the [S]tack trace option is selected.
</para>
<para>
This function may cause different actions on non-UNIX platforms.
</para>
@prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.
If @prg_name is %NULL, g_get_prgname() is called to get the program name
(which will work correctly if gdk_init() or gtk_init() has been called).
<!-- ##### MACRO G_BREAKPOINT ##### -->
<para>
Inserts a breakpoint instruction into the code. On x86 and alpha systems
this is implemented as a soft interrupt and on other architectures it raises
a %SIGTRAP signal.
</para>

63
glib/gbacktrace.c
View File

@ -91,6 +91,56 @@ static void stack_trace (char **args);
extern volatile gboolean glib_on_error_halt;
volatile gboolean glib_on_error_halt = TRUE;
/**
* g_on_error_query:
* @prg_name: the program name, needed by <command>gdb</command>
* for the [S]tack trace option. If @prg_name is %NULL, g_get_prgname()
* is called to get the program name (which will work correctly if
* gdk_init() or gtk_init() has been called)
*
* Prompts the user with
* <computeroutput>[E]xit, [H]alt, show [S]tack trace or [P]roceed</computeroutput>.
* This function is intended to be used for debugging use only.
* The following example shows how it can be used together with
* the g_log() functions.
*
* |[
* &num;include &lt;glib.h&gt;
*
* static void
* log_handler (const gchar *log_domain,
* GLogLevelFlags log_level,
* const gchar *message,
* gpointer user_data)
* {
* g_log_default_handler (log_domain, log_level, message, user_data);
*
* g_on_error_query (MY_PROGRAM_NAME);
* }
*
* int
* main (int argc, char *argv[])
* {
* g_log_set_handler (MY_LOG_DOMAIN,
* G_LOG_LEVEL_WARNING |
* G_LOG_LEVEL_ERROR |
* G_LOG_LEVEL_CRITICAL,
* log_handler,
* NULL);
* /&ast; ... &ast;/
* ]|
*
* If [E]xit is selected, the application terminates with a call
* to <literal>_exit(0)</literal>.
*
* If [S]tack trace is selected, g_on_error_stack_trace() is called.
* This invokes <command>gdb</command>, which attaches to the current
* process and shows a stack trace. The prompt is then shown again.
*
* If [P]roceed is selected, the function returns.
*
* This function may cause different actions on non-UNIX platforms.
*/
void
g_on_error_query (const gchar *prg_name)
{
@ -160,6 +210,19 @@ g_on_error_query (const gchar *prg_name)
#endif
}
/**
* g_on_error_stack_trace:
* @prg_name: the program name, needed by <command>gdb</command>
* for the [S]tack trace option. If @prg_name is %NULL, g_get_prgname()
* is called to get the program name (which will work correctly if
* gdk_init() or gtk_init() has been called)
*
* Invokes <command>gdb</command>, which attaches to the current
* process and shows a stack trace. Called by g_on_error_query()
* when the [S]tack trace option is selected.
*
* This function may cause different actions on non-UNIX platforms.
*/
void
g_on_error_stack_trace (const gchar *prg_name)
{

18
glib/gbacktrace.h
View File

@ -36,20 +36,16 @@
G_BEGIN_DECLS
/* Fatal error handlers.
* g_on_error_query() will prompt the user to either
* [E]xit, [H]alt, [P]roceed or show [S]tack trace.
* g_on_error_stack_trace() invokes gdb, which attaches to the current
* process and shows a stack trace.
* These function may cause different actions on non-unix platforms.
* The prg_name arg is required by gdb to find the executable, if it is
* passed as NULL, g_on_error_query() will try g_get_prgname().
*/
void g_on_error_query (const gchar *prg_name);
void g_on_error_stack_trace (const gchar *prg_name);
/* Hacker macro to place breakpoints for selected machines.
* Actual use is strongly discouraged of course ;)
/**
* G_BREAKPOINT:
*
* Inserts a breakpoint instruction into the code.
*
* On x86 and alpha systems this is implemented as a soft interrupt
* and on other architectures it raises a %SIGTRAP signal.
*/
#if (defined (__i386__) || defined (__x86_64__)) && defined (__GNUC__) && __GNUC__ >= 2
# define G_BREAKPOINT() G_STMT_START{ __asm__ __volatile__ ("int $03"); }G_STMT_END

124
glib/gmessages.c
View File

@ -28,6 +28,24 @@
* MT safe
*/
/**
* SECTION:warnings
* @Title: Message Output and Debugging Functions
* @Short_description: functions to output messages and help debug applications
*
* These functions provide support for outputting messages.
*
* The <function>g_return</function> family of macros (g_return_if_fail(),
* g_return_val_if_fail(), g_return_if_reached(), g_return_val_if_reached())
* should only be used for programming errors, a typical use case is
* checking for invalid parameters at the beginning of a public function.
* They should not be used if you just mean "if (error) return", they
* should only be used if you mean "if (bug in program) return".
* The program behavior is generally considered undefined after one
* of these checks fails. They are not intended for normal control
* flow, only to give a perhaps-helpful warning before giving up.
*/
#include "config.h"
#include <stdlib.h>
@ -986,37 +1004,65 @@ g_log_default_handler (const gchar *log_domain,
g_free (string);
}
/**
* g_set_print_handler:
* @func: the new print handler
*
* Sets the print handler.
*
* Any messages passed to g_print() will be output via
* the new handler. The default handler simply outputs
* the message to stdout. By providing your own handler
* you can redirect the output, to a GTK+ widget or a
* log file for example.
*
* Returns: the old print handler
*/
GPrintFunc
g_set_print_handler (GPrintFunc func)
{
GPrintFunc old_print_func;
g_mutex_lock (g_messages_lock);
old_print_func = glib_print_func;
glib_print_func = func;
g_mutex_unlock (g_messages_lock);
return old_print_func;
}
/**
* g_print:
* @format: the message format. See the printf() documentation
* @Varargs: the parameters to insert into the format string
*
* Outputs a formatted message via the print handler.
* The default print handler simply outputs the message to stdout.
*
* g_print() should not be used from within libraries for debugging
* messages, since it may be redirected by applications to special
* purpose message windows or even files. Instead, libraries should
* use g_log(), or the convenience functions g_message(), g_warning()
* and g_error().
*/
void
g_print (const gchar *format,
...)
...)
{
va_list args;
gchar *string;
GPrintFunc local_glib_print_func;
g_return_if_fail (format != NULL);
va_start (args, format);
string = g_strdup_vprintf (format, args);
va_end (args);
g_mutex_lock (g_messages_lock);
local_glib_print_func = glib_print_func;
g_mutex_unlock (g_messages_lock);
if (local_glib_print_func)
local_glib_print_func (string);
else
@ -1024,50 +1070,76 @@ g_print (const gchar *format,
const gchar *charset;
if (g_get_charset (&charset))
fputs (string, stdout); /* charset is UTF-8 already */
fputs (string, stdout); /* charset is UTF-8 already */
else
{
gchar *lstring = strdup_convert (string, charset);
{
gchar *lstring = strdup_convert (string, charset);
fputs (lstring, stdout);
g_free (lstring);
}
fputs (lstring, stdout);
g_free (lstring);
}
fflush (stdout);
}
g_free (string);
}
/**
* g_set_printerr_handler:
* @func: the new error message handler
*
* Sets the handler for printing error messages.
*
* Any messages passed to g_printerr() will be output via
* the new handler. The default handler simply outputs the
* message to stderr. By providing your own handler you can
* redirect the output, to a GTK+ widget or a log file for
* example.
*
* Returns: the old error message handler
*/
GPrintFunc
g_set_printerr_handler (GPrintFunc func)
{
GPrintFunc old_printerr_func;
g_mutex_lock (g_messages_lock);
old_printerr_func = glib_printerr_func;
glib_printerr_func = func;
g_mutex_unlock (g_messages_lock);
return old_printerr_func;
}
/**
* g_printerr:
* @format: the message format. See the printf() documentation
* @Varargs: the parameters to insert into the format string
*
* Outputs a formatted message via the error message handler.
* The default handler simply outputs the message to stderr.
*
* g_printerr() should not be used from within libraries.
* Instead g_log() should be used, or the convenience functions
* g_message(), g_warning() and g_error().
*/
void
g_printerr (const gchar *format,
...)
...)
{
va_list args;
gchar *string;
GPrintFunc local_glib_printerr_func;
g_return_if_fail (format != NULL);
va_start (args, format);
string = g_strdup_vprintf (format, args);
va_end (args);
g_mutex_lock (g_messages_lock);
local_glib_printerr_func = glib_printerr_func;
g_mutex_unlock (g_messages_lock);
if (local_glib_printerr_func)
local_glib_printerr_func (string);
else
@ -1075,14 +1147,14 @@ g_printerr (const gchar *format,
const gchar *charset;
if (g_get_charset (&charset))
fputs (string, stderr); /* charset is UTF-8 already */
fputs (string, stderr); /* charset is UTF-8 already */
else
{
gchar *lstring = strdup_convert (string, charset);
{
gchar *lstring = strdup_convert (string, charset);
fputs (lstring, stderr);
g_free (lstring);
}
fputs (lstring, stderr);
g_free (lstring);
}
fflush (stderr);
}
g_free (string);

81
glib/gmessages.h
View File

@ -226,6 +226,13 @@ g_debug (const gchar *format,
}
#endif /* !__GNUC__ */
/**
* GPrintFunc:
* @string: the message to output
*
* Specifies the type of the print handler functions.
* These are called with the complete formatted string to output.
*/
typedef void (*GPrintFunc) (const gchar *string);
void g_print (const gchar *format,
...) G_GNUC_PRINTF (1, 2);
@ -234,23 +241,73 @@ void g_printerr (const gchar *format,
...) G_GNUC_PRINTF (1, 2);
GPrintFunc g_set_printerr_handler (GPrintFunc func);
/* Provide macros for graceful error handling.
* The "return" macros will return from the current function.
* Two different definitions are given for the macros in
* order to support gcc's __PRETTY_FUNCTION__ capability.
/**
* g_warn_if_reached:
*
* Logs a critical warning.
*
* Since: 2.16
*/
#define g_warn_if_reached() \
do { \
g_warn_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, NULL); \
} while (0)
#define g_warn_if_reached() do { g_warn_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, NULL); } while (0)
#define g_warn_if_fail(expr) do { if G_LIKELY (expr) ; else \
g_warn_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, #expr); } while (0)
/**
* g_warn_if_fail:
* @expr: the expression to check
*
* Logs a warning if the expression is not true.
*
* Since: 2.16
*/
#define g_warn_if_fail(expr) \
do { \
if G_LIKELY (expr) ; \
else g_warn_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, #expr); \
} while (0)
#ifdef G_DISABLE_CHECKS
#define g_return_if_fail(expr) G_STMT_START{ (void)0; }G_STMT_END
#define g_return_val_if_fail(expr,val) G_STMT_START{ (void)0; }G_STMT_END
#define g_return_if_reached() G_STMT_START{ return; }G_STMT_END
#define g_return_val_if_reached(val) G_STMT_START{ return (val); }G_STMT_END
/**
* g_return_if_fail:
* @expr: the expression to check
*
* Returns from the current function if the expression
* is not true. If the expression evaluates to %FALSE,
* a critical message is logged and the function returns.
* This can only be used in functions which do not return
* a value.
*/
#define g_return_if_fail(expr) G_STMT_START{ (void)0; }G_STMT_END
/**
* g_return_val_if_fail:
* @expr: the expression to check
* @val: the value to return from the current function
* if the expression is not true
*
* Returns from the current function, returning the value @val,
* if the expression is not true. If the expression evaluates
* to %FALSE, a critical message is logged and @val is returned.
*/
#define g_return_val_if_fail(expr,val) G_STMT_START{ (void)0; }G_STMT_END
/**
* g_return_if_reached:
*
* Logs a critical message and returns from the current function.
* This can only be used in functions which do not return a value.
*/
#define g_return_if_reached() G_STMT_START{ return; }G_STMT_END
/**
* g_return_val_if_reached:
* @val: the value to return from the current function
*
* Logs a critical message and returns @val.
*/
#define g_return_val_if_reached(val) G_STMT_START{ return (val); }G_STMT_END
#else /* !G_DISABLE_CHECKS */