Filesystem Module

Functions
M_log_error_t	M_log_module_add_file (M_log_t *log, const char *log_file_path, size_t num_to_keep, M_uint64 autorotate_size, M_uint64 autorotate_time_s, size_t max_queue_bytes, const char *archive_cmd, const char *archive_file_ext, M_log_module_t **out_mod)
M_log_error_t	M_log_module_file_rotate (M_log_t *log, M_log_module_t *module)

Detailed Description

Functions to enable logging to a group of files on disk. Includes support for log rotation and compression.

Function Documentation

M_log_module_add_file()

M_log_error_t M_log_module_add_file	(	M_log_t *	log,
		const char *	log_file_path,
		size_t	num_to_keep,
		M_uint64	autorotate_size,
		M_uint64	autorotate_time_s,
		size_t	max_queue_bytes,
		const char *	archive_cmd,
		const char *	archive_file_ext,
		M_log_module_t **	out_mod
	)

Add a module to output to a rotating list of files on disk.

When archiving a file, the uncompressed file name will be appended directly onto whatever archive command is supplied by the user, then executed in its own process. In order for rotation to work correctly, the output file produced by the command must be exactly equal to [uncompressed file][archive_file_ext].

The automatic file rotation parameters (autorotate_size and autorotate_time_s) can be disabled by setting them to a value of 0. If both are disabled, rotations will only happen when M_log_module_file_rotate() is explicitly called by the user.

The behavior of time-based autorotate is platform dependent. On platforms that allow you to query file creation time (e.g., Windows, macOS, BSD), the age of the file is calculated from its creation date. On platforms that don't keep track of file creation time (e.g., Linux), the age of the file is calculated using an internal timer that starts when the file is first opened. On such platforms, the age of the head log file is effectively reset to zero whenever you restart the process.

Parameters

[in]	log	logger object
[in]	log_file_path	main log file to output (if relative path, interpreted relative to current working dir)
[in]	num_to_keep	number of older rotated log files to keep on disk, or 0 to keep no old files
[in]	autorotate_size	size (in bytes) after which the main log file is rotated, or 0 to disable size autorotate
[in]	autorotate_time_s	time (in seconds) after which the main log file is rotated, or 0 to disable time autorotate
[in]	max_queue_bytes	max size of queue used to buffer asynchronous writes to the log file
[in]	archive_cmd	command used to compress old log files (e.g., "bzip2 -f"). If NULL, compression is disabled.
[in]	archive_file_ext	extension added to files by archive_cmd (e.g., ".bz2"). If NULL, compression is disabled.
[out]	out_mod	handle for created module, or NULL if there was an error.

Returns

error code

M_log_module_file_rotate()

M_log_error_t M_log_module_file_rotate	(	M_log_t *	log,
		M_log_module_t *	module
	)

Manually trigger a file rotation.

This can be used to rotate the main log file on some other condition than size - like receiving SIGHUP, or on some sort of timer. If the internal message queue is empty, the rotation will happen immediately. If not, the rotation will happen after the internal worker thread finishes writing the message it's currently working on.

Parameters

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

Returns

error code