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
	Heap-backed message waiting for the logging output thread. 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_TERMINAL_BUFFER_SIZE   16384
#define	LOG_TERMINAL_ENTRY_BUFFER_SIZE   (LOG_HEADER_BUFFER_SIZE + LOG_TERMINAL_BUFFER_SIZE)
#define	log_colored_msg(level, colored_message, plain_message)
#define	log_terminal_colored_msg(level, colored_message, plain_message)
#define	log_plain(...)
	Plain logging - writes to both log file and stderr without timestamps or log levels.
#define	log_plain_stderr(...)
	Plain logging to stderr with newline.
#define	log_plain_stdout(...)
	Plain logging to stdout with newline.
#define	log_plain_stderr_nonewline(...)
	Plain logging to stderr without newline - for interactive prompts.
#define	log_file(...)
	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)
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 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 a DEV message (most verbose, development only).
#define	log_debug(...)
	Log a DEBUG message.
#define	log_info(...)
	Log an INFO message.
#define	log_warn(...)
	Log a WARN message.
#define	log_error(...)
	Log an ERROR message.
#define	log_fatal(...)
	Log a FATAL message.
Rate-Limited Logging Macros
#define	log_dev_every(interval_us, fmt, ...)
	Rate-limited DEV logging.
#define	log_debug_every(interval_us, fmt, ...)
	Rate-limited DEBUG logging.
#define	log_info_every(interval_us, fmt, ...)
	Rate-limited INFO logging.
#define	log_warn_every(interval_us, fmt, ...)
	Rate-limited WARN logging.
#define	log_error_every(interval_us, fmt, ...)
	Rate-limited ERROR logging.
#define	log_fatal_every(interval_us, fmt, ...)
	Rate-limited FATAL logging.
Nth-Call Logging Macros
#define	log_dev_nth(n, fmt, ...)
	Log DEV message every nth call.
#define	log_debug_nth(n, fmt, ...)
	Log DEBUG message every nth call.
#define	log_info_nth(n, fmt, ...)
	Log INFO message every nth call.
#define	log_warn_nth(n, fmt, ...)
	Log WARN message every nth call.
#define	log_error_nth(n, fmt, ...)
	Log ERROR message every nth call.
#define	log_fatal_nth(n, fmt, ...)
	Log FATAL message every nth call.
Once-Only Logging Macros
#define	log_dev_once(fmt, ...)
	Log DEV message exactly once.
#define	log_debug_once(fmt, ...)
	Log DEBUG message exactly once.
#define	log_info_once(fmt, ...)
	Log INFO message exactly once.
#define	log_warn_once(fmt, ...)
	Log WARN message exactly once.
#define	log_error_once(fmt, ...)
	Log ERROR message exactly once.
#define	log_fatal_once(fmt, ...)
	Log FATAL message exactly once.

Typedefs
typedef struct color_scheme_t	color_scheme_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 ,   LOG_COLOR_WHITE = 8 }
	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_colored_msg_impl (log_level_t level, const char *file, int line, const char *func, const char *colored_message, const char *plain_message)
	Write semantically colored terminal text and an ANSI-free log equivalent.
void	log_terminal_colored_msg_impl (log_level_t level, const char *file, int line, const char *func, const char *colored_message, const char *plain_message)
	Write semantically colored terminal text without persistent logging.
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_level_color_for_output (log_color_t color, bool enabled)
const char **	log_get_color_array (void)
	Get the appropriate color array based on terminal capabilities.
const char *	log_get_foreground_color (void)
int	log_get_color_mode (void)
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_net_message (struct acip_transport *transport, 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_history_buffer (void)
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 )

Value:

log_console_impl((level), __FILE__, __LINE__, __func__, (message))

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

log_debug_every

#define log_debug_every	(		interval_us,
			fmt,
			... )

Value:

log_every(DEBUG, interval_us, fmt, ##__VA_ARGS__)

Rate-limited DEBUG logging.

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

Referenced by acip_handle_acds_packet(), acip_websocket_server_transport_create(), ascii_convert_with_buffers_stabilized(), audio_process_received_samples(), audio_ring_buffer_read(), client_audio_render_thread(), client_video_render_thread(), crypto_encrypt(), ffmpeg_decoder_read_audio_samples(), ffmpeg_encoder_write_frame(), h265_encode(), handle_audio_batch_packet(), handle_audio_opus_batch_packet(), handle_audio_opus_packet(), handle_image_frame_h265_packet(), handle_image_frame_packet(), media_source_read_audio(), media_source_read_video(), opus_codec_decode(), opus_codec_encode(), packet_decode_frame_data_buffer(), packet_send(), send_packet_secure(), session_display_encode_frame(), session_display_write_ascii_frame(), session_host_receive_packet(), session_pipeline_run_main(), session_render_loop(), term_renderer_feed(), terminal_fd_reader_next(), terminal_fd_writer_write(), threaded_send_image_frame_encoded(), threaded_send_packet(), and websocket_server_run().

log_debug_nth

#define log_debug_nth	(		n,
			fmt,
			... )

Value:

log_nth(DEBUG, n, fmt, ##__VA_ARGS__)

Log DEBUG message every nth call.

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

log_debug_once

#define log_debug_once	(		fmt,
			... )

Value:

log_once(DEBUG, fmt, ##__VA_ARGS__)

Log DEBUG message exactly once.

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

log_dev_every

#define log_dev_every	(		interval_us,
			fmt,
			... )

Value:

log_every(DEV, interval_us, fmt, ##__VA_ARGS__)

Rate-limited DEV logging.

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

Referenced by acip_server_receive_and_dispatch(), audio_process_received_samples(), audio_ring_buffer_read(), client_audio_render_thread(), client_video_render_thread(), create_mixed_ascii_frame_for_client(), mixer_process_excluding_source(), session_display_write_ascii_frame(), session_render_loop(), video_frame_commit(), and websocket_transport_send().

log_dev_nth

#define log_dev_nth	(		n,
			fmt,
			... )

Value:

log_nth(DEV, n, fmt, ##__VA_ARGS__)

Log DEV message every nth call.

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

log_dev_once

#define log_dev_once	(		fmt,
			... )

Value:

log_once(DEV, fmt, ##__VA_ARGS__)

Log DEV message exactly once.

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

log_error_every

#define log_error_every	(		interval_us,
			fmt,
			... )

Value:

log_every(ERROR, interval_us, fmt, ##__VA_ARGS__)

Rate-limited ERROR logging.

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

Referenced by client_audio_pipeline_capture(), client_audio_pipeline_playback(), client_audio_render_thread(), crypto_decrypt(), mutex_stack_detect_deadlocks(), and session_pipeline_run_main().

log_error_nth

#define log_error_nth	(		n,
			fmt,
			... )

Value:

log_nth(ERROR, n, fmt, ##__VA_ARGS__)

Log ERROR message every nth call.

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

log_error_once

#define log_error_once	(		fmt,
			... )

Value:

log_once(ERROR, fmt, ##__VA_ARGS__)

Log ERROR message exactly once.

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

log_fatal_every

#define log_fatal_every	(		interval_us,
			fmt,
			... )

Value:

log_every(FATAL, interval_us, fmt, ##__VA_ARGS__)

Rate-limited FATAL logging.

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

log_fatal_nth

#define log_fatal_nth	(		n,
			fmt,
			... )

Value:

log_nth(FATAL, n, fmt, ##__VA_ARGS__)

Log FATAL message every nth call.

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

log_fatal_once

#define log_fatal_once	(		fmt,
			... )

Value:

log_once(FATAL, fmt, ##__VA_ARGS__)

Log FATAL message exactly once.

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

log_info_every

#define log_info_every	(		interval_us,
			fmt,
			... )

Value:

log_every(INFO, interval_us, fmt, ##__VA_ARGS__)

Rate-limited INFO logging.

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

log_info_nth

#define log_info_nth	(		n,
			fmt,
			... )

Value:

log_nth(INFO, n, fmt, ##__VA_ARGS__)

Log INFO message every nth call.

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

log_info_once

#define log_info_once	(		fmt,
			... )

Value:

log_once(INFO, fmt, ##__VA_ARGS__)

Log INFO message exactly once.

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

log_warn_every

#define log_warn_every	(		interval_us,
			fmt,
			... )

Value:

log_every(WARN, interval_us, fmt, ##__VA_ARGS__)

Rate-limited WARN logging.

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

Referenced by ansi_rle_add_pixel(), audio_process_received_samples(), audio_ring_buffer_write(), client_audio_pipeline_process_duplex(), client_video_render_thread(), create_mixed_ascii_frame_for_client(), ffmpeg_decoder_read_audio_samples(), media_source_read_audio(), mixer_process_excluding_source(), send_packet_secure(), session_display_encode_frame(), session_display_render_frame(), session_display_write_ascii_frame(), and session_host_inject_audio().

log_warn_nth

#define log_warn_nth	(		n,
			fmt,
			... )

Value:

log_nth(WARN, n, fmt, ##__VA_ARGS__)

Log WARN message every nth call.

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

log_warn_once

#define log_warn_once	(		fmt,
			... )

Value:

log_once(WARN, fmt, ##__VA_ARGS__)

Log WARN message exactly once.

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

Referenced by audio_processor_create().

Typedef Documentation

log_mmap_config_t

typedef struct log_mmap_config log_mmap_config_t

Definition at line 908 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 183 of file 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) {
    log_terminal_printf(STDERR_FILENO, "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 2334 of file log.c.

                                                                                                            {
  if (!message) {
    return;
  }
 
  int fd = terminal_choose_log_fd(level);
  if (fd < 0) {
    return;
  }
 
  // Presentation owns terminal output, but never changes the caller's logging preference.
  if (ui_controller_is_presenting() && (ui_controller_is_owner() || platform_isatty(fd))) {
    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);
    ui_controller_write(fd, message, msg_len);
    if (msg_len == 0 || message[msg_len - 1] != '\n') {
      ui_controller_write(fd, "\n", 1);
    }
  }
}

References log_json_async_safe(), terminal_choose_log_fd(), ui_controller_is_owner(), ui_controller_is_presenting(), and ui_controller_write().

log_get_history_buffer()

session_log_buffer_t * log_get_history_buffer

(

void

)

Borrowed history retained from log_init through log_system_destroy, independent of screens.

Definition at line 565 of file log.c.

                                                   {
  return g_history;
}

Referenced by log_search_gather_and_filter_logs(), terminal_screen_log_init(), and ui_session_create().