This subsystem provides a convenient message logging facility. You must initialize this subsystem prior to using any other part of libacfutils which may emit log messages (which is nearly all of them). Call log_init() with a suitable logging callback in the first argument. On shutdown, call log_fini() to make sure all memory resources of the logging system are freed. To log a message, use the logMsg() macro.
- See also
- log_init()
-
log_fini()
-
logMsg()
Definition in file log.h.
| void log_backtrace |
( |
int |
skip_frames | ) |
|
\func void log_backtrace(int skip_frames) Logs a backtrace of the current stack to the logging system. This is typically called from an assertion failure handler to try and gather debugging information, before the app is terminated.
This function uses OS-specific facilities to try and determine the function names and offsets of each stack frame.
- On macOS and Linux, this facility utilizes the
backtrace() and backtrace_symbols() functions from the platforms' respective C libraries. These attempt to use any embedded symbol information inside of the binary to determine function names and offsets.
- On Windows, binaries unfortunately almost never ship with symbol information for internal symbols not exposed via
dllexport. Therefore, to support getting some semblance of useful information, libacfutils utilizes a custom symbol table provided by you. This symbol table can be generated from a compiled binary containing DWARF2 debug information using the mksyms shell script contained in the tools directory of the libacfutils source repo. Please note, that MSVC doesn't generate DWARF2 debug information and therefore this utility cannot be used for binaries compiled with MSVC. The generated file data should be redirected to a file named syms.txt and placed next to the Windows XPL file for the plugin and shipped with the plugin, like this: $ tools/mksyms win.xpl > syms.txt
- Parameters
-
| skip_frames | Number of stack frames to skip off the top of the stack before printing the remaining frames. Sometimes a crash handler is invoked from within an exception or signal handling callback. This would place a bunch of useless stack frames near the top of the backtrace, resulting in a backtrace that's hard to read. Use this argument to skip them, if you know for sure how many there are. |
Definition at line 516 of file log.c.
| void log_init |
( |
logfunc_t |
func, |
|
|
const char * |
prefix |
|
) |
| |
Initializes the libacfutils logging subsystem. You must call this before any other subsystem of libacfutils. Typically, you would do this at the start of your plugin load callback (XPluginStart()). This is to make sure that if any of libacfutils' subsystems or your own code needs to log errors, they can. Without initialization, any logging calls will cause the app to crash with a call to abort().
At the end of your plugin's unload, deinitialize the logging subsystem using log_fini().
- Parameters
-
| func | A callback function which will be called for every log message that will be emitted. You can provide your own logging function, or use log_xplm_cb() to simply emit any log messages to the X-Plane Log.txt. |
| prefix | A logging prefix name, which will be prepended to every log message. This is to help disambiguate which plugin is emitting a particular message. A good choice here is something that is a short name of your plugin, e.g. "my_plugin". |
Definition at line 97 of file log.c.
