libqb  1.0.6
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
qblog.h File Reference
#include <stdint.h>
#include <stdlib.h>
#include <stdio.h>
#include <stdarg.h>
#include <errno.h>
#include <syslog.h>
#include <string.h>
#include <qb/qbutil.h>
#include <qb/qbconfig.h>
#include <assert.h>
#include <dlfcn.h>
Include dependency graph for qblog.h:

Data Structures

struct  qb_log_callsite
 An instance of this structure is created in a special ELF section at every dynamic debug callsite. More...
 
union  qb_log_ctl2_arg_t
 

Macros

#define LOG_TRACE   (LOG_DEBUG + 1)
 
#define QB_LOG_MAX_LEN   512
 
#define QB_LOG_STRERROR_MAX_LEN   128
 
#define QB_ATTR_SECTION   __verbose /* conforms to C ident. */
 
#define QB_ATTR_SECTION_STR   QB_PP_STRINGIFY(QB_ATTR_SECTION)
 
#define QB_ATTR_SECTION_START   QB_PP_JOIN(__start_, QB_ATTR_SECTION)
 
#define QB_ATTR_SECTION_STOP   QB_PP_JOIN(__stop_, QB_ATTR_SECTION)
 
#define QB_ATTR_SECTION_START_STR   QB_PP_STRINGIFY(QB_ATTR_SECTION_START)
 
#define QB_ATTR_SECTION_STOP_STR   QB_PP_STRINGIFY(QB_ATTR_SECTION_STOP)
 
#define QB_NONAPI_LOG_INIT_DATA_EXTRA_(name)
 
#define QB_LOG_INIT_DATA(name)
 Optional on-demand self-check of 1/ toolchain sanity (prerequisite for the logging subsystem to work properly) and 2/ non-void active use of logging (satisfied with a justifying existence of a logging callsite as defined with a qb_logt invocation) at the target (but see below), which is supposedly assured by it's author(!) as of relying on this very macro [technically, the symbols that happen to be resolved under the respective identifiers do not necessarily originate in the same compilation unit as when it's not the end executable (or by induction, a library positioned earlier in the symbol lookup order) but a shared library, the former takes a precedence unless that site comes short of exercising the logging, making its callsite section empty and, in turn, without such boundary symbols, hence making the resolution continue further in the lookup order – despite fuzzily targeted attestation, the check remains reasonable]; only effective when link-time ("run-time amortizing") callsite collection is; as a side effect, it can ensure the boundary-denoting symbols for the target collection area are kept alive with some otherwise unkind linkers. More...
 
#define QB_LOG_TAG_LIBQB_MSG_BIT   31
 
#define QB_LOG_TAG_LIBQB_MSG   (1U << QB_LOG_TAG_LIBQB_MSG_BIT)
 
#define qb_logt(priority, tags, fmt, args...)
 This is the function to generate a log message if you want to manually add tags. More...
 
#define qb_log(priority, fmt, args...)   qb_logt(priority, 0, fmt, ##args)
 This is the main function to generate a log message. More...
 
#define QB_XC   '\a'
 
#define QB_XS   "\a"
 
#define qb_perror(priority, fmt, args...)
 This is similar to perror except it goes into the logging system. More...
 
#define qb_enter()   qb_log(LOG_TRACE, "ENTERING %s()", __func__)
 
#define qb_leave()   qb_log(LOG_TRACE, "LEAVING %s()", __func__)
 
#define QB_LOG_CTL2_I32(a)   ((qb_log_ctl2_arg_t) { .i32 = (a) })
 
#define QB_LOG_CTL2_S(a)   ((qb_log_ctl2_arg_t) { .s = (a) })
 

Typedefs

typedef void(* qb_log_filter_fn) (struct qb_log_callsite *cs)
 
typedef void(* qb_log_logger_fn) (int32_t t, struct qb_log_callsite *cs, time_t timestamp, const char *msg)
 
typedef void(* qb_log_vlogger_fn) (int32_t t, struct qb_log_callsite *cs, time_t timestamp, va_list ap)
 
typedef void(* qb_log_close_fn) (int32_t t)
 
typedef void(* qb_log_reload_fn) (int32_t t)
 

Enumerations

enum  qb_log_target_slot {
  QB_LOG_TARGET_START, QB_LOG_TARGET_STATIC_START = QB_LOG_TARGET_START, QB_LOG_SYSLOG = QB_LOG_TARGET_STATIC_START, QB_LOG_STDERR,
  QB_LOG_BLACKBOX, QB_LOG_STDOUT, QB_LOG_TARGET_STATIC_MAX, QB_LOG_TARGET_STATIC_END = QB_LOG_TARGET_STATIC_MAX - 1,
  QB_LOG_TARGET_DYNAMIC_START = QB_LOG_TARGET_STATIC_MAX, QB_LOG_TARGET_MAX = 32, QB_LOG_TARGET_DYNAMIC_END = QB_LOG_TARGET_MAX - 1, QB_LOG_TARGET_END = QB_LOG_TARGET_DYNAMIC_END
}
 
enum  qb_log_target_state { QB_LOG_STATE_UNUSED = 1, QB_LOG_STATE_DISABLED = 2, QB_LOG_STATE_ENABLED = 3 }
 
enum  qb_log_conf {
  QB_LOG_CONF_ENABLED, QB_LOG_CONF_FACILITY, QB_LOG_CONF_DEBUG, QB_LOG_CONF_SIZE,
  QB_LOG_CONF_THREADED, QB_LOG_CONF_PRIORITY_BUMP, QB_LOG_CONF_STATE_GET, QB_LOG_CONF_FILE_SYNC,
  QB_LOG_CONF_EXTENDED, QB_LOG_CONF_IDENT
}
 
enum  qb_log_filter_type {
  QB_LOG_FILTER_FILE, QB_LOG_FILTER_FUNCTION, QB_LOG_FILTER_FORMAT, QB_LOG_FILTER_FILE_REGEX,
  QB_LOG_FILTER_FUNCTION_REGEX, QB_LOG_FILTER_FORMAT_REGEX
}
 
enum  qb_log_filter_conf {
  QB_LOG_FILTER_ADD, QB_LOG_FILTER_REMOVE, QB_LOG_FILTER_CLEAR_ALL, QB_LOG_TAG_SET,
  QB_LOG_TAG_CLEAR, QB_LOG_TAG_CLEAR_ALL
}
 

Functions

struct qb_log_callsite __attribute__ ((aligned(8)))
 
void qb_log_real_ (struct qb_log_callsite *cs,...)
 Internal function: use qb_log() or qb_logt() More...
 
void qb_log_real_va_ (struct qb_log_callsite *cs, va_list ap)
 
void qb_log_from_external_source (const char *function, const char *filename, const char *format, uint8_t priority, uint32_t lineno, uint32_t tags,...) __attribute__((format(printf
 This function is to import logs from other code (like libraries) that provide a callback with their logs. More...
 
void struct qb_log_callsiteqb_log_callsite_get (const char *function, const char *filename, const char *format, uint8_t priority, uint32_t lineno, uint32_t tags)
 Get or create a callsite at the given position. More...
 
void qb_log_from_external_source_va (const char *function, const char *filename, const char *format, uint8_t priority, uint32_t lineno, uint32_t tags, va_list ap) __attribute__((format(printf
 
void qb_log_init (const char *name, int32_t facility, uint8_t priority)
 Init the logging system. More...
 
void qb_log_fini (void)
 Logging system finalization function. More...
 
int32_t qb_log_callsites_register (struct qb_log_callsite *_start, struct qb_log_callsite *_stop)
 If you are using dynamically loadable modules via dlopen() and you load them after qb_log_init() then after you load the module you will need to do the following to get the filters to work in that module: More...
 
void qb_log_callsites_dump (void)
 Dump the callsite info to stdout. More...
 
int32_t qb_log_ctl (int32_t target, enum qb_log_conf conf_type, int32_t arg)
 Main logging control function. More...
 
int32_t qb_log_ctl2 (int32_t target, enum qb_log_conf conf_type, qb_log_ctl2_arg_t arg)
 Extension of main logging control function accepting also strings. More...
 
int32_t qb_log_filter_ctl (int32_t value, enum qb_log_filter_conf c, enum qb_log_filter_type type, const char *text, uint8_t low_priority)
 This allows you modify the 'tags' and 'targets' callsite fields at runtime. More...
 
int32_t qb_log_filter_ctl2 (int32_t value, enum qb_log_filter_conf c, enum qb_log_filter_type type, const char *text, uint8_t high_priority, uint8_t low_priority)
 This extends qb_log_filter_ctl() by been able to provide a high_priority. More...
 
int32_t qb_log_filter_fn_set (qb_log_filter_fn fn)
 Instead of using the qb_log_filter_ctl() functions you can apply the filters manually by defining a callback and setting the targets field using qb_bit_set() and qb_bit_clear() like the following below: More...
 
void qb_log_tags_stringify_fn_set (qb_log_tags_stringify_fn fn)
 Set the callback to map the 'tags' bit map to a string. More...
 
void qb_log_format_set (int32_t t, const char *format)
 Set the format specifiers. More...
 
int32_t qb_log_file_open (const char *filename)
 Open a log file. More...
 
void qb_log_file_close (int32_t t)
 Close a log file and release is resources. More...
 
int32_t qb_log_thread_priority_set (int32_t policy, int32_t priority)
 When using threaded logging set the pthread policy and priority. More...
 
int32_t qb_log_thread_start (void)
 Start the logging pthread. More...
 
ssize_t qb_log_blackbox_write_to_file (const char *filename)
 Write the blackbox to file. More...
 
void qb_log_blackbox_print_from_file (const char *filename)
 Read the blackbox for file and print it out. More...
 
int32_t qb_log_custom_open (qb_log_logger_fn log_fn, qb_log_close_fn close_fn, qb_log_reload_fn reload_fn, void *user_data)
 Open a custom log target. More...
 
void qb_log_custom_close (int32_t t)
 Close a custom log target and release is resources. More...
 
void * qb_log_target_user_data_get (int32_t t)
 Retrieve the user data set by either qb_log_custom_open or qb_log_target_user_data_set. More...
 
int32_t qb_log_target_user_data_set (int32_t t, void *user_data)
 Associate user data with this log target. More...
 
void qb_log_target_format (int32_t target, struct qb_log_callsite *cs, time_t timestamp, const char *formatted_message, char *output_buffer)
 Format the callsite and timestamp info according to the format. More...
 
int32_t qb_log_facility2int (const char *fname)
 Convert string "auth" to equivalent number "LOG_AUTH" etc. More...
 
const char * qb_log_facility2str (int32_t fnum)
 Convert number "LOG_AUTH" to equivalent string "auth" etc. More...
 

Variables

const typedef char *(* qb_log_tags_stringify_fn )(uint32_t tags)
 
const char * function
 
const char * filename
 
const char * format
 
uint8_t priority
 
uint32_t lineno
 
uint32_t targets
 
uint32_t tags
 
struct qb_log_callsite __start___verbose []
 
struct qb_log_callsite __stop___verbose []
 
enum qb_log_target_slot __attribute__
 

Detailed Description

The logging API provides four main parts (basics, filtering, threading & blackbox).

The idea behind this logging system is not to be prescriptive but to provide a set of tools to help the developer achieve what they want quickly and easily.

Basic logging API.
Call qb_log() to generate a log message. Then to write the message somewhere meaningful call qb_log_ctl() to configure the targets.

Simplest possible use:

main() {
qb_log_init("simple-log", LOG_DAEMON, LOG_INFO);
// ...
qb_log(LOG_WARNING, "watch out");
// ...
}
Note
In practice, such a minimalistic approach hardly caters real use cases. Following section discusses the customization. Moreover when employing the log module is bound to its active use (some log messages are assuredly emitted within the target compilation unit), it's quite vital to instrument the target side with QB_LOG_INIT_DATA() macro placed in the top file scope in exactly one source file (preferably the main one) to be mixed into the resulting compilation unit. This is a self-defensive measure for when the linker-assisted collection of callsite data silently fails, which could otherwise go unnoticed, causing troubles down the road, but alas it cannot discern misuse of QB_LOG_INIT_DATA() macro in no-logging context from broken callsite section handling assumptions owing to overboard fancy linker – situation that the self-check aims to detect in the first place.
Configuring log targets.
A log target can be syslog, stderr, the blackbox, stdout, or a text file. By default, only syslog is enabled. While this is customary for daemons, it is rarely appropriate for ordinary programs, which should promptly disable that when other targets (read on) are to be utilized:

To enable a target do the following:

syslog, stderr, the blackbox, and stdout are static (they don't need to be created, just enabled or disabled). However, you can open multiple logfiles (falling within inclusive range QB_LOG_TARGET_DYNAMIC_START up to QB_LOG_TARGET_DYNAMIC_END). To do this, use the following code:

mytarget = qb_log_file_open("/var/log/mylogfile");

Once your targets are enabled/opened, you can configure them as follows: Configure the size of blackbox:

Make logging to file threaded:

Sometimes, syslog daemons are (pre)configured to filter messages not exceeding a particular priority. When this happens to be the logging target, the designated priority of the message is passed along unchanged, possibly resulting in message loss. For messages up to LOG_DEBUG importance, this can be worked around by proportionally bumping the priorities to be passed to syslog (here, the step is such that LOG_DEBUG gets promoted to LOG_INFO):

To ensure all logs to file targets are fsync'ed (new messages expressly transferred to the storage device as they keep coming, otherwise defaults to QB_FALSE):

Filtering messages.
To have more power over what log messages go to which target you can apply filters to the targets. What happens is the desired callsites have the correct bit set. Then when the log message is generated it gets sent to the targets based on which bit is set in the callsite's "target" bitmap. Messages can be filtered based on the:
  1. filename + priority
  2. function name + priority
  3. format string + priority

So to make all logs from evil_function() go to stderr, do the following:

So to make all logs from totem* (with a priority <= LOG_INFO) go to stderr, do the following:

So to make all logs with the substring "ringbuffer" go to stderr, do the following:

Thread safe non-blocking logging.
Logging is only thread safe when threaded logging is in use. If you plan on logging from multiple threads, you must initialize libqb's logger thread and use qb_log_filter_ctl to set the QB_LOG_CONF_THREADED flag on all the logging targets in use.

To achieve non-blocking logging, so that any calls to write() or syslog() will not hold up your program, you can use threaded logging as well.

Threaded logging use:

main() {
qb_log_init("simple-log", LOG_DAEMON, LOG_INFO);
// ...
daemonize();
// call this after you fork()
// ...
qb_log(LOG_WARNING, "watch out");
// ...
}
A blackbox for in-field diagnosis.
This stores log messages in a ringbuffer so they can be written to file if the program crashes (you will need to catch SIGSEGV). These can then be easily printed out later.
Note
the blackbox is not enabled by default.

Blackbox usage:

static void sigsegv_handler(int sig)
{
(void)signal (SIGSEGV, SIG_DFL);
qb_log_blackbox_write_to_file("simple-log.fdata");
raise(SIGSEGV);
}
main() {
signal(SIGSEGV, sigsegv_handler);
qb_log_init("simple-log", LOG_DAEMON, LOG_INFO);
QB_LOG_FILTER_FILE, "*", LOG_DEBUG);
// ...
qb_log(LOG_WARNING, "watch out");
// ...
}
Tagging messages.
You can tag messages using the second argument to qb_logt() or by using qb_log_filter_ctl(). This can be used to add feature or sub-system information to the logs.
const char* my_tags_stringify(uint32_t tags) {
return "libqb";
} else if (tags == 3) {
return "three";
} else {
return "MAIN";
}
}
main() {
// ...
qb_log_tags_stringify_fn_set(my_tags_stringify);
// ...
qb_logt(LOG_INFO, 3, "hello");
qb_logt(LOG_INFO, 0, "hello");
}

The code above will produce:

[libqb] some message
[three] info hello
[MAIN ] info hello

Macro Definition Documentation

◆ LOG_TRACE

#define LOG_TRACE   (LOG_DEBUG + 1)

◆ QB_ATTR_SECTION

#define QB_ATTR_SECTION   __verbose /* conforms to C ident. */

◆ QB_ATTR_SECTION_START

#define QB_ATTR_SECTION_START   QB_PP_JOIN(__start_, QB_ATTR_SECTION)

◆ QB_ATTR_SECTION_START_STR

#define QB_ATTR_SECTION_START_STR   QB_PP_STRINGIFY(QB_ATTR_SECTION_START)

◆ QB_ATTR_SECTION_STOP

#define QB_ATTR_SECTION_STOP   QB_PP_JOIN(__stop_, QB_ATTR_SECTION)

◆ QB_ATTR_SECTION_STOP_STR

#define QB_ATTR_SECTION_STOP_STR   QB_PP_STRINGIFY(QB_ATTR_SECTION_STOP)

◆ QB_ATTR_SECTION_STR

#define QB_ATTR_SECTION_STR   QB_PP_STRINGIFY(QB_ATTR_SECTION)

◆ qb_enter

#define qb_enter ( )    qb_log(LOG_TRACE, "ENTERING %s()", __func__)
Examples
simplelog.c.

◆ qb_leave

#define qb_leave ( )    qb_log(LOG_TRACE, "LEAVING %s()", __func__)
Examples
simplelog.c.

◆ qb_log

#define qb_log (   priority,
  fmt,
  args... 
)    qb_logt(priority, 0, fmt, ##args)

This is the main function to generate a log message.

Parameters
prioritythis takes syslog priorities.
fmtusual printf style format specifiers
argsusual printf style args
Examples
ipcserver.c, and simplelog.c.

◆ QB_LOG_CTL2_I32

#define QB_LOG_CTL2_I32 (   a)    ((qb_log_ctl2_arg_t) { .i32 = (a) })

◆ QB_LOG_CTL2_S

#define QB_LOG_CTL2_S (   a)    ((qb_log_ctl2_arg_t) { .s = (a) })

◆ QB_LOG_INIT_DATA

#define QB_LOG_INIT_DATA (   name)
Value:
void name(void); \
void name(void) { \
void *work_handle; struct qb_log_callsite *work_s1, *work_s2; \
/* our own (target's) sanity, or possibly that of higher priority \
symbol resolution site (unless target equals end executable) \
or even the lower one if no such predecessor defines these */ \
if ((work_handle = dlopen(NULL, RTLD_LOCAL|RTLD_LAZY)) != NULL) { \
work_s1 = (struct qb_log_callsite *) \
dlsym(work_handle, QB_ATTR_SECTION_START_STR); \
work_s2 = (struct qb_log_callsite *) \
dlsym(work_handle, QB_ATTR_SECTION_STOP_STR); \
assert("implicit callsite section is observable, otherwise \target's and/or libqb's build is at fault, preventing reliable logging" \
&& work_s1 != NULL && work_s2 != NULL); \
dlclose(work_handle); /* perhaps overly eager thing to do */ } \
QB_NONAPI_LOG_INIT_DATA_EXTRA_(name); \
/* finally, original, straightforward check */ \
assert("implicit callsite section is populated, otherwise \target's build is at fault, preventing reliable logging" \
void __attribute__ ((constructor)) name(void);

Optional on-demand self-check of 1/ toolchain sanity (prerequisite for the logging subsystem to work properly) and 2/ non-void active use of logging (satisfied with a justifying existence of a logging callsite as defined with a qb_logt invocation) at the target (but see below), which is supposedly assured by it's author(!) as of relying on this very macro [technically, the symbols that happen to be resolved under the respective identifiers do not necessarily originate in the same compilation unit as when it's not the end executable (or by induction, a library positioned earlier in the symbol lookup order) but a shared library, the former takes a precedence unless that site comes short of exercising the logging, making its callsite section empty and, in turn, without such boundary symbols, hence making the resolution continue further in the lookup order – despite fuzzily targeted attestation, the check remains reasonable]; only effective when link-time ("run-time amortizing") callsite collection is; as a side effect, it can ensure the boundary-denoting symbols for the target collection area are kept alive with some otherwise unkind linkers.

Applying this macro in the target program/library is strongly recommended whenever the logging as framed by this header file is in use. Moreover, it's important to state that using this check while not ensuring _GNU_SOURCE macro definition is present at compile-time means only half of the available sanity checking will be performed, possibly resulting in libqb's own internally logged messages being lost without warning.

◆ QB_LOG_MAX_LEN

#define QB_LOG_MAX_LEN   512
Examples
simplelog.c.

◆ QB_LOG_STRERROR_MAX_LEN

#define QB_LOG_STRERROR_MAX_LEN   128

◆ QB_LOG_TAG_LIBQB_MSG

#define QB_LOG_TAG_LIBQB_MSG   (1U << QB_LOG_TAG_LIBQB_MSG_BIT)

◆ QB_LOG_TAG_LIBQB_MSG_BIT

#define QB_LOG_TAG_LIBQB_MSG_BIT   31
Examples
simplelog.c.

◆ qb_logt

#define qb_logt (   priority,
  tags,
  fmt,
  args... 
)
Value:
do { \
static struct qb_log_callsite descriptor \
__attribute__((section(QB_ATTR_SECTION_STR), aligned(8))) = \
{ __func__, __FILE__, fmt, priority, __LINE__, 0, tags }; \
qb_log_real_(&descriptor, ##args); \
} while(0)

This is the function to generate a log message if you want to manually add tags.

Parameters
prioritythis takes syslog priorities.
tagsthis is a uint32_t that you can use with qb_log_tags_stringify_fn_set() to "tag" a log message with a feature or sub-system then you can use "%g" in the format specifer to print it out.
fmtusual printf style format specifiers
argsusual printf style args
Examples
simplelog.c.

◆ QB_NONAPI_LOG_INIT_DATA_EXTRA_

#define QB_NONAPI_LOG_INIT_DATA_EXTRA_ (   name)
Value:
_Pragma(QB_PP_STRINGIFY(GCC warning QB_PP_STRINGIFY( \
without "_GNU_SOURCE" defined (directly or not) \
QB_LOG_INIT_DATA cannot check sanity of libqb proper \
nor of the target site originating this check alone)))

◆ qb_perror

#define qb_perror (   priority,
  fmt,
  args... 
)
Value:
do { \
char _perr_buf_[QB_LOG_STRERROR_MAX_LEN]; \
const char *_perr_str_ = qb_strerror_r(errno, _perr_buf_, sizeof(_perr_buf_)); \
qb_logt(priority, 0, fmt ": %s (%d)", ##args, _perr_str_, errno); \
} while(0)

This is similar to perror except it goes into the logging system.

Parameters
prioritythis takes syslog priorities.
fmtusual printf style format specifiers
argsusual printf style args
Note
Because qb_perror() adds the system error message and error number onto the end of the given fmt, that information will become extended information if QB_XS is used inside fmt and will not show up in any logs that strip extended information.
Examples
ipcserver.c, and simplelog.c.

◆ QB_XC

#define QB_XC   '\a'

◆ QB_XS

#define QB_XS   "\a"

Typedef Documentation

◆ qb_log_close_fn

typedef void(* qb_log_close_fn) (int32_t t)

◆ qb_log_filter_fn

typedef void(* qb_log_filter_fn) (struct qb_log_callsite *cs)

◆ qb_log_logger_fn

typedef void(* qb_log_logger_fn) (int32_t t, struct qb_log_callsite *cs, time_t timestamp, const char *msg)

◆ qb_log_reload_fn

typedef void(* qb_log_reload_fn) (int32_t t)

◆ qb_log_vlogger_fn

typedef void(* qb_log_vlogger_fn) (int32_t t, struct qb_log_callsite *cs, time_t timestamp, va_list ap)

Enumeration Type Documentation

◆ qb_log_conf

Enumerator
QB_LOG_CONF_ENABLED 
QB_LOG_CONF_FACILITY 
QB_LOG_CONF_DEBUG 
QB_LOG_CONF_SIZE 
QB_LOG_CONF_THREADED 
QB_LOG_CONF_PRIORITY_BUMP 
QB_LOG_CONF_STATE_GET 
QB_LOG_CONF_FILE_SYNC 
QB_LOG_CONF_EXTENDED 
QB_LOG_CONF_IDENT 

◆ qb_log_filter_conf

Enumerator
QB_LOG_FILTER_ADD 
QB_LOG_FILTER_REMOVE 
QB_LOG_FILTER_CLEAR_ALL 
QB_LOG_TAG_SET 
QB_LOG_TAG_CLEAR 
QB_LOG_TAG_CLEAR_ALL 

◆ qb_log_filter_type

Enumerator
QB_LOG_FILTER_FILE 
QB_LOG_FILTER_FUNCTION 
QB_LOG_FILTER_FORMAT 
QB_LOG_FILTER_FILE_REGEX 
QB_LOG_FILTER_FUNCTION_REGEX 
QB_LOG_FILTER_FORMAT_REGEX 

◆ qb_log_target_slot

Enumerator
QB_LOG_TARGET_START 
QB_LOG_TARGET_STATIC_START 
QB_LOG_SYSLOG 
QB_LOG_STDERR 
QB_LOG_BLACKBOX 
QB_LOG_STDOUT 
QB_LOG_TARGET_STATIC_MAX 
QB_LOG_TARGET_STATIC_END 
QB_LOG_TARGET_DYNAMIC_START 
QB_LOG_TARGET_MAX 
QB_LOG_TARGET_DYNAMIC_END 
QB_LOG_TARGET_END 

◆ qb_log_target_state

Enumerator
QB_LOG_STATE_UNUSED 
QB_LOG_STATE_DISABLED 
QB_LOG_STATE_ENABLED 

Function Documentation

◆ __attribute__()

struct qb_log_callsite __attribute__ ( (aligned(8))  )

◆ qb_log_blackbox_print_from_file()

void qb_log_blackbox_print_from_file ( const char *  filename)

Read the blackbox for file and print it out.

Examples
simplelog.c.

◆ qb_log_blackbox_write_to_file()

ssize_t qb_log_blackbox_write_to_file ( const char *  filename)

Write the blackbox to file.

Examples
simplelog.c.

◆ qb_log_callsite_get()

void struct qb_log_callsite* qb_log_callsite_get ( const char *  function,
const char *  filename,
const char *  format,
uint8_t  priority,
uint32_t  lineno,
uint32_t  tags 
)

Get or create a callsite at the given position.

The result can then be passed into qb_log_real_()

Parameters
functionoriginating function name
filenameoriginating filename
formatformat string
prioritythis takes syslog priorities.
linenofile line number
tagsthe tag

◆ qb_log_callsites_dump()

void qb_log_callsites_dump ( void  )

Dump the callsite info to stdout.

◆ qb_log_callsites_register()

int32_t qb_log_callsites_register ( struct qb_log_callsite _start,
struct qb_log_callsite _stop 
)

If you are using dynamically loadable modules via dlopen() and you load them after qb_log_init() then after you load the module you will need to do the following to get the filters to work in that module:

_start = dlsym (dl_handle, QB_ATTR_SECTION_START_STR);
_stop = dlsym (dl_handle, QB_ATTR_SECTION_STOP_STR);

◆ qb_log_ctl()

int32_t qb_log_ctl ( int32_t  target,
enum qb_log_conf  conf_type,
int32_t  arg 
)

Main logging control function.

Parameters
targetQB_LOG_SYSLOG, QB_LOG_STDERR or result from qb_log_file_open()
conf_typeconfiguration directive ("what to configure") that accepts int32_t argument determining the new value unless ignored for particular directive altogether (incompatible directives: QB_LOG_CONF_IDENT)
argthe new value for a state-changing configuration directive, ignored otherwise
See also
qb_log_conf
Return values
-errnoon error
0on success
qb_log_target_statefor QB_LOG_CONF_STATE_GET
Examples
ipcclient.c, ipcserver.c, and simplelog.c.

◆ qb_log_ctl2()

int32_t qb_log_ctl2 ( int32_t  target,
enum qb_log_conf  conf_type,
qb_log_ctl2_arg_t  arg 
)

Extension of main logging control function accepting also strings.

Parameters
targetQB_LOG_SYSLOG, QB_LOG_STDERR or result from qb_log_file_open()
conf_typeconfiguration directive ("what to configure") that accepts either int32_t or a null-terminated string argument determining the new value unless ignored for particular directive (compatible directives: those valid for qb_log_ctl
  • QB_LOG_CONF_IDENT)
argthe new value for a state-changing configuration directive, ignored otherwise; for QB_LOG_CONF_IDENT, 's' member as new identifier to openlog(), for all qb_log_ctl-compatible ones, 'i32' member is assumed (although a preferred way is to use that original function directly as it allows for more type safety)
See also
qb_log_ctl
Note
You can use QB_LOG_CTL2_I32 and QB_LOG_CTL2_S macros for a convenient on-the-fly construction of the object to be passed as an arg argument.

◆ qb_log_custom_close()

void qb_log_custom_close ( int32_t  t)

Close a custom log target and release is resources.

◆ qb_log_custom_open()

int32_t qb_log_custom_open ( qb_log_logger_fn  log_fn,
qb_log_close_fn  close_fn,
qb_log_reload_fn  reload_fn,
void *  user_data 
)

Open a custom log target.

Return values
-errnoon error
valuein inclusive range QB_LOG_TARGET_DYNAMIC_START to QB_LOG_TARGET_DYNAMIC_END (to be passed into other qb_log_* functions)
Examples
simplelog.c.

◆ qb_log_facility2int()

int32_t qb_log_facility2int ( const char *  fname)

Convert string "auth" to equivalent number "LOG_AUTH" etc.

◆ qb_log_facility2str()

const char* qb_log_facility2str ( int32_t  fnum)

Convert number "LOG_AUTH" to equivalent string "auth" etc.

◆ qb_log_file_close()

void qb_log_file_close ( int32_t  t)

Close a log file and release is resources.

◆ qb_log_file_open()

int32_t qb_log_file_open ( const char *  filename)

Open a log file.

Return values
-errnoon error
valuein inclusive range QB_LOG_TARGET_DYNAMIC_START to QB_LOG_TARGET_DYNAMIC_END (to be passed into other qb_log_* functions)
Examples
simplelog.c.

◆ qb_log_filter_ctl()

int32_t qb_log_filter_ctl ( int32_t  value,
enum qb_log_filter_conf  c,
enum qb_log_filter_type  type,
const char *  text,
uint8_t  low_priority 
)

This allows you modify the 'tags' and 'targets' callsite fields at runtime.

Examples
ipcclient.c, ipcserver.c, and simplelog.c.

◆ qb_log_filter_ctl2()

int32_t qb_log_filter_ctl2 ( int32_t  value,
enum qb_log_filter_conf  c,
enum qb_log_filter_type  type,
const char *  text,
uint8_t  high_priority,
uint8_t  low_priority 
)

This extends qb_log_filter_ctl() by been able to provide a high_priority.

Examples
simplelog.c.

◆ qb_log_filter_fn_set()

int32_t qb_log_filter_fn_set ( qb_log_filter_fn  fn)

Instead of using the qb_log_filter_ctl() functions you can apply the filters manually by defining a callback and setting the targets field using qb_bit_set() and qb_bit_clear() like the following below:

static void
m_filter(struct qb_log_callsite *cs)
{
if ((cs->priority >= LOG_ALERT &&
cs->priority <= LOG_DEBUG) &&
strcmp(cs->filename, "my_c_file.c") == 0) {
} else {
}
}
Examples
simplelog.c.

◆ qb_log_fini()

void qb_log_fini ( void  )

Logging system finalization function.

It releases any shared memory. Stops the logging thread if running. Flushes the last messages to their destinations.

Examples
ipcclient.c, ipcserver.c, and simplelog.c.

◆ qb_log_format_set()

void qb_log_format_set ( int32_t  t,
const char *  format 
)

Set the format specifiers.

n FUNCTION NAME f FILENAME l FILELINE p PRIORITY t TIMESTAMP b BUFFER g TAGS N name (passed into qb_log_init) P PID H hostname

Any number between % and character specify field length to pad or chop.

Note
Some of the fields are immediately evaluated and remembered for performance reasons, so when there's an objective for log messages to carry PIDs (not in the default setup) and, moreover, precisely, this function needs to be reinvoked upon fork (clone) in the respective children. When already linking to libpthread, pthread_atfork callback registration could be useful.
Examples
ipcclient.c, ipcserver.c, and simplelog.c.

◆ qb_log_from_external_source()

void qb_log_from_external_source ( const char *  function,
const char *  filename,
const char *  format,
uint8_t  priority,
uint32_t  lineno,
uint32_t  tags,
  ... 
)

This function is to import logs from other code (like libraries) that provide a callback with their logs.

Note
the performance of this will not impress you, as the filtering is done on each log message, not beforehand. So try doing basic pre-filtering.
Parameters
functionoriginating function name
filenameoriginating filename
formatformat string
prioritythis takes syslog priorities.
linenofile line number
tagsthis is a uint32_t that you can use with qb_log_tags_stringify_fn_set() to "tag" a log message with a feature or sub-system then you can use "%g" in the format specifer to print it out.

◆ qb_log_from_external_source_va()

void qb_log_from_external_source_va ( const char *  function,
const char *  filename,
const char *  format,
uint8_t  priority,
uint32_t  lineno,
uint32_t  tags,
va_list  ap 
)

◆ qb_log_init()

void qb_log_init ( const char *  name,
int32_t  facility,
uint8_t  priority 
)

Init the logging system.

Parameters
namewill be passed into openlog()
facilitydefault for all new targets.
prioritya basic filter with this priority will be added.
Examples
ipcclient.c, ipcserver.c, and simplelog.c.

◆ qb_log_real_()

void qb_log_real_ ( struct qb_log_callsite cs,
  ... 
)

Internal function: use qb_log() or qb_logt()

◆ qb_log_real_va_()

void qb_log_real_va_ ( struct qb_log_callsite cs,
va_list  ap 
)

◆ qb_log_tags_stringify_fn_set()

void qb_log_tags_stringify_fn_set ( qb_log_tags_stringify_fn  fn)

Set the callback to map the 'tags' bit map to a string.

Examples
simplelog.c.

◆ qb_log_target_format()

void qb_log_target_format ( int32_t  target,
struct qb_log_callsite cs,
time_t  timestamp,
const char *  formatted_message,
char *  output_buffer 
)

Format the callsite and timestamp info according to the format.

set using qb_log_format_set() It is intended to be used from your custom logger function.

Examples
simplelog.c.

◆ qb_log_target_user_data_get()

void* qb_log_target_user_data_get ( int32_t  t)

Retrieve the user data set by either qb_log_custom_open or qb_log_target_user_data_set.

◆ qb_log_target_user_data_set()

int32_t qb_log_target_user_data_set ( int32_t  t,
void *  user_data 
)

Associate user data with this log target.

Note
only use this with custom targets

◆ qb_log_thread_priority_set()

int32_t qb_log_thread_priority_set ( int32_t  policy,
int32_t  priority 
)

When using threaded logging set the pthread policy and priority.

Return values
-errnoon error
0success

◆ qb_log_thread_start()

int32_t qb_log_thread_start ( void  )

Start the logging pthread.

Examples
simplelog.c.

Variable Documentation

◆ __attribute__

enum qb_log_target_slot __attribute__

◆ __start___verbose

struct qb_log_callsite __start___verbose[]

◆ __stop___verbose

struct qb_log_callsite __stop___verbose[]

◆ filename

const char* filename

◆ format

const char* format

◆ function

const char* function

◆ lineno

uint32_t lineno

◆ priority

uint8_t priority

◆ qb_log_tags_stringify_fn

const typedef char*(* qb_log_tags_stringify_fn) (uint32_t tags)

◆ tags

uint32_t tags
Examples
simplelog.c.

◆ targets

uint32_t targets
qb_log_callsite::targets
uint32_t targets
Definition: qblog.h:283
QB_ATTR_SECTION_START
#define QB_ATTR_SECTION_START
Definition: qblog.h:296
qb_strerror_r
char * qb_strerror_r(int errnum, char *buf, size_t buflen)
strerror_r replacement.
QB_LOG_FILTER_FUNCTION
@ QB_LOG_FILTER_FUNCTION
Definition: qblog.h:587
QB_LOG_STRERROR_MAX_LEN
#define QB_LOG_STRERROR_MAX_LEN
Definition: qblog.h:268
QB_LOG_CONF_PRIORITY_BUMP
@ QB_LOG_CONF_PRIORITY_BUMP
Definition: qblog.h:578
qb_log_init
void qb_log_init(const char *name, int32_t facility, uint8_t priority)
Init the logging system.
QB_PP_STRINGIFY
#define QB_PP_STRINGIFY(arg)
Definition: qbdefs.h:66
qb_log_format_set
void qb_log_format_set(int32_t t, const char *format)
Set the format specifiers.
QB_TRUE
#define QB_TRUE
Definition: qbdefs.h:48
QB_LOG_INIT_DATA
#define QB_LOG_INIT_DATA(name)
Optional on-demand self-check of 1/ toolchain sanity (prerequisite for the logging subsystem to work ...
Definition: qblog.h:377
qb_bit_clear
#define qb_bit_clear(barray, bit)
Definition: qbdefs.h:55
qb_log_callsite::priority
uint8_t priority
Definition: qblog.h:281
qb_bit_set
#define qb_bit_set(barray, bit)
Definition: qbdefs.h:54
qb_log_tags_stringify_fn_set
void qb_log_tags_stringify_fn_set(qb_log_tags_stringify_fn fn)
Set the callback to map the 'tags' bit map to a string.
QB_ATTR_SECTION_STR
#define QB_ATTR_SECTION_STR
Definition: qblog.h:295
qb_logt
#define qb_logt(priority, tags, fmt, args...)
This is the function to generate a log message if you want to manually add tags.
Definition: qblog.h:478
qb_log_callsite::filename
const char * filename
Definition: qblog.h:279
qb_log
#define qb_log(priority, fmt, args...)
This is the main function to generate a log message.
Definition: qblog.h:501
__attribute__
enum qb_log_target_slot __attribute__
QB_ATTR_SECTION_STOP
#define QB_ATTR_SECTION_STOP
Definition: qblog.h:297
QB_LOG_SYSLOG
@ QB_LOG_SYSLOG
Definition: qblog.h:551
QB_FALSE
#define QB_FALSE
Definition: qbdefs.h:47
qb_log_callsites_register
int32_t qb_log_callsites_register(struct qb_log_callsite *_start, struct qb_log_callsite *_stop)
If you are using dynamically loadable modules via dlopen() and you load them after qb_log_init() then...
QB_LOG_TAG_LIBQB_MSG_BIT
#define QB_LOG_TAG_LIBQB_MSG_BIT
Definition: qblog.h:407
QB_ATTR_SECTION_START_STR
#define QB_ATTR_SECTION_START_STR
Definition: qblog.h:298
QB_LOG_CONF_ENABLED
@ QB_LOG_CONF_ENABLED
Definition: qblog.h:573
QB_LOG_CONF_FILE_SYNC
@ QB_LOG_CONF_FILE_SYNC
Definition: qblog.h:580
qb_log_file_open
int32_t qb_log_file_open(const char *filename)
Open a log file.
QB_ATTR_SECTION_STOP_STR
#define QB_ATTR_SECTION_STOP_STR
Definition: qblog.h:299
qb_log_thread_start
int32_t qb_log_thread_start(void)
Start the logging pthread.
qb_log_blackbox_write_to_file
ssize_t qb_log_blackbox_write_to_file(const char *filename)
Write the blackbox to file.
QB_LOG_CONF_THREADED
@ QB_LOG_CONF_THREADED
Definition: qblog.h:577
QB_LOG_FILTER_FILE
@ QB_LOG_FILTER_FILE
Definition: qblog.h:586
QB_LOG_FILTER_ADD
@ QB_LOG_FILTER_ADD
Definition: qblog.h:595
qb_log_fini
void qb_log_fini(void)
Logging system finalization function.
qb_log_filter_ctl
int32_t qb_log_filter_ctl(int32_t value, enum qb_log_filter_conf c, enum qb_log_filter_type type, const char *text, uint8_t low_priority)
This allows you modify the 'tags' and 'targets' callsite fields at runtime.
qb_log_callsite
An instance of this structure is created in a special ELF section at every dynamic debug callsite.
Definition: qblog.h:277
qb_bit_is_set
#define qb_bit_is_set(barray, bit)
Definition: qbdefs.h:56
tags
uint32_t tags
Definition: qblog.h:277
QB_LOG_CONF_SIZE
@ QB_LOG_CONF_SIZE
Definition: qblog.h:576
QB_LOG_FILTER_FORMAT
@ QB_LOG_FILTER_FORMAT
Definition: qblog.h:588
QB_LOG_BLACKBOX
@ QB_LOG_BLACKBOX
Definition: qblog.h:553
priority
uint8_t priority
Definition: qblog.h:274
qb_log_ctl
int32_t qb_log_ctl(int32_t target, enum qb_log_conf conf_type, int32_t arg)
Main logging control function.
QB_LOG_STDERR
@ QB_LOG_STDERR
Definition: qblog.h:552
LOG_TRACE
#define LOG_TRACE
Definition: qblog.h:265