log.h File Reference

📝 Logging API with multiple log levels and terminal output control More...

Go to the source code of this file.

Data Structures
struct	log_buffer_entry_t
	A single buffered log entry. More...

Macros
#define	LOG_ATOMIC_UINT64   atomic_t
#define	LOG_ATOMIC_UINT64_INIT(val)
#define	DEFAULT_LOG_LEVEL   LOG_DEBUG
	Default log level for debug builds (DEBUG and above)
#define	MAX_LOG_SIZE   (3 * 1024 * 1024)
	Maximum log file size in bytes (3MB) before rotation.
#define	MAX_TERMINAL_BUFFER_SIZE   (64 * 1024)
	Maximum size of terminal output buffer (64KB)
#define	MAX_TERMINAL_BUFFER_ENTRIES   256
	Maximum number of buffered log entries.
#define	LOG_MSG_BUFFER_SIZE   4096
	Maximum size of a single log message (including formatting)
#define	LOG_MMAP_MSG_BUFFER_SIZE   1024
	Maximum size of a log message in mmap mode.
#define	LOG_HEADER_BUFFER_SIZE   512
	Maximum size of a log header (timestamp, level, file:line:func)
#define	LOG_TIMESTAMP_BUFFER_SIZE   32
	Maximum size of a timestamp string.
#define	log_plain(...)   log_plain_msg(__VA_ARGS__)
	Plain logging - writes to both log file and stderr without timestamps or log levels.
#define	log_plain_stderr(...)   log_plain_stderr_msg(__VA_ARGS__)
	Plain logging to stderr with newline.
#define	log_plain_stdout(...)   log_plain_stdout_msg(__VA_ARGS__)
	Plain logging to stdout with newline.
#define	log_plain_stderr_nonewline(...)   log_plain_stderr_nonewline_msg(__VA_ARGS__)
	Plain logging to stderr without newline - for interactive prompts.
#define	log_file(...)   log_file_msg(__VA_ARGS__)
	File-only logging - writes to log file only, no stderr output.
#define	log_every(log_level, interval_us, fmt, ...)
	Rate-limited logging macro (thread-safe)
#define	log_nth(log_level, n, fmt, ...)
	Log every nth call to this code location (thread-safe)
#define	log_once(log_level, fmt, ...)
	Log exactly once per call site (thread-safe)
#define	log_console(level, message)   log_console_impl((level), __FILE__, __LINE__, __func__, (message))
Logging Macros
Note Compile-time log level stripping: In release builds, log_dev() and log_debug() are compiled out completely (no runtime overhead). Override with LOG_COMPILE_LEVEL.
#define	log_as(level, ...)   log_msg(level, __FILE__, __LINE__, __func__, __VA_ARGS__)
	Log a message given the associated level.
#define	log_only(bitmask, level, ...)
	Log a message given its level and if the bitmask allows so.
#define	log_dev(...)   log_only(LOG_BIT(LOG_DEV), LOG_DEV, __VA_ARGS__)
	Log a DEV message (most verbose, development only)
#define	log_debug(...)   log_only(LOG_BIT(LOG_DEBUG), LOG_DEBUG, __VA_ARGS__)
	Log a DEBUG message.
#define	log_info(...)   log_only(LOG_BIT(LOG_INFO), LOG_INFO, __VA_ARGS__)
	Log an INFO message.
#define	log_warn(...)   log_only(LOG_BIT(LOG_WARN), LOG_WARN, __VA_ARGS__)
	Log a WARN message.
#define	log_error(...)   log_only(LOG_BIT(LOG_ERROR), LOG_ERROR, __VA_ARGS__)
	Log an ERROR message.
#define	log_fatal(...)   log_only(LOG_BIT(LOG_FATAL), LOG_FATAL, __VA_ARGS__)
	Log a FATAL message.
Rate-Limited Logging Macros
#define	log_dev_every(interval_us, fmt, ...)   log_every(DEV, interval_us, fmt, ##__VA_ARGS__)
	Rate-limited DEV logging.
#define	log_debug_every(interval_us, fmt, ...)   log_every(DEBUG, interval_us, fmt, ##__VA_ARGS__)
	Rate-limited DEBUG logging.
#define	log_info_every(interval_us, fmt, ...)   log_every(INFO, interval_us, fmt, ##__VA_ARGS__)
	Rate-limited INFO logging.
#define	log_warn_every(interval_us, fmt, ...)   log_every(WARN, interval_us, fmt, ##__VA_ARGS__)
	Rate-limited WARN logging.
#define	log_error_every(interval_us, fmt, ...)   log_every(ERROR, interval_us, fmt, ##__VA_ARGS__)
	Rate-limited ERROR logging.
#define	log_fatal_every(interval_us, fmt, ...)   log_every(FATAL, interval_us, fmt, ##__VA_ARGS__)
	Rate-limited FATAL logging.
Nth-Call Logging Macros
#define	log_dev_nth(n, fmt, ...)   log_nth(DEV, n, fmt, ##__VA_ARGS__)
	Log DEV message every nth call.
#define	log_debug_nth(n, fmt, ...)   log_nth(DEBUG, n, fmt, ##__VA_ARGS__)
	Log DEBUG message every nth call.
#define	log_info_nth(n, fmt, ...)   log_nth(INFO, n, fmt, ##__VA_ARGS__)
	Log INFO message every nth call.
#define	log_warn_nth(n, fmt, ...)   log_nth(WARN, n, fmt, ##__VA_ARGS__)
	Log WARN message every nth call.
#define	log_error_nth(n, fmt, ...)   log_nth(ERROR, n, fmt, ##__VA_ARGS__)
	Log ERROR message every nth call.
#define	log_fatal_nth(n, fmt, ...)   log_nth(FATAL, n, fmt, ##__VA_ARGS__)
	Log FATAL message every nth call.
Once-Only Logging Macros
#define	log_dev_once(fmt, ...)   log_once(DEV, fmt, ##__VA_ARGS__)
	Log DEV message exactly once.
#define	log_debug_once(fmt, ...)   log_once(DEBUG, fmt, ##__VA_ARGS__)
	Log DEBUG message exactly once.
#define	log_info_once(fmt, ...)   log_once(INFO, fmt, ##__VA_ARGS__)
	Log INFO message exactly once.
#define	log_warn_once(fmt, ...)   log_once(WARN, fmt, ##__VA_ARGS__)
	Log WARN message exactly once.
#define	log_error_once(fmt, ...)   log_once(ERROR, fmt, ##__VA_ARGS__)
	Log ERROR message exactly once.
#define	log_fatal_once(fmt, ...)   log_once(FATAL, fmt, ##__VA_ARGS__)
	Log FATAL message exactly once.

Typedefs
typedef struct color_scheme_t	color_scheme_t
typedef struct session_log_buffer	session_log_buffer_t
typedef struct log_mmap_config	log_mmap_config_t

Enumerations
enum	log_color_t {   LOG_COLOR_DEV = 0 , LOG_COLOR_DEBUG = 1 , LOG_COLOR_INFO = 2 , LOG_COLOR_WARN = 3 ,   LOG_COLOR_ERROR = 4 , LOG_COLOR_FATAL = 5 , LOG_COLOR_GREY = 6 , LOG_COLOR_RESET = 7 }
	Color enum for logging - indexes into color arrays. More...

Functions
void	log_init (const char *filename, log_level_t level, bool force_stderr, bool use_mmap)
	Initialize the logging system.
void	log_destroy (void)
	Destroy the logging system and close log file.
void	log_system_init (void)
	Initialize the logging system internal state (system-level init)
void	log_system_destroy (void)
	Shutdown the logging system internal state (system-level cleanup)
void	log_set_level (log_level_t level)
	Set the minimum log level.
log_level_t	log_get_level (void)
	Get the current minimum log level.
asciichat_error_t	log_set_format (const char *format_str, bool console_only)
	Set a custom log format string.
void	log_set_terminal_output (bool enabled)
	Control stderr output to terminal.
bool	log_get_terminal_output (void)
	Get current terminal output setting.
void	log_set_force_stderr (bool enabled)
	Force all terminal log output to stderr.
bool	log_get_force_stderr (void)
	Get current force_stderr setting.
void	log_disable_file_output (void)
	Disable file output and use stderr instead.
void	log_truncate_if_large (void)
	Manually truncate large log files.
void	log_msg (log_level_t level, const char *file, int line, const char *func, const char *fmt,...)
	Log a message at a specific level.
void	log_terminal_msg (log_level_t level, const char *file, int line, const char *func, const char *fmt,...)
	Log a message to terminal only (no file output)
void	log_plain_msg (const char *fmt,...)
	Plain logging without timestamps or levels.
void	log_plain_stderr_msg (const char *fmt,...)
	Plain logging to stderr with newline.
void	log_plain_stdout_msg (const char *fmt,...)
	Plain logging to stdout with newline.
void	log_plain_stderr_nonewline_msg (const char *fmt,...)
	Plain logging to stderr without trailing newline.
void	log_file_msg (const char *fmt,...)
	Log to file only, no stderr output.
void	log_labeled (const char *label, log_color_t color, const char *message,...)
	Print a labeled message with color.
const char *	log_level_color (log_color_t color)
	Get color string for a given color enum.
const char **	log_get_color_array (void)
	Get the appropriate color array based on terminal capabilities.
void	log_redetect_terminal_capabilities (void)
	Re-detect terminal capabilities after logging is initialized.
void	log_init_colors (void)
	Initialize logging color system with current terminal capabilities.
void	log_set_color_scheme (const color_scheme_t *scheme)
	Set the color scheme for logging output.
bool	log_lock_terminal (void)
	Lock terminal output for exclusive access by the calling thread.
void	log_unlock_terminal (bool previous_state)
	Release terminal lock and flush buffered messages.
void	log_set_flush_delay (unsigned int delay_ms)
	Set the delay between flushing buffered log entries.
char *	format_message (const char *format, va_list args)
	Format a message using va_list.
size_t	get_current_time_formatted (char *time_buf)
	Get current time as formatted string.
asciichat_error_t	log_network_message (socket_t sockfd, const struct crypto_context_t *crypto_ctx, log_level_t level, remote_log_direction_t direction, const char *fmt,...)
	Send a formatted log message over the network.
asciichat_error_t	log_net_message (socket_t sockfd, const struct crypto_context_t *crypto_ctx, log_level_t level, remote_log_direction_t direction, const char *file, int line, const char *func, const char *fmt,...)
	Log a message to all destinations (network, file, and terminal).
asciichat_error_t	log_enable_mmap (const char *log_path)
	Enable lock-free mmap-based logging.
asciichat_error_t	log_enable_mmap_sized (const char *log_path, size_t max_size)
	Enable lock-free mmap logging with custom file size.
void	log_disable_mmap (void)
	Disable mmap logging and return to mutex-based logging.
void	log_shutdown_begin (void)
	Begin shutdown phase - disable console logging but keep file logging.
void	log_shutdown_end (void)
	End shutdown phase - restore previous logging settings.
void	log_cleanup_colors (void)
	Clean up compiled color scheme.
void	log_set_session_log_buffer (session_log_buffer_t *buf)
	Register a session log buffer with the logger.
void	log_clear_session_log_buffer (void)
	Unregister the session log buffer.
session_log_buffer_t *	log_get_session_log_buffer (void)
	Get the currently registered session log buffer.
size_t	log_recolor_plain_entry (const char *plain_line, char *colored_buf, size_t buf_size)
	Recolor a plain (non-colored) log line with proper ANSI codes.
const char *	get_level_string_padded (log_level_t level)
	Get padded log level string (internal utility for formatting)
void	log_console_impl (log_level_t level, const char *file, int line, const char *func, const char *message)
void *	log_get_template (void)
	Get the current log format template (opaque pointer)

Detailed Description

📝 Logging API with multiple log levels and terminal output control

Definition in file log/log.h.

Macro Definition Documentation

log_console

#define log_console	(		level,
			message
	)		log_console_impl((level), __FILE__, __LINE__, __func__, (message))

Definition at line 1003 of file log/log.h.

log_debug_every

#define log_debug_every	(		interval_us,
			fmt,
			...
	)		log_every(DEBUG, interval_us, fmt, ##__VA_ARGS__)

Rate-limited DEBUG logging.

Definition at line 702 of file log/log.h.

log_debug_nth

#define log_debug_nth	(		n,
			fmt,
			...
	)		log_nth(DEBUG, n, fmt, ##__VA_ARGS__)

Log DEBUG message every nth call.

Definition at line 808 of file log/log.h.

log_debug_once

#define log_debug_once	(		fmt,
			...
	)		log_once(DEBUG, fmt, ##__VA_ARGS__)

Log DEBUG message exactly once.

Definition at line 833 of file log/log.h.

log_dev_every

#define log_dev_every	(		interval_us,
			fmt,
			...
	)		log_every(DEV, interval_us, fmt, ##__VA_ARGS__)

Rate-limited DEV logging.

Definition at line 699 of file log/log.h.

log_dev_nth

#define log_dev_nth	(		n,
			fmt,
			...
	)		log_nth(DEV, n, fmt, ##__VA_ARGS__)

Log DEV message every nth call.

Definition at line 805 of file log/log.h.

log_dev_once

#define log_dev_once	(		fmt,
			...
	)		log_once(DEV, fmt, ##__VA_ARGS__)

Log DEV message exactly once.

Definition at line 830 of file log/log.h.

log_error_every

#define log_error_every	(		interval_us,
			fmt,
			...
	)		log_every(ERROR, interval_us, fmt, ##__VA_ARGS__)

Rate-limited ERROR logging.

Definition at line 711 of file log/log.h.

log_error_nth

#define log_error_nth	(		n,
			fmt,
			...
	)		log_nth(ERROR, n, fmt, ##__VA_ARGS__)

Log ERROR message every nth call.

Definition at line 817 of file log/log.h.

log_error_once

#define log_error_once	(		fmt,
			...
	)		log_once(ERROR, fmt, ##__VA_ARGS__)

Log ERROR message exactly once.

Definition at line 842 of file log/log.h.

log_fatal_every

#define log_fatal_every	(		interval_us,
			fmt,
			...
	)		log_every(FATAL, interval_us, fmt, ##__VA_ARGS__)

Rate-limited FATAL logging.

Definition at line 714 of file log/log.h.

log_fatal_nth

#define log_fatal_nth	(		n,
			fmt,
			...
	)		log_nth(FATAL, n, fmt, ##__VA_ARGS__)

Log FATAL message every nth call.

Definition at line 820 of file log/log.h.

log_fatal_once

#define log_fatal_once	(		fmt,
			...
	)		log_once(FATAL, fmt, ##__VA_ARGS__)

Log FATAL message exactly once.

Definition at line 845 of file log/log.h.

log_info_every

#define log_info_every	(		interval_us,
			fmt,
			...
	)		log_every(INFO, interval_us, fmt, ##__VA_ARGS__)

Rate-limited INFO logging.

Definition at line 705 of file log/log.h.

log_info_nth

#define log_info_nth	(		n,
			fmt,
			...
	)		log_nth(INFO, n, fmt, ##__VA_ARGS__)

Log INFO message every nth call.

Definition at line 811 of file log/log.h.

log_info_once

#define log_info_once	(		fmt,
			...
	)		log_once(INFO, fmt, ##__VA_ARGS__)

Log INFO message exactly once.

Definition at line 836 of file log/log.h.

log_warn_every

#define log_warn_every	(		interval_us,
			fmt,
			...
	)		log_every(WARN, interval_us, fmt, ##__VA_ARGS__)

Rate-limited WARN logging.

Definition at line 708 of file log/log.h.

log_warn_nth

#define log_warn_nth	(		n,
			fmt,
			...
	)		log_nth(WARN, n, fmt, ##__VA_ARGS__)

Log WARN message every nth call.

Definition at line 814 of file log/log.h.

log_warn_once

#define log_warn_once	(		fmt,
			...
	)		log_once(WARN, fmt, ##__VA_ARGS__)

Log WARN message exactly once.

Definition at line 839 of file log/log.h.

Typedef Documentation

log_mmap_config_t

typedef struct log_mmap_config log_mmap_config_t

Definition at line 861 of file log/log.h.

Function Documentation

get_level_string_padded()

const char * get_level_string_padded

(

log_level_t

level

)

Get padded log level string (internal utility for formatting)

Parameters

level

Log level

Returns

Padded level string (5 chars: "DEBUG", "INFO ", "WARN ", "DEV ", "ERROR", "FATAL")

Note

Internal function - do not use directly in application code

Get padded log level string (internal utility for formatting)

Returns level names padded to 5 characters for visual alignment. Used consistently in both colored and plain text formatters to ensure grep pattern matching works correctly.

Parameters

level

Log level

Returns

Padded level string (e.g., "INFO ", "WARN ", "DEBUG")

Definition at line 149 of file log/log.c.

                                                       {
  const char *result;
  switch (level) {
  case LOG_INFO:
    result = "INFO "; // 5 chars: INFO + 1 space
    break;
  case LOG_WARN:
    result = "WARN "; // 5 chars: WARN + 1 space
    break;
  case LOG_DEV:
    result = "DEV  "; // 5 chars: DEV + 2 spaces
    break;
  case LOG_DEBUG:
    result = "DEBUG"; // 5 chars: DEBUG (no padding needed)
    break;
  case LOG_ERROR:
    result = "ERROR"; // 5 chars: ERROR (no padding needed)
    break;
  case LOG_FATAL:
    result = "FATAL"; // 5 chars: FATAL (no padding needed)
    break;
  default:
    result = "?????"; // Invalid level - return 5 question marks
  }
  // Verify length
  if (strlen(result) != 5) {
    fprintf(stderr, "ERROR: get_level_string_padded() returned non-5-char string: '%s' (len=%zu)\n", result,
            strlen(result));
  }
  return result;
}

References LOG_DEBUG, LOG_DEV, LOG_ERROR, LOG_FATAL, LOG_INFO, and LOG_WARN.

Referenced by log_template_apply().

log_console_impl()

void log_console_impl	(	log_level_t	level,
		const char *	file,
		int	line,
		const char *	func,
		const char *	message
	)

Definition at line 2120 of file log/log.c.

                                                                                                            {
  if (!message) {
    return;
  }
 
  int fd = terminal_choose_log_fd(level);
  if (fd < 0) {
    return;
  }
 
  // Check if JSON output is enabled (json_file >= 0 means enabled)
  int json_fd = atomic_load_int(&g_log.json_file);
  bool use_json = (json_fd >= 0);
 
  if (use_json) {
    // Use async-safe JSON formatter (safe for signal handlers)
    log_json_async_safe(fd, level, file, line, func, message);
  } else {
    // Text output to console using platform_write_all to handle partial writes
    size_t msg_len = strlen(message);
    platform_write_all(fd, (const uint8_t *)message, msg_len);
    if (msg_len == 0 || message[msg_len - 1] != '\n') {
      platform_write_all(fd, (const uint8_t *)"\n", 1);
    }
  }
}

References atomic_load_int(), log_json_async_safe(), platform_write_all(), and terminal_choose_log_fd().