Common

Typedefs
typedef struct M_log	M_log_t
typedef struct M_log_module	M_log_module_t
typedef void(*	M_log_prefix_cb) (M_buf_t *msg_buf, M_uint64 tag, void *prefix_thunk, void *msg_thunk)
typedef M_bool(*	M_log_filter_cb) (M_uint64 tag, void *filter_thunk, void *msg_thunk)
typedef void(*	M_log_expire_cb) (M_log_module_t *module, void *thunk)
typedef void(*	M_log_destroy_cb) (void *thunk)

Enumerations
enum	M_log_error_t {   M_LOG_SUCCESS = 0 ,   M_LOG_INVALID_PARAMS ,   M_LOG_INVALID_PATH ,   M_LOG_INVALID_TAG ,   M_LOG_NO_EVENT_LOOP ,   M_LOG_SUSPENDED ,   M_LOG_DUPLICATE_TAG_NAME ,   M_LOG_UNREACHABLE ,   M_LOG_INVALID_TIME_FORMAT ,   M_LOG_MODULE_UNSUPPORTED ,   M_LOG_MODULE_NOT_FOUND ,   M_LOG_WRONG_MODULE ,   M_LOG_GENERIC_FAIL }
enum	M_log_module_type_t {   M_LOG_MODULE_NULL = 0 ,   M_LOG_MODULE_STREAM ,   M_LOG_MODULE_NSLOG ,   M_LOG_MODULE_ANDROID ,   M_LOG_MODULE_FILE ,   M_LOG_MODULE_SYSLOG ,   M_LOG_MODULE_TSYSLOG ,   M_LOG_MODULE_MEMBUF }
enum	M_log_line_end_mode_t {   M_LOG_LINE_END_NATIVE ,   M_LOG_LINE_END_UNIX ,   M_LOG_LINE_END_WINDOWS }
enum	M_stream_type_t {   M_STREAM_STDOUT ,   M_STREAM_STDERR }
enum	M_syslog_facility_t {   M_SYSLOG_FACILITY_USER = 1 << 3 ,   M_SYSLOG_FACILITY_DAEMON = 3 << 3 ,   M_SYSLOG_FACILITY_LOCAL0 = 16 << 3 ,   M_SYSLOG_FACILITY_LOCAL1 = 17 << 3 ,   M_SYSLOG_FACILITY_LOCAL2 = 18 << 3 ,   M_SYSLOG_FACILITY_LOCAL3 = 19 << 3 ,   M_SYSLOG_FACILITY_LOCAL4 = 20 << 3 ,   M_SYSLOG_FACILITY_LOCAL5 = 21 << 3 ,   M_SYSLOG_FACILITY_LOCAL6 = 22 << 3 ,   M_SYSLOG_FACILITY_LOCAL7 = 23 << 3 }
enum	M_syslog_priority_t {   M_SYSLOG_EMERG = 0 ,   M_SYSLOG_ALERT = 1 ,   M_SYSLOG_CRIT = 2 ,   M_SYSLOG_ERR = 3 ,   M_SYSLOG_WARNING = 4 ,   M_SYSLOG_NOTICE = 5 ,   M_SYSLOG_INFO = 6 ,   M_SYSLOG_DEBUG = 7 }
enum	M_android_log_priority_t {   M_ANDROID_LOG_FATAL = 0 ,   M_ANDROID_LOG_ERROR = 1 ,   M_ANDROID_LOG_WARN = 2 ,   M_ANDROID_LOG_INFO = 3 ,   M_ANDROID_LOG_DEBUG = 4 ,   M_ANDROID_LOG_VERBOSE = 5 }

Functions
const char *	M_log_err_to_str (M_log_error_t err)
M_log_t *	M_log_create (M_log_line_end_mode_t mode, M_bool flush_on_destroy, M_event_t *event)
void	M_log_destroy (M_log_t *log)
void	M_log_destroy_blocking (M_log_t *log, M_uint64 timeout_ms)
M_log_error_t	M_log_set_time_format (M_log_t *log, const char *fmt)
M_log_error_t	M_log_set_tag_name (M_log_t *log, M_uint64 tag, const char *name)
const char *	M_log_get_tag_name (M_log_t *log, M_uint64 tag)
M_uint64	M_log_get_tag (M_log_t *log, const char *name)
M_log_error_t	M_log_set_tag_names_padded (M_log_t *log, M_bool padded)
M_log_error_t	M_log_printf (M_log_t *log, M_uint64 tag, void *msg_thunk, const char *fmt,...)
M_log_error_t	M_log_vprintf (M_log_t *log, M_uint64 tag, void *msg_thunk, const char *fmt, va_list ap)
M_log_error_t	M_log_write (M_log_t *log, M_uint64 tag, void *msg_thunk, const char *msg)
void	M_log_emergency (M_log_t *log, const char *msg)
void	M_log_reopen_all (M_log_t *log)
void	M_log_suspend (M_log_t *log)
void	M_log_resume (M_log_t *log, M_event_t *event)
M_list_t *	M_log_all_modules (M_log_t *log)
M_bool	M_log_module_present (M_log_t *log, M_log_module_t *module)
M_log_module_type_t	M_log_module_type (M_log_t *log, M_log_module_t *module)
M_log_error_t	M_log_module_set_accepted_tags (M_log_t *log, M_log_module_t *module, M_uint64 tags)
M_log_error_t	M_log_module_get_accepted_tags (M_log_t *log, M_log_module_t *module, M_uint64 *out_tags)
M_log_error_t	M_log_module_set_prefix (M_log_t *log, M_log_module_t *module, M_log_prefix_cb prefix_cb, void *prefix_thunk, M_log_destroy_cb thunk_destroy_cb)
M_log_error_t	M_log_set_prefix (M_log_t *log, M_log_prefix_cb prefix_cb, void *prefix_thunk, M_log_destroy_cb thunk_destroy_cb)
M_log_error_t	M_log_module_set_filter (M_log_t *log, M_log_module_t *module, M_log_filter_cb filter_cb, void *filter_thunk, M_log_destroy_cb thunk_destroy_cb)
M_log_error_t	M_log_module_reopen (M_log_t *log, M_log_module_t *module)
M_log_error_t	M_log_module_remove (M_log_t *log, M_log_module_t *module)

Detailed Description

Common logging functions.

Typedef Documentation

M_log_t

typedef struct M_log M_log_t

Opaque struct that maintains state for the logging system.

M_log_module_t

typedef struct M_log_module M_log_module_t

Opaque handle used to refer to individual log modules. DON'T FREE THIS.

M_log_prefix_cb

typedef void(* M_log_prefix_cb) (M_buf_t *msg_buf, M_uint64 tag, void *prefix_thunk, void *msg_thunk)

Function type for per-module prefix callbacks.

This will be called every time a log message is sent to the module. It allows you to add a custom prefix after the timestamp string, by letting you append to the message buffer before the log message is added:

03-02-2012 08:05:32<your prefix here>... log message ...<line end char> 

Note that no spaces or separator chars are automatically added between the timestamp string, your prefix, and the log message.

If no prefix callback is provided, the default prefix ": " will be added instead.

Warning

Do not call any M_log_* or M_log_module_* functions from inside a prefix callback, it will cause a deadlock.

Do not write line-end characters in a prefix. Some logging modules don't handle multiple-line messages very well, and line-end chars are not automatically removed from custom prefixes.

May be called simultaneously from multiple threads. If the content of prefix_thunk may be modified after it's passed to a module, you should include your own locks inside the thunk and use them inside the callback.

See also

M_log_set_prefix()

Parameters

[in]	prefix_thunk	thunk passed to M_log_set_prefix()
[in]	msg_thunk	thunk passed to M_printf() or M_vprintf()
[in]	msg_buf	message buffer (append prefix to this)
[in]	tag	tag of message we're prefixing

M_log_filter_cb

typedef M_bool(* M_log_filter_cb) (M_uint64 tag, void *filter_thunk, void *msg_thunk)

Function type for per-module filtering callbacks.

This will be called every time a log message is sent to the module. If the function returns M_FALSE, the message will be ignored by the module.

Warning

Do not call any M_log_* or M_log_module_* functions from inside a filter callback, it will cause a deadlock.

May be called simultaneously from multiple threads. If the content of filter_thunk may be modified after it's passed to a module, you should include your own locks inside the thunk and use them inside the callback.

See also

M_log_module_set_filter()

Parameters

[in]	filter_thunk	thunk passed to M_log_module_set_filter()
[in]	msg_thunk	thunk passed to M_log_printf() or M_log_vprintf()
[in]	tag	tag of message we're filtering

Returns

M_TRUE if this module will accept the given tag, M_FALSE otherwise

M_log_expire_cb

typedef void(* M_log_expire_cb) (M_log_module_t *module, void *thunk)

Function type for callback that's called when a module expires.

This will be called by the log whenever a module expires and is automatically removed. Currently, only the membuf module has an automatic expiration date. The callback is not called when a module is removed by normal, user-initiated means like M_log_module_remove() or M_log_module_take_membuf().

Note that the callback is called AFTER the module is removed from the log. So, at the time the callback is called, the module handle is already invalid.

Warning

This callback may be called simultaneously by multiple internal threads. If the callback modifies some shared datastructure, you MUST use your own locks to prevent concurrent access to that datastructure.

See also

M_log_module_add_membuf()

Parameters

[in]	module	handle of membuf module that was just removed (invalid)
[in]	thunk	thunk passed to M_log_module_add_membuf()

M_log_destroy_cb

typedef void(* M_log_destroy_cb) (void *thunk)

Function type for destructors.

Enumeration Type Documentation

M_log_error_t

enum M_log_error_t

Error codes for the logging system.

Enumerator
M_LOG_SUCCESS	Operation succeeded.
M_LOG_INVALID_PARAMS	Given parameters invalid (usually a NULL pointer)
M_LOG_INVALID_PATH	Given filesystem path couldn't be normalized
M_LOG_INVALID_TAG	Single tags must be non-zero and a power of two
M_LOG_NO_EVENT_LOOP	No event loop specified for log, can't use event-based modules.
M_LOG_SUSPENDED	Log has been suspended, can't take the requested action until resume is called
M_LOG_DUPLICATE_TAG_NAME	Given name has already been assigned to a different tag
M_LOG_UNREACHABLE	Requested resource unreachable (can't connect to host, can't open file on disk)
M_LOG_INVALID_TIME_FORMAT	Given time format string is invalid (can't be parsed)
M_LOG_MODULE_UNSUPPORTED	The given module type is not supported on this OS
M_LOG_MODULE_NOT_FOUND	The requested module has already been removed from the logger
M_LOG_WRONG_MODULE	Module-specific function was run on the wrong module
M_LOG_GENERIC_FAIL	Generic internal module failure occurred (usually an IO error)

M_log_module_type_t

enum M_log_module_type_t

Logging module types.

Enumerator
M_LOG_MODULE_NULL	Type that represents invalid or unset module type
M_LOG_MODULE_STREAM	Module that outputs to stdout or stderr
M_LOG_MODULE_NSLOG	Module that outputs to macOS/iOS logging system (NSLog)
M_LOG_MODULE_ANDROID	Module that outputs to android logging system
M_LOG_MODULE_FILE	Module that outputs to a set of files on the filesystem
M_LOG_MODULE_SYSLOG	Module that outputs directly to a local syslog daemon
M_LOG_MODULE_TSYSLOG	Module that outputs to a remove syslog daemon using TCP
M_LOG_MODULE_MEMBUF	Module that outputs to a temporary memory buffer

M_log_line_end_mode_t

enum M_log_line_end_mode_t

Control what type of line endings get automatically appended to log messages.

Enumerator
M_LOG_LINE_END_NATIVE	'\n' if running on Unix, '\r\n' if running on Windows
M_LOG_LINE_END_UNIX	always use '\n'
M_LOG_LINE_END_WINDOWS	always use '\r\n'

M_stream_type_t

enum M_stream_type_t

Types of output streams that can be used for the stream module.

Enumerator
M_STREAM_STDOUT	Output log messages to stdout
M_STREAM_STDERR	Output log messages to stderr

M_syslog_facility_t

enum M_syslog_facility_t

Standard facility types for syslog and tcp_syslog modules.

Enumerator
M_SYSLOG_FACILITY_USER
M_SYSLOG_FACILITY_DAEMON
M_SYSLOG_FACILITY_LOCAL0
M_SYSLOG_FACILITY_LOCAL1
M_SYSLOG_FACILITY_LOCAL2
M_SYSLOG_FACILITY_LOCAL3
M_SYSLOG_FACILITY_LOCAL4
M_SYSLOG_FACILITY_LOCAL5
M_SYSLOG_FACILITY_LOCAL6
M_SYSLOG_FACILITY_LOCAL7

M_syslog_priority_t

enum M_syslog_priority_t

Standard log priority types for syslog and tcp_syslog modules.

Listed in enum in order of descending priority (highest priority --> lowest priority).

It is up to the caller to define the mapping between their own logging tags and the syslog priority levels. These mappings are defined on a per-module basis.

See also

M_log_module_syslog_set_tag_priority

M_log_module_tcp_syslog_set_tag_priority

Enumerator
M_SYSLOG_EMERG
M_SYSLOG_ALERT
M_SYSLOG_CRIT
M_SYSLOG_ERR
M_SYSLOG_WARNING
M_SYSLOG_NOTICE
M_SYSLOG_INFO
M_SYSLOG_DEBUG

M_android_log_priority_t

enum M_android_log_priority_t

Standard log priority types for android log module.

Listed in enum in order of descending priority (highest priority --> lowest priority).

See also

M_log_module_android_set_tag_priority

Enumerator
M_ANDROID_LOG_FATAL
M_ANDROID_LOG_ERROR
M_ANDROID_LOG_WARN
M_ANDROID_LOG_INFO
M_ANDROID_LOG_DEBUG
M_ANDROID_LOG_VERBOSE

Function Documentation

M_log_err_to_str()

const char * M_log_err_to_str

(

M_log_error_t

err

)

Return human-readable string describing the given error code.

Parameters

[in]

err

error code

Returns

human-readable descriptive string

M_log_create()

M_log_t * M_log_create	(	M_log_line_end_mode_t	mode,
		M_bool	flush_on_destroy,
		M_event_t *	event
	)

Create a new log manager.

When first created, the log manager will accept messages, but won't output anything. The desired output modules must be added and configured after the logger is created. You can add any number or combination of the output modules.

To free the logger object, you must call M_log_destroy() or M_log_destroy_blocking().

If flush_on_destroy is set to M_TRUE, log modules won't be destroyed until all messages in their queue (if any) are written. Otherwise, log modules will be destroyed immediately after the message currently being written is done.

If you don't plan on adding any event-based modules (like tcp_syslog), you can pass NULL for the event pointer.

See also

M_log_module_add_stream

M_log_module_add_file

M_log_module_add_syslog

M_log_module_add_tcp_syslog

M_log_module_add_membuf

M_log_destroy

M_log_destroy_blocking

Parameters

[in]	mode	line-ending mode
[in]	flush_on_destroy	if M_TRUE, wait until message queue is empty when destroying a module
[in]	event	external event loop to use for event-based modules (not owned by logger)

Returns

new logger object

M_log_destroy()

void M_log_destroy

(

M_log_t *

log

)

Destroy the logger (non-blocking).

Sends a message to each module requesting that it stop at the next opportunity and destroy itself, then immediately destroys the logger.

Worker threads will try to clean themselves up gracefully, after this function returns (if the process doesn't end before they have a chance to).

See also

M_log_destroy_blocking

Parameters

[in]

log

logger object

M_log_destroy_blocking()

void M_log_destroy_blocking	(	M_log_t *	log,
		M_uint64	timeout_ms
	)

Destroy the logger (blocking).

Sends a message to each module requesting that it stop at the next opportunity. Once all internal worker threads have stopped, destroys all the modules and the logger.

If the timeout is reached before all modules have stopped, non-blocking destroys will be triggered for the remaining modules.

In order to avoid blocking the event loop, backend modules like TCP syslog which are event-based (no worker threads) will not block when this function is called. Instead, they will execute a normal non-blocking destroy. To give these backends time to exit cleanly, make sure to call M_event_done_with_disconnect() after this function, and pass non-zero values to both timeouts.

Example:

M_event_t  event_loop = ...;
M_log_t   *log        = M_log_create(..., event_loop, ...);
...
// Block up to five seconds while threaded backends try to exit cleanly.
M_log_destroy_blocking(log, 5000);
 
// Wait up to five seconds for top-level handlers added by event-based log backends to close their
// own I/O objects. Then, wait up to 1 second to force clean disconnects on any I/O objects
// that are still open.
M_event_done_with_disconnect(event_loop, 5000, 1000);
 
M_event_destroy(event_loop);

See also

M_log_destroy

Parameters

[in]	log	logger object
[in]	timeout_ms	amount of time to wait for modules to finish before giving up, or 0 to never give up

M_log_set_time_format()

M_log_error_t M_log_set_time_format	(	M_log_t *	log,
		const char *	fmt
	)

Set timestamp format for all future log messages.

If not set, the default timestamp format "%Y-%M-%DT%H:%m:%s.%l%Z" (ISO8601) will be used.

If the given time format string is empty or invalid, an error will be returned and the old time format string will be preserved.

Specifiers accepted in time format string:

• %t – Unix timestamp
• %M – 2 digit month
• %a – abbreviated month (Jan/Feb/Mar, etc)
• %D – 2 digit day of month
• %d – abbreviated day of week (Sun/Mon/Tue, etc)
• %Y – 4 digit year
• %y – 2 digit year
• %H – 2 digit hour
• %m – 2 digit minute
• %s – 2 digit second
• %l – 3 digit millisecond
• %u – 6 digit microsecond
• %z – timezone offset (without colon)
• %Z – timezone offset (with colon)

For example "[%D/%a/%Y:%H:%m:%s.%l %z]" might give a prefix like: [11/Jan/2008:09:19:11.654 -0500]

Parameters

[in]	log	logger object
[in]	fmt	time format string

Returns

error code

M_log_set_tag_name()

M_log_error_t M_log_set_tag_name	(	M_log_t *	log,
		M_uint64	tag,
		const char *	name
	)

Associate a name with the given tag.

If a name is specified for the given tag, it will be added to the message prefix, in between the timestamp and the custom prefix.

Alternatively, since the tag gets passed into the custom prefix callback, you can add the tag name there instead of using this.

Tag names must be unique (case-insensitive). If you try to assign the same name to two tags, you'll get an error code on the second (M_LOG_DUPLICATE_NAME).

Parameters

log	logger object
tag	user-defined tag (must be a single power-of-two tag)
name	name to associate with this tag (NULL or empty string to remove an existing name association)

Returns

error code

M_log_get_tag_name()

const char * M_log_get_tag_name	(	M_log_t *	log,
		M_uint64	tag
	)

Get the name associated with the given tag.

Warning

DO NOT call this method from a prefix or filter callback, it will cause a deadlock.

Parameters

log	logger object
tag	user-defined tag (must be a single power-of-two tag)

Returns

name of tag, or NULL if there's no name stored or some other error occurred

M_log_get_tag()

M_uint64 M_log_get_tag	(	M_log_t *	log,
		const char *	name
	)

Get the tag associated with the given name (case-insensitive).

Warning

DO NOT call this method from a prefix or filter callback, it will cause a deadlock.

Parameters

log	logger object
name	name that has been previously associated with a tag (case doesn't matter)

Returns

tag associated with the given name, or 0 if there's no tag with this name or some other error occurred

M_log_set_tag_names_padded()

M_log_error_t M_log_set_tag_names_padded	(	M_log_t *	log,
		M_bool	padded
	)

Control whether the log should pad names out to a common width or not.

By default, tag names are unpadded. However, if you use this function to enable padding, all tag names will be padded with spaces on the right out to the width of the longest name added to the log so far.

Parameters

log	logger object
padded	M_TRUE if tag names should be padded on output, M_FALSE if not (the default)

Returns

error code

M_log_printf()

M_log_error_t M_log_printf	(	M_log_t *	log,
		M_uint64	tag,
		void *	msg_thunk,
		const char *	fmt,
			...
	)

Write a formatted message to the log.

Multi-line messages will be split into a separate log message for each line.

A timestamp prefix will be automatically added to the start of each line, formatted according to the string set in M_log_set_time_format(). All the lines from a single call to M_printf() will be given identical timestamps.

The message will then be sent to each individual logging module for further processing, if the given message tag is in the list of accepted tags for the module (as set by M_log_module_set_accepted_tags()). A given module may also be skipped if a filter callback was set for the module and it rejected the message.

For each module that accepts the message, a prefix callback is called (if set) that appends additional text to each line's prefix, immediately following the timestamp string. The formatted message itself is then added, followed by the line-end characters corresponding to the current line-ending mode. The finished message is then sent on to the module.

Note that the per-message thunk only needs to be valid until M_log_printf() returns - you can put non-const data in here. This thunk is caller-managed - it's not freed or otherwise kept track of internally.

Parameters

[in]	log	logger object
[in]	tag	user-defined tag attached to this message (must be a single power-of-two tag)
[in]	msg_thunk	per-message thunk to pass to filter and prefix callbacks (only needs to be valid until function returns)
[in]	fmt	format string, accepts same tags as M_printf()

Returns

error code

M_log_vprintf()

M_log_error_t M_log_vprintf	(	M_log_t *	log,
		M_uint64	tag,
		void *	msg_thunk,
		const char *	fmt,
		va_list	ap
	)

Write a formatted message to the log (var arg).

Same as M_log_printf(), but accepts a variable argument list explicitly as a va_list. This is inteded to allow the user to define their own wrapper functions that take variable argument lists (...) and call M_log_vprintf() internally.

Parameters

[in]	log	logger object
[in]	tag	user-defined tag attached to this message (must be a single power-of-two tag)
[in]	msg_thunk	per-message thunk to pass to filter and prefix callbacks (only needs to be valid until function returns)
[in]	fmt	format string, accepts same tags as M_printf()
[in]	ap	list of arguments passed in from the calling vararg function

Returns

error code

M_log_write()

M_log_error_t M_log_write	(	M_log_t *	log,
		M_uint64	tag,
		void *	msg_thunk,
		const char *	msg
	)

Write a message directly to the log.

Same as M_log_printf(), but it takes a message directly, instead of a format string and a list of arguments.

Parameters

[in]	log	logger object
[in]	tag	user-defined tag attached to this message (must be a single power-of-two tag)
[in]	msg_thunk	per-message thunk to pass to filter and prefix callbacks (only needs to be valid until function returns)
[in]	msg	message string

M_log_emergency()

void M_log_emergency	(	M_log_t *	log,
		const char *	msg
	)

Perform an emergency message write, to all modules that allow such writes.

Warning

This function is EXTREMELY dangerous. It's meant to be called in a signal handler as the program is crashing, so it doesn't acquire any mutex locks, and it tries not to malloc anything. DON'T USE THIS FUNCTION IN NORMAL USAGE, IT IS NOT SAFE.

Parameters

[in]	log	logger object
[in]	msg	emergency message to output

M_log_reopen_all()

void M_log_reopen_all

(

M_log_t *

log

)

Reopen/refresh connections for all modules in the logger.

This closes then re-opens existing file streams, syslog, TCP connections, etc. for every loaded module.

Modules that don't open or close anything (membuf, stream, Android log, etc.) are unaffected by this command.

See also

M_log_module_reopen (if you only want to reopen a specific module)

Parameters

[in]

log

logger object

M_log_suspend()

void M_log_suspend

(

M_log_t *

log

)

Suspend connections for all modules in the logger (BLOCKING).

This closes existing file streams, syslog, TCP connections, etc. for every loaded module.

For modules that have resources closed, messages will accumulate without any being written while suspended.

Modules that don't open or close anything (membuf, stream, Android log, etc.) are unaffected by this command.

Warning

This call will block until every module that can be suspended reports that it is finished suspending itself. At worst, this means that we'll be blocked until whatever message is in the process of being written is done.

If you have modules that depend on an external event loop (like tcp_syslog), you must wait for the event loop to finish after calling suspend, and then destroy it. You then create a new event loop once you're ready to resume, and pass it into M_log_resume().

See also

M_log_resume

Parameters

[in]

log

logger object

M_log_resume()

void M_log_resume	(	M_log_t *	log,
		M_event_t *	event
	)

Resume connections for all modules in the logger.

This opens file streams, syslog, TCP connections, etc. that were closed by M_log_suspend().

Modules that were previously suspended will now start pulling messages of the queue and writing them again.

If you have any modules that use an external event loop, you must pass the new loop to use into this function (since you should have destroyed the old one after calling suspend). If you're not using event-based modules, you can just set this to NULL.

See also

M_log_suspend

Parameters

[in]	log	logger object
[in]	event	external event loop to use for event-based modules (not owned by logger)

M_log_all_modules()

M_list_t * M_log_all_modules

(

M_log_t *

log

)

Return list of handles of all currently loaded modules.

The returned list is a snapshot of what modules were loaded when the function was called. Other threads may modify the internal list of modules after you get a copy, so the list of modules may not be accurate.

The caller is responsible for freeing the returned list with M_list_destroy().

Parameters

[in]

log

logger object

Returns

list of M_log_module_t pointers (module handles)

M_log_module_present()

M_bool M_log_module_present	(	M_log_t *	log,
		M_log_module_t *	module
	)

Check to see if the given module handle is still loaded in the logger.

See also

M_log_module_remove

Parameters

[in]	log	logger object
[in]	module	handle of module to operate on

Returns

M_TRUE if module hasn't been removed from the log yet, M_FALSE otherwise

M_log_module_type()

M_log_module_type_t M_log_module_type	(	M_log_t *	log,
		M_log_module_t *	module
	)

Return the type of the given module (file, stream, etc.).

Parameters

[in]	log	logger object
[in]	module	handle of module to operate on

Returns

type of module, or M_LOG_MODULE_NULL if module has already been removed

M_log_module_set_accepted_tags()

M_log_error_t M_log_module_set_accepted_tags	(	M_log_t *	log,
		M_log_module_t *	module,
		M_uint64	tags
	)

Associate the given user-defined tag(s) with the given module handle.

If you don't associate any tags with a module, nothing will get written to it.

See also

M_LOG_ALL_TAGS

M_log_all_tags_lt

M_log_all_tags_lte

M_log_all_tags_gt

M_log_all_tags_gte

M_log_module_get_accepted_tags

Parameters

[in]	log	logger object
[in]	module	handle of module to operate on
[in]	tags	user-defined power-of-two tag (or multiple power-of-two tags, OR'd together)

Returns

error code

M_log_module_get_accepted_tags()

M_log_error_t M_log_module_get_accepted_tags	(	M_log_t *	log,
		M_log_module_t *	module,
		M_uint64 *	out_tags
	)

Return a snapshot of the user-defined tag(s) currently associated with the given module handle.

See also

M_log_module_set_accepted_tags

Parameters

[in]	log	logger object
[in]	module	handle of module to operate on
[out]	out_tags	tag snapshot will be placed here, or 0 if no tags are associated with this module

Returns

error code

M_log_module_set_prefix()

M_log_error_t M_log_module_set_prefix	(	M_log_t *	log,
		M_log_module_t *	module,
		M_log_prefix_cb	prefix_cb,
		void *	prefix_thunk,
		M_log_destroy_cb	thunk_destroy_cb
	)

Associate a prefix callback with the given module handle.

This exists only for legacy compatibility. Do Not use. It does not associate with a module.

See also

M_log_set_prefix

Parameters

[in]	log	logger object
[in]	module	handle of module to operate on
[in]	prefix_cb	prefix callback (function pointer)
[in]	prefix_thunk	any state used by prefix callback
[in]	thunk_destroy_cb	function to call when destroying the prefix thunk

Returns

error code

M_log_set_prefix()

M_log_error_t M_log_set_prefix	(	M_log_t *	log,
		M_log_prefix_cb	prefix_cb,
		void *	prefix_thunk,
		M_log_destroy_cb	thunk_destroy_cb
	)

M_log_module_set_filter()

M_log_error_t M_log_module_set_filter	(	M_log_t *	log,
		M_log_module_t *	module,
		M_log_filter_cb	filter_cb,
		void *	filter_thunk,
		M_log_destroy_cb	thunk_destroy_cb
	)

Associate a filter callback with the given module handle.

The filter callback allows the user to reject additional log messages. It is applied after the messages are filtered according to the list of accepted tags set by M_log_module_set_accepted_tags(). If no filter callback is provided, no additional filtering beyond the list of accepted tags will be performed. See M_log_filter_cb for more details.

See also

M_log_filter_cb

M_log_module_set_accepted_tags

Parameters

[in]	log	logger object
[in]	module	handle of module to operate on
[in]	filter_cb	filter callback (function pointer)
[in]	filter_thunk	any state used by filter callback
[in]	thunk_destroy_cb	function to call when destroying the filter thunk

Returns

error code

M_log_module_reopen()

M_log_error_t M_log_module_reopen	(	M_log_t *	log,
		M_log_module_t *	module
	)

Trigger a disconnect/reconnect of the given module's internal resource.

The exact action taken by this command depends on the module. For example, the file module will close and reopen the internal connection to the main log file. Modules without closeable resources (like membuf and stream) treat this as a no-op.

See also

M_log_reopen_all (if you want to reopen all modules in the logger)

Parameters

[in]	log	logger object
[in]	module	handle of module to operate on

Returns

error code

M_log_module_remove()

M_log_error_t M_log_module_remove	(	M_log_t *	log,
		M_log_module_t *	module
	)

Remove a module from the running log and destroy it.

This function does not block. If the module is busy writing a message, it is removed from the list of active modules, and then it destroys itself asynchronously when the module is finished with its current chunk of work.

Parameters

[in]	log	logger object
[in]	module	handle of module to destroy

Returns

error code