exit.h File Reference

#include "common.h"
#include <stdio.h>
#include "bu/defines.h"
#include "bu/hook.h"

Include dependency graph for exit.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
int	bu_backtrace (FILE *fp)
int	bu_backtrace_app (FILE *fp, const char *argv0)
void	bu_bomb_add_hook (bu_hook_t func, void *clientdata)
void	bu_bomb_save_all_hooks (struct bu_hook_list *save_hlp)
void	bu_bomb_delete_all_hooks (void)
void	bu_bomb_restore_hooks (struct bu_hook_list *save_hlp)
NORETURN void	bu_bomb (const char *str)
NORETURN _BU_ATTR_PRINTF23 void	bu_exit (int status, const char *fmt,...)
int	bu_crashreport (const char *filename)
	Generate a crash report file, including a call stack backtrace and other system details. More...
int	bu_crashreport_app (const char *filename, const char *argv0)

Function Documentation

bu_backtrace()

int bu_backtrace

(

FILE *

fp

)

this routine provides a trace of the call stack to the caller, generally called either directly, via a signal handler, or through bu_bomb() with the appropriate bu_debug flags set.

the routine waits indefinitely (in a spin loop) until a signal (SIGINT) is received, at which point execution continues, or until some other signal is received that terminates the application.

the stack backtrace will be written to the provided 'fp' file pointer. it's the caller's responsibility to open and close that pointer if necessary. If 'fp' is NULL, stdout will be used.

returns truthfully if a backtrace was attempted.

bu_backtrace_app()

int bu_backtrace_app	(	FILE *	fp,
		const char *	argv0
	)

A version of bu_backtrace where the caller provides their own full path to their executable for passing to GDB, rather than having libbu attempt to determine that path.

Passing NULL to argv0 makes the behavior identical to that of bu_backtrace.

bu_bomb_add_hook()

void bu_bomb_add_hook	(	bu_hook_t	func,
		void *	clientdata
	)

Adds a hook to the list of bu_bomb hooks. The top (newest) one of these will be called with its associated client data and a string to be processed. Typically, these hook functions will display the output (possibly in an X window) or record it.

NOTE: The hook functions are all non-PARALLEL.

bu_bomb_save_all_hooks()

void bu_bomb_save_all_hooks

(

struct bu_hook_list *

save_hlp

)

bu_bomb_delete_all_hooks()

void bu_bomb_delete_all_hooks

(

void

)

bu_bomb_restore_hooks()

void bu_bomb_restore_hooks

(

struct bu_hook_list *

save_hlp

)

bu_bomb()

NORETURN void bu_bomb

(

const char *

str

)

Abort the running process.

The bu_bomb routine is called on a fatal error, generally where no recovery is possible. Error handlers may, however, be registered with BU_SETJUMP(). This routine intentionally limits calls to other functions and intentionally uses no stack variables. Just in case the application is out of memory, bu_bomb deallocates a small buffer of memory.

Before termination, it optionally performs the following operations in the order listed:

1. Outputs str to standard error
2. Calls any callback functions set in the global bu_bomb_hook_list variable with str passed as an argument.
3. Jumps to any user specified error handler registered with the BU_SETJUMP() facility.
4. Outputs str to the terminal device in case standard error is redirected.
5. Aborts abnormally (via abort) if BU_DEBUG_COREDUMP is defined.
6. Exits with exit(12).

Only produce a core-dump when that debugging bit is set. Note that this function is meant to be a last resort semi-graceful abort.

This routine should never return unless there is a BU_SETJUMP() handler registered.

Referenced by Deserializer::read_int32(), Serializer::write_int32(), and Deserializer::~Deserializer().

bu_exit()

NORETURN _BU_ATTR_PRINTF23 void bu_exit	(	int	status,
		const char *	fmt,
			...
	)

Semi-graceful termination of the application that doesn't cause a stack trace, exiting with the specified status after printing the given message. It's okay for this routine to use the stack, contrary to bu_bomb's behavior since it should be called for expected termination situations.

This routine should generally not be called within a library. Use bu_bomb or (better) cascade the error back up to the application.

This routine should never return.

bu_crashreport()

int bu_crashreport

(

const char *

filename

)

Generate a crash report file, including a call stack backtrace and other system details.

this routine writes out details of the currently running process to the specified file, including an informational header about the execution environment, stack trace details, kernel and hardware information, and current version information.

returns truthfully if the crash report was written.

due to various reasons, this routine is NOT thread-safe.

bu_crashreport_app()

int bu_crashreport_app	(	const char *	filename,
		const char *	argv0
	)

A version of bu_crashreport where the caller provides their own full path to their executable for passing to GDB, rather than having libbu attempt to determine that path.

Passing NULL to argv0 makes the behavior identical to that of bu_crashreport.