luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-09-20 01:06:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

gmessages: clarify what log levels are for

Browse Source 
For a long time we've had it as 'common knowledge' that criticals are
for programmer errors and warnings are for external errors, but we've
never documented that.  Do so.

(Modified by Philip Withnall <withnall@endlessm.com> to apply cleanly to
master; rearranged to fit in with current master documentation.)

https://bugzilla.gnome.org/show_bug.cgi?id=741049
This commit is contained in:
Allison Lortie 2014-12-02 18:48:17 -05:00 committed by Philip Withnall
parent 042ab215b2
commit ad3b2f2387
2 changed files with 30 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/reference/glib/running.xml
View File

@ -122,13 +122,15 @@ How to run and debug your GLib application
<varlistentry>
<term>fatal-warnings</term>
<listitem><para>Causes GLib to abort the program at the first call
to g_warning() or g_critical().</para>
to g_warning() or g_critical(). Use of this flag is not
recommended except when debugging.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>fatal-criticals</term>
<listitem><para>Causes GLib to abort the program at the first call
to g_critical().</para>
to g_critical(). This flag can be useful during debugging and
testing.</para>
</listitem>
</varlistentry>
<varlistentry>

32
glib/gmessages.c
View File

@ -387,6 +387,16 @@ myInvalidParameterHandler(const wchar_t *expression,
* preferred for that instead, as it allows calling functions to perform actions
* conditional on the type of error.
*
* Warning messages are intended to be used in the event of unexpected
* external conditions (system misconfiguration, missing files,
* other trusted programs violating protocol, invalid contents in
* trusted files, etc.)
*
* If attempting to deal with programmer errors (for example, incorrect function
* parameters) then you should use %G_LOG_LEVEL_CRITICAL instead.
*
* g_warn_if_reached() and g_warn_if_fail() log at %G_LOG_LEVEL_WARNING.
*
* You can make warnings fatal at runtime by setting the `G_DEBUG`
* environment variable (see
* [Running GLib Applications](glib-running.html)):
@ -413,13 +423,16 @@ myInvalidParameterHandler(const wchar_t *expression,
* into the format string (as with printf())
*
* Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL).
* It's more or less application-defined what constitutes
* a critical vs. a regular warning. You could call
* g_log_set_always_fatal() to make critical warnings exit
* the program, then use g_critical() for fatal errors, for
* example.
*
* You can also make critical warnings fatal at runtime by
* Critical warnings are intended to be used in the event of an error
* that originated in the current process (a programmer error).
* Logging of a critical error is by definition an indication of a bug
* somewhere in the current program (or its libraries).
*
* g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and
* g_return_val_if_reached() log at %G_LOG_LEVEL_CRITICAL.
*
* You can make critical warnings fatal at runtime by
* setting the `G_DEBUG` environment variable (see
* [Running GLib Applications](glib-running.html)):
*
@ -427,6 +440,8 @@ myInvalidParameterHandler(const wchar_t *expression,
* G_DEBUG=fatal-warnings gdb ./my-program
* ]|
*
* You can also use g_log_set_always_fatal().
*
* Any unrelated failures can be skipped over in
* [gdb](https://www.gnu.org/software/gdb/) using the `continue` command.
*
@ -778,6 +793,11 @@ g_log_set_always_fatal (GLogLevelFlags fatal_mask)
* g_log_set_writer_func(). See
* [Using Structured Logging][using-structured-logging].
*
* This function is mostly intended to be used with
* %G_LOG_LEVEL_CRITICAL. You should typically not set
* %G_LOG_LEVEL_WARNING, %G_LOG_LEVEL_MESSAGE, %G_LOG_LEVEL_INFO or
* %G_LOG_LEVEL_DEBUG as fatal except inside of test programs.
*
* Returns: the old fatal mask for the log domain
*/
GLogLevelFlags