Commit a0456f9c authored by Philip Withnall's avatar Philip Withnall

gmessages: Clarify documentation about aborting on fatal log levels

Clarify that we actually raise SIGTRAP rather than calling abort(). We
haven’t called abort() since about 2011, when commit
a04efe6a changed the logic to use
SIGTRAP to make it possible to skip past fatal log messages in the
debugger if they weren’t relevant to the problem being debugged.
Signed-off-by: Philip Withnall's avatarPhilip Withnall <withnall@endlessm.com>

GNOME/glib#1448
parent f6703db3
......@@ -47,8 +47,11 @@ void g_on_error_stack_trace (const gchar *prg_name);
*
* Inserts a breakpoint instruction into the code.
*
* On x86 and alpha systems this is implemented as a soft interrupt
* On architectures which support it, this is implemented as a soft interrupt
* and on other architectures it raises a `SIGTRAP` signal.
*
* `SIGTRAP` is used rather than abort() to allow breakpoints to be skipped past
* in a debugger if they are not the desired target of debugging.
*/
#if (defined (__i386__) || defined (__x86_64__)) && defined (__GNUC__) && __GNUC__ >= 2
# define G_BREAKPOINT() G_STMT_START{ __asm__ __volatile__ ("int $03"); }G_STMT_END
......
......@@ -428,8 +428,8 @@ myInvalidParameterHandler(const wchar_t *expression,
* preferred for that instead, as it allows calling functions to perform actions
* conditional on the type of error.
*
* Error messages are always fatal, resulting in a call to
* abort() to terminate the application. This function will
* Error messages are always fatal, resulting in a call to G_BREAKPOINT()
* to terminate the application. This function will
* result in a core dump; don't use it for errors you expect.
* Using this function indicates a bug in your program, i.e.
* an assertion failure.
......@@ -1238,8 +1238,9 @@ static GSList *expected_messages = NULL;
*
* Logs an error or debugging message.
*
* If the log level has been set as fatal, the abort()
* function is called to terminate the program.
* If the log level has been set as fatal, G_BREAKPOINT() is called
* to terminate the program. See the documentation for G_BREAKPOINT() for
* details of the debugging options this provides.
*
* If g_log_default_handler() is used as the log handler function, a new-line
* character will automatically be appended to @..., and need not be entered
......@@ -1389,8 +1390,9 @@ g_logv (const gchar *log_domain,
*
* Logs an error or debugging message.
*
* If the log level has been set as fatal, the abort()
* function is called to terminate the program.
* If the log level has been set as fatal, G_BREAKPOINT() is called
* to terminate the program. See the documentation for G_BREAKPOINT() for
* details of the debugging options this provides.
*
* If g_log_default_handler() is used as the log handler function, a new-line
* character will automatically be appended to @..., and need not be entered
......@@ -1571,7 +1573,7 @@ done_query:
* Log a message with structured data. The message will be passed through to
* the log writer set by the application using g_log_set_writer_func(). If the
* message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will
* be aborted at the end of this function. If the log writer returns
* be aborted by calling G_BREAKPOINT() at the end of this function. If the log writer returns
* %G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried.
* See the documentation for #GLogWriterFunc for information on chaining
* writers.
......@@ -3040,7 +3042,7 @@ escape_string (GString *string)
* allows to install an alternate default log handler.
* This is used if no log handler has been set for the particular log
* domain and log level combination. It outputs the message to stderr
* or stdout and if the log level is fatal it calls abort(). It automatically
* or stdout and if the log level is fatal it calls G_BREAKPOINT(). It automatically
* prints a new-line character after the message, so one does not need to be
* manually included in @message.
*
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment