Logging System

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

Files
file	apple.c
	Apple unified logging (os_log) integration.
file	colorize.c
	Log message colorization for terminal output.
file	format.c
	Log format parser implementation.
file	json.c
	📝 JSON structured logging output using yyjson
file	log.c
	📝 Multi-level logging with terminal color support, file rotation, and async output
file	mmap.c
	Lock-free memory-mapped text logging implementation.
file	named.c
	Format named objects in log messages (replaces hex addresses with type/name descriptions)
file	wasm.c
	WASM logging support for routing to browser console.
file	colorize.h
	Log message colorization for terminal output.
file	json.h
	📝 JSON structured logging output
file	log.h
	📝 Logging API with multiple log levels and terminal output control
file	mmap.h
	Lock-free memory-mapped text logging with crash safety.
file	named.h
	Format named objects in log messages (replaces hex addresses with type/name descriptions)
file	types.h
	Log level types and constants.

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_BIT(n)   (1ULL << (n))
	Logging bit conversion.
#define	LOG_CLIENT_IMPL(client, level, fmt, ...)
#define	log_debug_client(client, fmt, ...)   LOG_CLIENT_IMPL(client, LOG_DEBUG, fmt, ##__VA_ARGS__)
	Server sends DEBUG log message to client.
#define	log_info_client(client, fmt, ...)   LOG_CLIENT_IMPL(client, LOG_INFO, fmt, ##__VA_ARGS__)
	Server sends INFO log message to client.
#define	log_warn_client(client, fmt, ...)   LOG_CLIENT_IMPL(client, LOG_WARN, fmt, ##__VA_ARGS__)
	Server sends WARN log message to client.
#define	log_error_client(client, fmt, ...)   LOG_CLIENT_IMPL(client, LOG_ERROR, fmt, ##__VA_ARGS__)
	Server sends ERROR log message to client.
#define	log_fatal_client(client, fmt, ...)   LOG_CLIENT_IMPL(client, LOG_FATAL, fmt, ##__VA_ARGS__)
	Server sends FATAL log message to client.
#define	LOG_SERVER_IMPL(sockfd, crypto_ctx, level, fmt, ...)
#define	log_debug_server(sockfd, crypto_ctx, fmt, ...)    LOG_SERVER_IMPL(sockfd, crypto_ctx, LOG_DEBUG, fmt, ##__VA_ARGS__)
	Client sends DEBUG log message to server.
#define	log_info_server(sockfd, crypto_ctx, fmt, ...)   LOG_SERVER_IMPL(sockfd, crypto_ctx, LOG_INFO, fmt, ##__VA_ARGS__)
	Client sends INFO log message to server.
#define	log_warn_server(sockfd, crypto_ctx, fmt, ...)   LOG_SERVER_IMPL(sockfd, crypto_ctx, LOG_WARN, fmt, ##__VA_ARGS__)
	Client sends WARN log message to server.
#define	log_error_server(sockfd, crypto_ctx, fmt, ...)    LOG_SERVER_IMPL(sockfd, crypto_ctx, LOG_ERROR, fmt, ##__VA_ARGS__)
	Client sends ERROR log message to server.
#define	log_fatal_server(sockfd, crypto_ctx, fmt, ...)    LOG_SERVER_IMPL(sockfd, crypto_ctx, LOG_FATAL, fmt, ##__VA_ARGS__)
	Client sends FATAL log message to server.

Typedefs
typedef struct color_scheme_t	color_scheme_t
typedef struct session_log_buffer	session_log_buffer_t
typedef enum remote_log_direction	remote_log_direction_t
	Remote log packet direction enumeration.

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...
enum	log_level_t {   ASCIICHAT_LOG_DEV = 0 , ASCIICHAT_LOG_DEBUG , ASCIICHAT_LOG_INFO , ASCIICHAT_LOG_WARN ,   ASCIICHAT_LOG_ERROR , ASCIICHAT_LOG_FATAL }
	Logging levels enumeration. More...
enum	remote_log_direction { REMOTE_LOG_DIRECTION_UNKNOWN = 0 , REMOTE_LOG_DIRECTION_SERVER_TO_CLIENT = 1 , REMOTE_LOG_DIRECTION_CLIENT_TO_SERVER = 2 }
	Remote log packet direction enumeration. More...

Functions
log_template_t *	log_template_parse (const char *format_str, bool console_only)
	Parse a format string into compiled format structure.
void	log_template_free (log_template_t *format)
	Free compiled format structure.
int	log_template_apply (const log_template_t *format, char *buf, size_t buf_size, log_level_t level, const char *timestamp, const char *file, int line, const char *func, uint64_t tid, const char *message, bool use_colors, uint64_t time_nanoseconds)
	Apply format to a log entry and write result to buffer.
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.
void *	log_get_template (void)
	Get the current log format template (opaque pointer)
int	log_named_format_message (const char *message, char *output, size_t output_size)
	Format hex addresses in a message as named object descriptions.
const char *	log_named_format_or_original (const char *message)
	Format named objects in a message (thread-local buffer)
const char *	colorize_named_string (const char *name_str)
	Colorize a "type/name" string for display.

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.

Detailed Description

📝 Logging API with multiple log levels and terminal output control

This header provides a comprehensive logging system with:

• Multiple log levels (DEV, DEBUG, INFO, WARN, ERROR, FATAL)
• File and terminal output with automatic color coding
• Terminal capability detection (16-color, 256-color, truecolor)
• Rate-limited logging macros for high-frequency logging
• Thread-safe logging operations
• Automatic log file rotation when size limit is reached

Note

In debug builds, log macros include file/line/function information. In release builds, this information is omitted.

This module formats named objects in log messages by scanning for hex addresses and replacing them with friendly descriptions from the named object registry when available.

For example:

• Input: "Locked 0x7f1234567890 successfully"
• Output: "Locked mutex: recv_mutex.2 (0x7f1234567890) successfully"

When an address is not registered, it's left unchanged.

Logging Subsystem Architecture

Overview

The ascii-chat logging subsystem provides a comprehensive, high-performance logging system designed for terminal-based applications with multiple concurrent threads and real-time constraints.

Key features:

• Six severity levels (DEV, DEBUG, INFO, WARN, ERROR, FATAL)
• Simultaneous file and terminal output with automatic color coding
• Lock-free memory-mapped logging for high-performance scenarios
• PCRE2-based regex filtering with context display
• Flexible format customization for both console and file output
• Rate-limited and call-count-based logging macros
• Thread-safe logging with optional terminal locking for interactive prompts

System Architecture

The logging system is organized into modular layers:

┌──────────────────────────────────────────────────────────┐
│ Application Code (log_info, log_warn, etc.)              │
└────────────────────┬─────────────────────────────────────┘
                     │
┌────────────────────▼─────────────────────────────────────┐
│ lib/log/logging.c - Core logging system                  │
│ - log_init, log_destroy, log_set_level                   │
│ - log_msg, log_terminal_msg, log_plain_msg               │
│ - Terminal locking for interactive prompts               │
└──┬──────────────────┬───────────────────┬────────────────┘
   │                  │                   │
┌──▼──────────┐  ┌───▼──────────┐  ┌────▼─────────────────┐
│ Output      │  │ Formatting   │  │ Filtering & Colors   │
│             │  │              │  │                      │
│ - File I/O  │  │- format.c    │  │ - grep.c (PCRE2)     │
│ - mmap.c    │  │- Custom      │  │ - colorize.c         │
│ - Buffering │  │  templates   │  │ - Terminal detection │
└─────────────┘  └──────────────┘  └─────────────────────┘

Log Levels

The logging system defines six severity levels, from most to least verbose:

Level	Value	Purpose	Compile-Time Stripping	Example
DEV	0	Development/trace logs	Strippable in release	Frame timing, buffer state, handshake details
DEBUG	1	Debug diagnostic messages	Strippable in release	Algorithm decisions, state transitions
INFO	2	Informational messages	Strippable via LOG_COMPILE_LEVEL=LOG_WARN	Initialization, connection events
WARN	3	Warning conditions	Strippable via LOG_COMPILE_LEVEL=LOG_ERROR	Recoverable errors, performance concerns
ERROR	4	Error conditions	Strippable via LOG_COMPILE_LEVEL=LOG_FATAL	Failed operations, broken connections
FATAL	5	Fatal errors (program exit)	Never stripped	Out of memory, crypto failure

Key characteristics:

• DEV/DEBUG are compile-time strippable, allowing verbose debug builds while keeping release builds small. Override with LOG_COMPILE_LEVEL=LOG_DEV to keep them.
• INFO/WARN use log_info_every() and log_warn_every() for high-frequency paths (video/audio loops) to avoid log spam while maintaining visibility.
• ERROR/FATAL go to stderr; others go to stdout (unless force_stderr is enabled). This keeps stdout clean for client mode where ASCII art is rendered.

Macro API:

log_dev("Development message");           // Compile-time strippable
log_debug("Debug message");               // Compile-time strippable
log_info("Info message");                 // Production-safe
log_warn("Warning: %d", value);           // Warning condition
log_error("Error: %s", error_msg);        // Error condition
log_fatal("Fatal: exiting");              // Program termination

Message Formatting

The logging system uses a templated formatting system that allows customization of message output while maintaining performance.

Default format (debug mode):

[14:30:45] [DEBUG] [tid:1234] src/client.c:42 in client_init(): Starting client

Default format (release mode):

[14:30:45] [DEBUG] Starting client

Custom format support via log_set_format():

// Compact format
log_set_format("[%time(%H:%M:%S)] [%level_aligned] %message", false);
 
// Detailed format with colors
log_set_format("%color(LOG_DEBUG, [%level_aligned]) %message", false);
 
// Relative file paths
log_set_format("[%time(%H:%M:%S.%microseconds)] %file_relative:%line %message", false);

Format specifiers:

• time(fmt) - Time in strftime format (e.g., H:M:S, Y-m-d)
• level - Log level name (DEBUG, INFO, WARN, ERROR)
• level_aligned - Log level padded to 5 chars (for alignment)
• file - Full file path (debug mode only)
• file_relative - Relative file path (debug mode only)
• line - Line number (debug mode only)
• func - Function name (debug mode only)
• tid - Thread ID (debug mode only)
• message - Log message body
• microseconds - Microsecond component of timestamp
• nanoseconds - Nanosecond component of timestamp

Console-only formatting: By passing console_only=true to log_set_format(), the custom format applies only to terminal output. File logging uses the default format, which is useful for preserving readable logs while having fancy terminal colors.

Log Filtering with Grep

The filtering system uses PCRE2 regex to dynamically filter log output, with support for highlighting matched text.

CLI usage:

# Plain regex - matches "error" or "warning" case-insensitive
./ascii-chat server --grep "/error|warning/i"
 
# With context - show 2 lines before and after match
./ascii-chat client --grep "/handshake/C2"
 
# Fixed string search (no regex)
./ascii-chat server --grep "/DEBUG/F"
 
# Multiple patterns - OR logic
./ascii-chat client --grep "/error/i" --grep "/connection/i"
 
# Invert match - show everything EXCEPT matches
./ascii-chat server --grep "/debug|trace/iI"

Supported flags:

• i - Case-insensitive matching
• m - Multiline mode (^ and $ match line boundaries)
• s - Dotall mode (. matches newlines)
• x - Extended regex (ignore whitespace in pattern)
• F - Fixed string literal (no regex, exact match)
• g - Global highlighting (highlight all matches in line)
• I - Invert match (show lines that DON'T match)
• B<n> - Show n lines before match (context)
• A<n> - Show n lines after match (context)
• C<n> - Show n lines before and after (context)

Filter performance:

• Each pattern is compiled once at startup (not on every log)
• Matching uses thread-local storage (no allocations per match)
• Matched text is highlighted with yellow background
• Filtering is applied after formatting, so matches include colored output

Output Routing

The logging system routes messages to different outputs based on level and configuration.

Default routing:

• DEV, DEBUG, INFO → stdout (unless force_stderr enabled)
• WARN, ERROR, FATAL → stderr
• All levels → log file (if configured)

Client mode special handling: Client mode keeps stdout clean for ASCII art rendering by enabling force_stderr:

log_init("client.log", LOG_DEBUG, true, false);  // force_stderr=true

This routes all log messages (including INFO) to stderr, keeping stdout available.

Output control functions:

log_set_terminal_output(false);  // Disable all terminal output
log_set_force_stderr(true);      // Force all logs to stderr
log_disable_file_output();       // Disable file output, use stderr fallback

Buffering for interactive prompts: When prompting for user input (passwords, yes/no questions), use terminal locking to ensure clean output:

bool prev = log_lock_terminal();      // Lock out other threads
fputs("Enter password: ", stdout);
// user types input
log_unlock_terminal(prev);             // Unlock and flush buffered logs

Performance Characteristics

The logging system is designed for low-latency, high-throughput scenarios common in real-time multimedia applications.

Lock-free mmap mode (recommended for production):

• File output: Lock-free atomic operations on mmap'd memory
• Terminal output: Atomic fprintf/fwrite (no mutex held)
• No contention: Multiple threads can log simultaneously without blocking
• Crash-safe: Text written directly to file, readable after crash
• Performance: ~5-10 microseconds per log message (x86-64)

Mutex-based mode (fallback):

• Single mutex protects both file and terminal output
• Suitable for applications with low logging volume
• Fallback when mmap initialization fails

Optimizations for high-frequency logging:

// Log at most once per second (1,000,000 microseconds)
log_info_every(1000000, "Frame buffer utilization: %d%%", percent);
 
// Log every 60th call (for 60 FPS, logs ~1x per second)
log_debug_nth(60, "Processing frame %zu", frame_count);
 
// Log exactly once per session
log_info_once("Client connected from %s", client_address);

Memory usage:

• Terminal buffer: 64 KB maximum (256 buffered entries)
• Single message: 4 KB maximum (truncated if exceeded)
• File buffer: Variable (mmap mode) or unbuffered
• Per-format specifier: ~100 bytes compiled size

CPU characteristics:

• Message formatting: ~2-5% of CPU in typical scenarios
• PCRE2 filtering: <1% overhead for simple patterns
• Terminal color detection: One-time cost at startup
• Rate-limited macros: Atomic operations only (no syscalls)

Appropriate Use Cases

Good use cases for logging:

• Connection lifecycle events (connected, disconnected, handshake)
• Configuration changes or mode transitions
• Recoverable errors and retry attempts
• Performance metrics and statistics (with rate limiting)
• Authentication and security events
• Frame drops or quality degradation
• Shader compilation or resource loading

Poor use cases (leads to spam):

• Every video frame processed (use log_nth or log_every)
• Every byte received (use log_every instead)
• Every mutex acquisition/release (use log_once or don't log)
• Every packet in a high-frequency network loop (use sampling)

Performance-sensitive code patterns:

// ❌ BAD: 60 logs per second (60 FPS scenario)
void process_frame(void) {
    log_debug("Processing frame %zu", frame_count);
}
 
// ✅ GOOD: 1 log per second using rate limiting
void process_frame(void) {
    log_debug_every(1000000, "Processed %zu frames", frame_count);
}
 
// ✅ GOOD: 1 log per 60 frames using call counting
void process_frame(void) {
    log_debug_nth(60, "Processing frames (batch complete)");
}

Error Handling in Logs

The logging system integrates with the application's error tracking system. For critical failures, use SET_ERRNO() to capture error context:

// Set errno with context message
if (crypto_failed) {
    log_error("Crypto handshake failed: %s", reason);
    return SET_ERRNO(ERROR_CRYPTO_FAILED, "Key exchange timeout");
}
 
// Check and log errors from other functions
asciichat_error_t result = process_network_packet();
if (result != ASCIICHAT_OK) {
    log_error("Network error: %d", result);
    return result;
}

Initialization and Shutdown

Standard initialization (debug mode):

log_init("output.log",           // Log file path
         LOG_DEBUG,              // Minimum log level
         false,                  // force_stderr: no (INFO to stdout)
         false);                 // use_mmap: no (use mutex-based)

Production initialization (server mode with mmap):

log_init("/var/log/asciichat.log",
         LOG_INFO,               // Only INFO and above
         false,                  // Normal routing
         true);                  // use_mmap: yes (lock-free)
 
// Optionally upgrade to lock-free mode
log_enable_mmap("/var/log/asciichat.log");

Client mode (keep stdout clean):

log_init("client.log",
         LOG_DEBUG,
         true,                   // force_stderr: yes
         false);

Graceful shutdown:

// Disable console output, keep file logging for shutdown messages
log_shutdown_begin();
log_info("Shutting down server");
log_info("All clients disconnected");
log_shutdown_end();
 
// Destroy logging system
log_destroy();

Thread Safety

All logging functions are thread-safe:

• log_msg() - Safe to call from any thread
• log_set_level() - Safe to call while logging active
• log_lock_terminal() - Safe for nested calls
• Rate-limited macros - Atomic operations ensure correctness

Interactive prompt pattern:

// Thread 1 (main thread) - handle user input
bool prev = log_lock_terminal();
char *password = getpass("Password: ");
log_unlock_terminal(prev);
// Now buffered logs from other threads are flushed
 
// Thread 2 (network thread) - can log normally
log_info("Received %d bytes", packet_size);  // Buffered during lock

Debugging with Logs

Enable verbose logging:

# -V increases verbosity (can be stacked)
./ascii-chat --log-level debug -V server
./ascii-chat -VVV client  # Maximum verbosity with DEV level

Log to file for analysis:

./ascii-chat --log-file debug.log server
# Or using CLI options
./ascii-chat --log-level dev --log-file debug.log server

Filter logs during execution:

# Watch crypto handshake
./ascii-chat --log-level debug server --grep "/handshake|crypto/ig"
 
# See only errors and warnings with context
./ascii-chat client --grep "/error|warn/iC3"
 
# Monitor specific component
./ascii-chat server --grep "/\\[AUDIO\\]/i"

Post-mortem analysis (from log file):

# Check for errors
grep -i error debug.log
 
# Find performance issues
grep "timeout\|delay\|slow" debug.log
 
# Track connection lifecycle
grep "connected\|disconnected\|handshake" debug.log

Code Examples

Basic logging:

log_info("Server started on port %d", 27224);
log_warn("Connection timeout after %d seconds", timeout);
log_error("Failed to bind socket: %s", strerror(errno));

Conditional logging:

if (verbose_mode) {
    log_debug("Processing frame %zu in %llu µs", frame_num, elapsed_us);
}
 
// Or use compile-time stripping for release builds
log_dev("Frame pipeline state: input=%d, processing=%d, output=%d",
        input_queue, process_queue, output_queue);

Labeled output:

log_labeled("[INIT]", LOG_COLOR_DEBUG, "Initializing subsystem");
log_labeled("[ERROR]", LOG_COLOR_ERROR, "Failed to create thread");

Raw output (no formatting):

// Write to file only (no terminal)
log_file("Raw packet dump follows:");
log_file("  00 01 02 03 04 05 06 07");
 
// Plain message to stderr
log_plain_stderr("Critical condition detected");

Network logging:

// Log to remote server, file, and terminal simultaneously
log_net_message(server_socket, crypto_ctx, LOG_INFO, REMOTE_LOG_OUTBOUND,
                NULL, 0, NULL, "Video quality: %d%% (%d kbps)", quality, bitrate);

Macro Definition Documentation

DEFAULT_LOG_LEVEL

#define DEFAULT_LOG_LEVEL   LOG_DEBUG

#include <log.h>

Default log level for debug builds (DEBUG and above)

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

log_as

#define log_as	(		level,
			...
	)		log_msg(level, __FILE__, __LINE__, __func__, __VA_ARGS__)

#include <log.h>

Log a message given the associated level.

Parameters

level	The log level to use
...	Format string and arguments (printf-style)

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

LOG_ATOMIC_UINT64

#define LOG_ATOMIC_UINT64   atomic_t

#include <log.h>

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

LOG_ATOMIC_UINT64_INIT

#define LOG_ATOMIC_UINT64_INIT

(

val

)

#include <log.h>

Value:

  {.impl = (uint64_t)0,                                                                                                \
   .last_store_time_ns = (uint64_t)0,                                                                                  \
   .last_load_time_ns = (uint64_t)0,                                                                                   \
   .store_count = (uint64_t)0,                                                                                         \
   .load_count = (uint64_t)0,                                                                                          \
   .cas_count = (uint64_t)0,                                                                                           \
   .cas_success_count = (uint64_t)0,                                                                                   \
   .fetch_count = (uint64_t)0}

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

  {.impl = (uint64_t)0,                                                                                                \
   .last_store_time_ns = (uint64_t)0,                                                                                  \
   .last_load_time_ns = (uint64_t)0,                                                                                   \
   .store_count = (uint64_t)0,                                                                                         \
   .load_count = (uint64_t)0,                                                                                          \
   .cas_count = (uint64_t)0,                                                                                           \
   .cas_success_count = (uint64_t)0,                                                                                   \
   .fetch_count = (uint64_t)0}

LOG_BIT

#define LOG_BIT

(

n

)

(1ULL << (n))

#include <types.h>

Logging bit conversion.

Converts a log level to a bit flag. Used to pack multiple log levels in the same number (array of flags).

Definition at line 19 of file types.h.

LOG_CLIENT_IMPL

#define LOG_CLIENT_IMPL	(		client,
			level,
			fmt,
			...
	)

#include <log.h>

Value:

  do {                                                                                                                 \
    if ((client)->crypto_initialized) {                                                                                \
      const struct crypto_context_t *_ctx = crypto_handshake_get_context(&(client)->crypto_handshake_ctx);             \
      log_net_message((client)->socket, _ctx, level, REMOTE_LOG_DIRECTION_SERVER_TO_CLIENT, __FILE__, __LINE__,        \
                      __func__, fmt, ##__VA_ARGS__);                                                                   \
    }                                                                                                                  \
  } while (0)

Definition at line 55 of file network/log.h.

     {                                                                                                                 \
    if ((client)->crypto_initialized) {                                                                                \
      const struct crypto_context_t *_ctx = crypto_handshake_get_context(&(client)->crypto_handshake_ctx);             \
      log_net_message((client)->socket, _ctx, level, REMOTE_LOG_DIRECTION_SERVER_TO_CLIENT, __FILE__, __LINE__,        \
                      __func__, fmt, ##__VA_ARGS__);                                                                   \
    }                                                                                                                  \
  } while (0)

log_debug

#define log_debug

(

...

)

log_only(LOG_BIT(LOG_DEBUG), LOG_DEBUG, __VA_ARGS__)

#include <log.h>

Log a DEBUG message.

Parameters

...	Format string and arguments (printf-style)

Note

DEBUG messages are stripped at compile-time in release builds.

In debug builds, includes file/line/function.

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

log_debug_client

#define log_debug_client	(		client,
			fmt,
			...
	)		LOG_CLIENT_IMPL(client, LOG_DEBUG, fmt, ##__VA_ARGS__)

#include <log.h>

Server sends DEBUG log message to client.

Definition at line 66 of file network/log.h.

log_debug_server

#define log_debug_server	(		sockfd,
			crypto_ctx,
			fmt,
			...
	)		LOG_SERVER_IMPL(sockfd, crypto_ctx, LOG_DEBUG, fmt, ##__VA_ARGS__)

#include <log.h>

Client sends DEBUG log message to server.

Definition at line 92 of file network/log.h.

log_dev

#define log_dev

(

...

)

log_only(LOG_BIT(LOG_DEV), LOG_DEV, __VA_ARGS__)

#include <log.h>

Log a DEV message (most verbose, development only)

Parameters

...	Format string and arguments (printf-style)

Note

DEV messages are stripped at compile-time in release builds.

In debug builds, includes file/line/function.

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

log_error

#define log_error

(

...

)

log_only(LOG_BIT(LOG_ERROR), LOG_ERROR, __VA_ARGS__)

#include <log.h>

Log an ERROR message.

Parameters

...	Format string and arguments (printf-style)

Note

ERROR messages can be stripped via LOG_COMPILE_LEVEL=LOG_FATAL.

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

log_error_client

#define log_error_client	(		client,
			fmt,
			...
	)		LOG_CLIENT_IMPL(client, LOG_ERROR, fmt, ##__VA_ARGS__)

#include <log.h>

Server sends ERROR log message to client.

Definition at line 75 of file network/log.h.

log_error_server

#define log_error_server	(		sockfd,
			crypto_ctx,
			fmt,
			...
	)		LOG_SERVER_IMPL(sockfd, crypto_ctx, LOG_ERROR, fmt, ##__VA_ARGS__)

#include <log.h>

Client sends ERROR log message to server.

Definition at line 102 of file network/log.h.

log_every

#define log_every	(		log_level,
			interval_us,
			fmt,
			...
	)

#include <log.h>

Value:

  do {                                                                                                                 \
    static LOG_ATOMIC_UINT64 _log_every_last_time = LOG_ATOMIC_UINT64_INIT(0);                                         \
    uint64_t _log_every_now = platform_get_monotonic_time_us();                                                        \
    uint64_t _log_every_last = atomic_load_u64(&_log_every_last_time);                                                 \
    if (_log_every_now - _log_every_last >= (uint64_t)(interval_us)) {                                                 \
      if (atomic_cas_u64(&_log_every_last_time, &_log_every_last, _log_every_now)) {                                   \
        log_msg(LOG_##log_level, __FILE__, __LINE__, __func__, fmt, ##__VA_ARGS__);                                    \
      }                                                                                                                \
    }                                                                                                                  \
  } while (0)

Rate-limited logging macro (thread-safe)

Logs at most once per specified time interval. Useful for threads that have an FPS and functions they call to prevent spammy logs.

Parameters

log_level	Log level (DEV, DEBUG, INFO, WARN, ERROR, FATAL)
interval_us	Minimum microseconds between log messages
fmt	Format string (printf-style)
...	Format arguments

Note

Each call site maintains its own static atomic timer, so different call sites can log independently. Thread-safe via atomic compare-exchange.

Uses platform_get_monotonic_time_us() for cross-platform time.

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

     {                                                                                                                 \
    static LOG_ATOMIC_UINT64 _log_every_last_time = LOG_ATOMIC_UINT64_INIT(0);                                         \
    uint64_t _log_every_now = platform_get_monotonic_time_us();                                                        \
    uint64_t _log_every_last = atomic_load_u64(&_log_every_last_time);                                                 \
    if (_log_every_now - _log_every_last >= (uint64_t)(interval_us)) {                                                 \
      if (atomic_cas_u64(&_log_every_last_time, &_log_every_last, _log_every_now)) {                                   \
        log_msg(LOG_##log_level, __FILE__, __LINE__, __func__, fmt, ##__VA_ARGS__);                                    \
      }                                                                                                                \
    }                                                                                                                  \
  } while (0)

log_fatal

#define log_fatal

(

...

)

log_only(LOG_BIT(LOG_FATAL), LOG_FATAL, __VA_ARGS__)

#include <log.h>

Log a FATAL message.

Parameters

...	Format string and arguments (printf-style)

Note

FATAL messages are never stripped (always compiled in).

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

log_fatal_client

#define log_fatal_client	(		client,
			fmt,
			...
	)		LOG_CLIENT_IMPL(client, LOG_FATAL, fmt, ##__VA_ARGS__)

#include <log.h>

Server sends FATAL log message to client.

Definition at line 78 of file network/log.h.

log_fatal_server

#define log_fatal_server	(		sockfd,
			crypto_ctx,
			fmt,
			...
	)		LOG_SERVER_IMPL(sockfd, crypto_ctx, LOG_FATAL, fmt, ##__VA_ARGS__)

#include <log.h>

Client sends FATAL log message to server.

Definition at line 106 of file network/log.h.

log_file

#define log_file

(

...

)

log_file_msg(__VA_ARGS__)

#include <log.h>

File-only logging - writes to log file only, no stderr output.

Parameters

...	Format string and arguments (printf-style)

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

LOG_HEADER_BUFFER_SIZE

#define LOG_HEADER_BUFFER_SIZE   512

#include <log.h>

Maximum size of a log header (timestamp, level, file:line:func)

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

log_info

#define log_info

(

...

)

log_only(LOG_BIT(LOG_INFO), LOG_INFO, __VA_ARGS__)

#include <log.h>

Log an INFO message.

Parameters

...	Format string and arguments (printf-style)

Note

INFO messages can be stripped via LOG_COMPILE_LEVEL=LOG_WARN.

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

log_info_client

#define log_info_client	(		client,
			fmt,
			...
	)		LOG_CLIENT_IMPL(client, LOG_INFO, fmt, ##__VA_ARGS__)

#include <log.h>

Server sends INFO log message to client.

Definition at line 69 of file network/log.h.

log_info_server

#define log_info_server	(		sockfd,
			crypto_ctx,
			fmt,
			...
	)		LOG_SERVER_IMPL(sockfd, crypto_ctx, LOG_INFO, fmt, ##__VA_ARGS__)

#include <log.h>

Client sends INFO log message to server.

Definition at line 96 of file network/log.h.

LOG_MMAP_MSG_BUFFER_SIZE

#define LOG_MMAP_MSG_BUFFER_SIZE   1024

#include <log.h>

Maximum size of a log message in mmap mode.

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

LOG_MSG_BUFFER_SIZE

#define LOG_MSG_BUFFER_SIZE   4096

#include <log.h>

Maximum size of a single log message (including formatting)

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

log_nth

#define log_nth	(		log_level,
			n,
			fmt,
			...
	)

#include <log.h>

Value:

  do {                                                                                                                 \
    static LOG_ATOMIC_UINT64 _log_nth_counter = LOG_ATOMIC_UINT64_INIT(0);                                             \
    uint64_t _log_nth_count = atomic_load_u64(&_log_nth_counter);                                                      \
    uint64_t _log_nth_new = _log_nth_count + 1;                                                                        \
    atomic_store_u64(&_log_nth_counter, _log_nth_new);                                                                 \
    if (_log_nth_new % (uint64_t)(n) == 0) {                                                                           \
      log_msg(LOG_##log_level, __FILE__, __LINE__, __func__, fmt, ##__VA_ARGS__);                                      \
    }                                                                                                                  \
  } while (0)

Log every nth call to this code location (thread-safe)

Logs a message every nth time the code is executed. Useful for logging periodic events in tight loops without spamming the log. For example, log_nth(INFO, 1000, "Processed items") logs every 1000 calls.

Each call site maintains its own static counter, so different call sites can log independently at different frequencies.

Parameters

log_level	Log level (DEV, DEBUG, INFO, WARN, ERROR, FATAL)
n	Log every nth call (1 = every call, 2 = every 2nd call, etc.)
fmt	Format string (printf-style)
...	Format arguments

Note

Thread-safe via atomic fetch_add.

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

     {                                                                                                                 \
    static LOG_ATOMIC_UINT64 _log_nth_counter = LOG_ATOMIC_UINT64_INIT(0);                                             \
    uint64_t _log_nth_count = atomic_load_u64(&_log_nth_counter);                                                      \
    uint64_t _log_nth_new = _log_nth_count + 1;                                                                        \
    atomic_store_u64(&_log_nth_counter, _log_nth_new);                                                                 \
    if (_log_nth_new % (uint64_t)(n) == 0) {                                                                           \
      log_msg(LOG_##log_level, __FILE__, __LINE__, __func__, fmt, ##__VA_ARGS__);                                      \
    }                                                                                                                  \
  } while (0)

log_once

#define log_once	(		log_level,
			fmt,
			...
	)

#include <log.h>

Value:

  do {                                                                                                                 \
    static LOG_ATOMIC_UINT64 _log_once_counter = LOG_ATOMIC_UINT64_INIT(0);                                            \
    uint64_t _log_once_count = atomic_load_u64(&_log_once_counter);                                                    \
    if (_log_once_count == 0) {                                                                                        \
      atomic_store_u64(&_log_once_counter, 1);                                                                         \
      log_msg(LOG_##log_level, __FILE__, __LINE__, __func__, fmt, ##__VA_ARGS__);                                      \
    }                                                                                                                  \
  } while (0)

Log exactly once per call site (thread-safe)

Logs a message exactly once, no matter how many times the code is executed. Each call site maintains its own static counter, so different call sites can log independently.

Useful for one-time initialization messages, warnings, or debug output that should only appear once per session.

Parameters

log_level	Log level (DEV, DEBUG, INFO, WARN, ERROR, FATAL)
fmt	Format string (printf-style)
...	Format arguments

Note

Thread-safe via atomic operations.

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

     {                                                                                                                 \
    static LOG_ATOMIC_UINT64 _log_once_counter = LOG_ATOMIC_UINT64_INIT(0);                                            \
    uint64_t _log_once_count = atomic_load_u64(&_log_once_counter);                                                    \
    if (_log_once_count == 0) {                                                                                        \
      atomic_store_u64(&_log_once_counter, 1);                                                                         \
      log_msg(LOG_##log_level, __FILE__, __LINE__, __func__, fmt, ##__VA_ARGS__);                                      \
    }                                                                                                                  \
  } while (0)

log_only

#define log_only	(		bitmask,
			level,
			...
	)

#include <log.h>

Value:

  ({                                                                                                                   \
    if ((bitmask) & LOG_BIT(level))                                                                                    \
      log_as(level, __VA_ARGS__);                                                                                      \
  })

Log a message given its level and if the bitmask allows so.

Parameters

bitmask	The severity bitmask, where level n is encoded as 2^n.
level	The log level used by the message
...	Format string and arguments (printf-style)

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

   {                                                                                                                   \
    if ((bitmask) & LOG_BIT(level))                                                                                    \
      log_as(level, __VA_ARGS__);                                                                                      \
  })

log_plain

#define log_plain

(

...

)

log_plain_msg(__VA_ARGS__)

#include <log.h>

Plain logging - writes to both log file and stderr without timestamps or log levels.

Parameters

...	Format string and arguments (printf-style)

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

log_plain_stderr

#define log_plain_stderr

(

...

)

log_plain_stderr_msg(__VA_ARGS__)

#include <log.h>

Plain logging to stderr with newline.

Parameters

...	Format string and arguments (printf-style)

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

log_plain_stderr_nonewline

#define log_plain_stderr_nonewline

(

...

)

log_plain_stderr_nonewline_msg(__VA_ARGS__)

#include <log.h>

Plain logging to stderr without newline - for interactive prompts.

Parameters

...	Format string and arguments (printf-style)

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

log_plain_stdout

#define log_plain_stdout

(

...

)

log_plain_stdout_msg(__VA_ARGS__)

#include <log.h>

Plain logging to stdout with newline.

Parameters

...	Format string and arguments (printf-style)

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

LOG_SERVER_IMPL

#define LOG_SERVER_IMPL	(		sockfd,
			crypto_ctx,
			level,
			fmt,
			...
	)

#include <log.h>

Value:

  log_net_message(sockfd, (const struct crypto_context_t *)(crypto_ctx), level, REMOTE_LOG_DIRECTION_CLIENT_TO_SERVER, \
                  __FILE__, __LINE__, __func__, fmt, ##__VA_ARGS__)

Definition at line 86 of file network/log.h.

LOG_TIMESTAMP_BUFFER_SIZE

#define LOG_TIMESTAMP_BUFFER_SIZE   32

#include <log.h>

Maximum size of a timestamp string.

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

log_warn

#define log_warn

(

...

)

log_only(LOG_BIT(LOG_WARN), LOG_WARN, __VA_ARGS__)

#include <log.h>

Log a WARN message.

Parameters

...	Format string and arguments (printf-style)

Note

WARN messages can be stripped via LOG_COMPILE_LEVEL=LOG_ERROR.

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

log_warn_client

#define log_warn_client	(		client,
			fmt,
			...
	)		LOG_CLIENT_IMPL(client, LOG_WARN, fmt, ##__VA_ARGS__)

#include <log.h>

Server sends WARN log message to client.

Definition at line 72 of file network/log.h.

log_warn_server

#define log_warn_server	(		sockfd,
			crypto_ctx,
			fmt,
			...
	)		LOG_SERVER_IMPL(sockfd, crypto_ctx, LOG_WARN, fmt, ##__VA_ARGS__)

#include <log.h>

Client sends WARN log message to server.

Definition at line 99 of file network/log.h.

MAX_LOG_SIZE

#define MAX_LOG_SIZE   (3 * 1024 * 1024)

#include <log.h>

Maximum log file size in bytes (3MB) before rotation.

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

MAX_TERMINAL_BUFFER_ENTRIES

#define MAX_TERMINAL_BUFFER_ENTRIES   256

#include <log.h>

Maximum number of buffered log entries.

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

MAX_TERMINAL_BUFFER_SIZE

#define MAX_TERMINAL_BUFFER_SIZE   (64 * 1024)

#include <log.h>

Maximum size of terminal output buffer (64KB)

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

Typedef Documentation

color_scheme_t

typedef struct color_scheme_t color_scheme_t

#include <log.h>

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

remote_log_direction_t

typedef enum remote_log_direction remote_log_direction_t

#include <log.h>

Remote log packet direction enumeration.

Indicates the originator of a remote log message so receivers can annotate logs clearly.

Note

This typedef MUST be defined before includes to avoid circular dependency issues with packet.h

session_log_buffer_t

typedef struct session_log_buffer session_log_buffer_t

#include <log.h>

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

Enumeration Type Documentation

log_color_t

enum log_color_t

#include <log.h>

Color enum for logging - indexes into color arrays.

These values directly index into level_colors arrays. Order matches DEV, DEBUG, WARN, INFO, ERROR, FATAL, GREY, RESET.

Enumerator
LOG_COLOR_DEV	Blue - DEV messages
LOG_COLOR_DEBUG	Cyan - DEBUG messages
LOG_COLOR_INFO	Green - INFO messages
LOG_COLOR_WARN	Yellow - WARN messages
LOG_COLOR_ERROR	Red - ERROR messages
LOG_COLOR_FATAL	Magenta - FATAL messages
LOG_COLOR_GREY	Grey - for neutral messages or labels
LOG_COLOR_RESET	Reset to default

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

             {
  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_t;

log_level_t

enum log_level_t

#include <types.h>

Logging levels enumeration.

Defines the severity levels for log messages. Used throughout the logging system without circular dependencies.

Enumerator
ASCIICHAT_LOG_DEV	Development messages (most verbose)
ASCIICHAT_LOG_DEBUG	Debug messages
ASCIICHAT_LOG_INFO	Informational messages
ASCIICHAT_LOG_WARN	Warning messages
ASCIICHAT_LOG_ERROR	Error messages
ASCIICHAT_LOG_FATAL	Fatal error messages (most severe)

Definition at line 29 of file types.h.

             {
  ASCIICHAT_LOG_DEV = 0, 
  ASCIICHAT_LOG_DEBUG,   
  ASCIICHAT_LOG_INFO,    
  ASCIICHAT_LOG_WARN,    
  ASCIICHAT_LOG_ERROR,   
  ASCIICHAT_LOG_FATAL    
} log_level_t;

remote_log_direction

enum remote_log_direction

#include <log.h>

Remote log packet direction enumeration.

Indicates the originator of a remote log message so receivers can annotate logs clearly.

Note

This typedef MUST be defined before includes to avoid circular dependency issues with packet.h

Enumerator
REMOTE_LOG_DIRECTION_UNKNOWN
REMOTE_LOG_DIRECTION_SERVER_TO_CLIENT
REMOTE_LOG_DIRECTION_CLIENT_TO_SERVER

Definition at line 20 of file network/log.h.

                                  {
  REMOTE_LOG_DIRECTION_UNKNOWN = 0,
  REMOTE_LOG_DIRECTION_SERVER_TO_CLIENT = 1,
  REMOTE_LOG_DIRECTION_CLIENT_TO_SERVER = 2
} remote_log_direction_t;

Function Documentation

colorize_named_string()

const char * colorize_named_string

(

const char *

name_str

)

#include <named.h>

Colorize a "type/name" string for display.

Parameters

name_str

String in "type/name" or "type/name.id" format

Returns

Colorized string with ANSI codes: type(yellow)/name(blue)

Used by memory report and other displays to colorize named objects. Applies colors:

• Type: yellow (LOG_COLOR_WARN)
• Name: blue (LOG_COLOR_DEV)
• Separator: uncolored

Example: "thread/splash_anim.0" displays with type in yellow, name in blue

Note

Returns pointer to rotating static buffer (4 buffers)

Safe to use in printf-style calls: "%s"

Colorize a "type/name" string for display.

Parameters

name_str

String in "type/name (0xaddress)" format (e.g., "thread/splash_anim.0 (0x7f123456)")

Returns

Colorized string with ANSI codes: type(yellow)/name(blue) (id(grey))

Used by memory report to colorize named object display. Returns a pointer to a static rotating buffer (4 buffers, valid until next call).

Example: "thread/splash_anim.0 (0x7f123456)" displays with:

• "thread" in yellow
• "splash_anim.0" in blue
• "0x7f123456" in grey

Definition at line 972 of file log/named.c.

                                                        {
#define COLORIZE_BUFFERS 4
#define COLORIZE_BUFFER_SIZE 512
  static char buffers[COLORIZE_BUFFERS][COLORIZE_BUFFER_SIZE];
  static int buffer_idx = 0;
 
  if (!name_str || name_str[0] == '\0') {
    return name_str;
  }
 
  char *current_buf = buffers[buffer_idx];
  buffer_idx = (buffer_idx + 1) % COLORIZE_BUFFERS;
 
  /* Find the slash separator (type/name) */
  const char *slash = strchr(name_str, '/');
  if (!slash) {
    /* No slash found - just return the string as-is */
    return name_str;
  }
 
  /* Find opening paren for address */
  const char *paren = strchr(name_str, '(');
 
  /* Extract type (before slash) */
  size_t type_len = slash - name_str;
  char type_buf[256];
  size_t copy_len = type_len < sizeof(type_buf) - 1 ? type_len : sizeof(type_buf) - 1;
  memcpy(type_buf, name_str, copy_len);
  type_buf[copy_len] = '\0';
 
  /* Extract name (between slash and paren, or end of string) */
  const char *name_start = slash + 1;
  size_t name_len;
  if (paren && paren > slash) {
    /* Skip spaces before paren */
    const char *name_end = paren - 1;
    while (name_end > name_start && *name_end == ' ') {
      name_end--;
    }
    name_len = name_end - name_start + 1;
  } else {
    name_len = strlen(name_start);
  }
 
  char name_buf[256];
  size_t name_copy_len = name_len < sizeof(name_buf) - 1 ? name_len : sizeof(name_buf) - 1;
  memcpy(name_buf, name_start, name_copy_len);
  name_buf[name_copy_len] = '\0';
 
  /* Apply colors */
  const char *type_colored = colored_string(LOG_COLOR_WARN, type_buf);
  const char *name_colored = colored_string(LOG_COLOR_DEV, name_buf);
 
  /* Format: type(yellow)/name(blue) and add address part if present */
  if (paren) {
    /* Extract address (0x...) from parentheses */
    const char *addr_start = paren + 1;
    const char *addr_end = strchr(addr_start, ')');
    if (addr_end) {
      size_t addr_len = addr_end - addr_start;
      char addr_buf[128];
      size_t addr_copy_len = addr_len < sizeof(addr_buf) - 1 ? addr_len : sizeof(addr_buf) - 1;
      memcpy(addr_buf, addr_start, addr_copy_len);
      addr_buf[addr_copy_len] = '\0';
 
      const char *addr_colored = colored_string(LOG_COLOR_GREY, addr_buf);
      safe_snprintf(current_buf, COLORIZE_BUFFER_SIZE, "%s/%s (%s)", type_colored, name_colored, addr_colored);
    } else {
      safe_snprintf(current_buf, COLORIZE_BUFFER_SIZE, "%s/%s %s", type_colored, name_colored, paren);
    }
  } else {
    safe_snprintf(current_buf, COLORIZE_BUFFER_SIZE, "%s/%s", type_colored, name_colored);
  }
 
  return current_buf;
#undef COLORIZE_BUFFERS
#undef COLORIZE_BUFFER_SIZE
}

References colored_string(), COLORIZE_BUFFER_SIZE, COLORIZE_BUFFERS, LOG_COLOR_DEV, LOG_COLOR_GREY, LOG_COLOR_WARN, and safe_snprintf().

format_message()

char * format_message	(	const char *	format,
		va_list	args
	)

#include <log.h>

Format a message using va_list.

Parameters

format	Format string
args	Variable arguments list

Returns

Formatted message string (must be freed by caller)

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

                                                       {
  if (!format) {
    return NULL;
  }
 
  // First, determine the size needed
  va_list args_copy;
  va_copy(args_copy, args);
  int size = safe_vsnprintf(NULL, 0, format, args_copy);
  va_end(args_copy);
 
  if (size < 0) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format context message");
    return NULL;
  }
 
  // Allocate and format the message
  char *message = SAFE_MALLOC(size + 1, char *);
  int result = safe_vsnprintf(message, (size_t)size + 1, format, args);
  if (result < 0) {
    SAFE_FREE(message);
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format context message");
    return NULL;
  }
 
  return message;
}

References args, ERROR_INVALID_STATE, LOGGING_INTERNAL_ERROR, SAFE_FREE, SAFE_MALLOC, and safe_vsnprintf().

Referenced by asciichat_fatal_with_context(), asciichat_set_errno_with_message(), asciichat_set_errno_with_system_error_and_message(), and log_labeled().

get_current_time_formatted()

size_t get_current_time_formatted

(

char *

time_buf

)

#include <log.h>

Get current time as formatted string.

Parameters

time_buf

Output buffer for formatted time

Returns

Number of characters written (excluding null terminator)

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

                                                  {
  /* Get wall-clock time in nanoseconds */
  uint64_t ts_ns = time_get_realtime_ns();
  // Extract seconds and nanoseconds from total nanoseconds
  time_t seconds = (time_t)(ts_ns / NS_PER_SEC_INT);
  long nanoseconds = (long)(ts_ns % NS_PER_SEC_INT);
  struct tm tm_info;
  platform_localtime(&seconds, &tm_info);
  // Format the time part first
  // strftime returns 0 on error, not negative (and len is size_t/unsigned)
  size_t len = strftime(time_buf, 32, "%H:%M:%S", &tm_info);
  if (len == 0 || len >= 32) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format time");
    return 0;
  }
 
  // Add microseconds manually (convert nanoseconds to microseconds for display)
  long microseconds = nanoseconds / 1000;
  if (microseconds < 0)
    microseconds = 0;
  if (microseconds > 999999)
    microseconds = 999999;
 
  int result = safe_snprintf(time_buf + len, 32 - len, ".%06ld", microseconds);
  if (result < 0 || result >= (int)(32 - len)) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format microseconds");
    return 0;
  }
 
  return len + (size_t)result;
}

References ERROR_INVALID_STATE, LOGGING_INTERNAL_ERROR, NS_PER_SEC_INT, platform_localtime(), safe_snprintf(), and time_get_realtime_ns().

Referenced by log_msg(), log_plain_msg(), and log_terminal_msg().

log_cleanup_colors()

void log_cleanup_colors

(

void

)

#include <log.h>

Clean up compiled color scheme.

Should be called AFTER memory reporting to ensure colored output. Safe to call multiple times (idempotent).

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

                              {
  colorscheme_cleanup_compiled(&g_log.compiled_colors);
}

References colorscheme_cleanup_compiled().

Referenced by asciichat_shared_destroy().

log_clear_session_log_buffer()

void log_clear_session_log_buffer

(

void

)

#include <log.h>

Unregister the session log buffer.

No-op if no buffer is currently registered.

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

                                        {
  atomic_ptr_store(&g_log.session_log_buffer, NULL);
}

References atomic_ptr_store().

Referenced by log_system_destroy(), splash_log_destroy(), ui_mdns_log_destroy(), and ui_status_log_destroy().

log_destroy()

void log_destroy

(

void

)

#include <log.h>

Destroy the logging system and close log file.

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

                       {
  // Destroy mmap logging first (if active)
  if (log_mmap_is_active()) {
    log_mmap_destroy();
  }
 
  // Cleanup grep filter
  grep_destroy();
 
  /* Mark logging system as shutdown FIRST (state machine transition)
   * This signals worker threads to stop logging immediately before we free memory.
   * This prevents TOCTOU race where a worker thread could see non-NULL format pointer
   * after we've freed it but before lifecycle_shutdown() is called. */
  lifecycle_shutdown(&g_log.lifecycle);
 
  // Cleanup custom format structures: All worker threads have been signaled to stop by this point.
  // Safe to free templates now without use-after-free concerns.
  if (g_log.format) {
    log_template_free(g_log.format);
    g_log.format = NULL;
  }
  if (g_log.format_console_only) {
    log_template_free(g_log.format_console_only);
    g_log.format_console_only = NULL;
  }
  atomic_store_bool(&g_log.has_custom_format, false);
 
  // Lock-free cleanup using atomic operations
  int old_file = atomic_load_int(&g_log.file);
  if (old_file >= 0 && old_file != STDERR_FILENO) {
    platform_close(old_file);
  }
  atomic_store_int(&g_log.file, -1);
 
  // Destroy rotation mutex
  lifecycle_shutdown(&g_log.rotation_mutex_lifecycle);
}

References atomic_load_int(), atomic_store_bool(), atomic_store_int(), grep_destroy(), lifecycle_shutdown(), log_mmap_destroy(), log_mmap_is_active(), log_template_free(), and platform_close().

Referenced by asciichat_shared_destroy(), and main().

log_disable_file_output()

void log_disable_file_output

(

void

)

#include <log.h>

Disable file output and use stderr instead.

Closes the current log file and redirects file output to stderr. Used when switching to JSON-only logging or when disabling text file output.

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

                                   {
  /* Close the current file if it's not stderr */
  int old_file = atomic_load_int(&g_log.file);
  if (old_file >= 0 && old_file != STDERR_FILENO) {
    platform_close(old_file);
  }
  /* Redirect file output to stderr */
  atomic_store_int(&g_log.file, STDERR_FILENO);
  g_log.filename[0] = '\0';
}

References atomic_load_int(), atomic_store_int(), and platform_close().

log_disable_mmap()

void log_disable_mmap

(

void

)

#include <log.h>

Disable mmap logging and return to mutex-based logging.

Flushes remaining entries and closes the mmap file.

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

                            {
  if (log_mmap_is_active()) {
    log_mmap_destroy();
    log_info("Lock-free mmap logging disabled");
  }
}

References log_info, log_mmap_destroy(), and log_mmap_is_active().

log_enable_mmap()

asciichat_error_t log_enable_mmap

(

const char *

log_path

)

#include <log.h>

Enable lock-free mmap-based logging.

When enabled, log messages bypass the mutex and use atomic operations to write directly to a memory-mapped log file as human-readable text.

Benefits:

• No mutex contention between logging threads
• Crash-safe: text is written directly to mmap'd file, readable after crash
• Fast path uses atomic fetch_add, no locks
• ERROR/FATAL messages sync immediately for visibility
• Simple: log file IS the mmap file (no separate binary format)

Parameters

log_path

Path to the log file (will be memory-mapped)

Returns

ASCIICHAT_OK on success, error code on failure

Note

Call log_init() first, then log_enable_mmap() to upgrade to lock-free

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

                                                        {
  return log_enable_mmap_sized(log_path, 0); /* Use default size */
}

References log_enable_mmap_sized().

log_enable_mmap_sized()

asciichat_error_t log_enable_mmap_sized	(	const char *	log_path,
		size_t	max_size
	)

#include <log.h>

Enable lock-free mmap logging with custom file size.

Parameters

log_path	Path to the log file
max_size	Maximum file size in bytes (0 = default 4MB)

Returns

ASCIICHAT_OK on success, error code on failure

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

                                                                               {
  if (!log_path) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "log_path is required");
  }
 
  // Initialize mmap logging - text is written directly to the mmap'd file
  asciichat_error_t result = log_mmap_init_simple(log_path, max_size);
  if (result != ASCIICHAT_OK) {
    return result;
  }
 
  log_info("Lock-free mmap logging enabled: %s", log_path);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, log_info, log_mmap_init_simple(), and SET_ERRNO.

Referenced by log_enable_mmap().

log_file_msg()

void log_file_msg	(	const char *	fmt,
			...
	)

#include <log.h>

Log to file only, no stderr output.

Parameters

fmt	Format string (printf-style)
...	Format arguments

Writes to log file only, without terminal output.

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

                                        {
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    return;
  }
 
  char log_buffer[LOG_MSG_BUFFER_SIZE];
  va_list args;
  va_start(args, fmt);
  int msg_len = safe_vsnprintf(log_buffer, sizeof(log_buffer), fmt, args);
  va_end(args);
 
  if (msg_len <= 0) {
    return;
  }
 
  // Truncate at whole line boundaries to avoid UTF-8 issues
  msg_len = truncate_at_whole_line(log_buffer, msg_len, sizeof(log_buffer));
 
  // Validate UTF-8 in formatted message
  validate_log_message_utf8(log_buffer, "file-only log");
 
  // Write to mmap if active, else to file
  if (log_mmap_is_active()) {
    log_mmap_write(LOG_INFO, NULL, 0, NULL, "%s", log_buffer);
  } else {
    int file_fd = atomic_load_u64(&g_log.file);
    if (file_fd >= 0 && file_fd != STDERR_FILENO) {
      write_to_log_file_atomic(log_buffer, msg_len, NULL);
      write_to_log_file_atomic("\n", 1, NULL);
    }
  }
}

References args, atomic_load_u64(), lifecycle_is_initialized(), LOG_INFO, log_mmap_is_active(), log_mmap_write(), LOG_MSG_BUFFER_SIZE, and safe_vsnprintf().

Referenced by backtrace_print().

log_get_color_array()

const char ** log_get_color_array

(

void

)

#include <log.h>

Get the appropriate color array based on terminal capabilities.

Returns

Pointer to color array (16-color, 256-color, or truecolor)

Automatically detects terminal capabilities and returns the appropriate color array.

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

                                       {
  init_terminal_capabilities();
 
  /* Colors should be initialized via log_system_init(); this is just a safety check */
  if (!g_log.log_colorscheme_initialized) {
    /* Fallback: initialize colors if not already done (should not happen after log_system_init) */
    log_init_colors();
  }
 
  /* Safety check: if colors are still not initialized, return NULL to prevent crashes from null pointers */
  if (!g_log.log_colorscheme_initialized) {
    return NULL;
  }
 
  /* Return the compiled color scheme based on terminal capabilities
   * codes_16, codes_256, codes_truecolor are now proper arrays of pointers (const char *[8]),
   * so we can safely cast them to const char **. */
  if (g_log.terminal_caps.color_level >= TERM_COLOR_TRUECOLOR) {
    return (const char **)g_log.compiled_colors.codes_truecolor;
  } else if (g_log.terminal_caps.color_level >= TERM_COLOR_256) {
    return (const char **)g_log.compiled_colors.codes_256;
  } else {
    return (const char **)g_log.compiled_colors.codes_16;
  }
}

References log_init_colors(), TERM_COLOR_256, and TERM_COLOR_TRUECOLOR.

Referenced by log_level_color(), log_msg(), and log_recolor_plain_entry().

log_get_force_stderr()

bool log_get_force_stderr

(

void

)

#include <log.h>

Get current force_stderr setting.

Returns

true if all logs are forced to stderr, false otherwise

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

                                {
  return atomic_load_u64(&g_log.force_stderr);
}

References atomic_load_u64().

Referenced by terminal_choose_log_fd().

log_get_level()

log_level_t log_get_level

(

void

)

#include <log.h>

Get the current minimum log level.

Returns

Current log level

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

                                {
  return (log_level_t)atomic_load_u64(&g_log.level);
}

References atomic_load_u64().

log_get_session_log_buffer()

session_log_buffer_t * log_get_session_log_buffer

(

void

)

#include <log.h>

Get the currently registered session log buffer.

Returns the buffer that was previously registered with log_set_session_log_buffer(). Returns NULL if no buffer is currently registered.

Returns

Pointer to registered buffer, or NULL

Returns the buffer that was previously registered with log_set_session_log_buffer(). Returns NULL if no buffer is currently registered.

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

                                                       {
  return (session_log_buffer_t *)atomic_ptr_load(&g_log.session_log_buffer);
}

References atomic_ptr_load().

Referenced by log_search_gather_and_filter_logs().

log_get_template()

void * log_get_template

(

void

)

#include <log.h>

Get the current log format template (opaque pointer)

Returns

Opaque pointer to the current log format template (may be NULL if not set) Cast to log_template_t* after including log/format.h

Returns the compiled log format template used by the logging system. This is useful for code that needs to format log entries using the same template as the rest of the logging system (e.g., platform code).

Note

The returned pointer is valid only for the lifetime of the logging system

It's safe to call before log_init() (will return NULL)

Return type is void* (opaque) to avoid circular dependency with format.h

Get the current log format template (opaque pointer)

Returns

Opaque pointer to the current log format template (may be NULL if not set)

Returns the compiled log format template used by the logging system. This is used by platform code (e.g., backtrace formatting) to format log entries using the same template as the rest of the logging system. Returns void* (opaque) to avoid circular dependency with format.h.

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

                             {
  return (void *)g_log.format;
}

Referenced by backtrace_print().

log_get_terminal_output()

bool log_get_terminal_output

(

void

)

#include <log.h>

Get current terminal output setting.

Returns

true if terminal output is enabled, false otherwise

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

                                   {
  return atomic_load_u64(&g_log.terminal_output_enabled);
}

References atomic_load_u64().

Referenced by config_load_and_apply().

log_init()

void log_init	(	const char *	filename,
		log_level_t	level,
		bool	force_stderr,
		bool	use_mmap
	)

#include <log.h>

Initialize the logging system.

Parameters

filename	Log file path (or NULL for no file logging)
level	Minimum log level to output
force_stderr	If true, route ALL logs to stderr (for client mode to keep stdout clean)
use_mmap	If true, use fully lock-free mmap logging (recommended). If mmap fails, uses stderr only (no mutex fallback).

Note

When use_mmap=true, the entire logging path is lock-free:

• File output uses atomic operations on mmap'd memory
• Terminal output uses atomic fprintf/fwrite to fd
• No mutex is ever acquired in the hot path

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

                                                                                         {
 
  // Initialize rotation mutex (only operation that uses a mutex)
  g_log.rotation_mutex_lifecycle.sync_type = LIFECYCLE_SYNC_MUTEX;
  g_log.rotation_mutex_lifecycle.sync.mutex = &g_log.rotation_mutex;
  lifecycle_init(&g_log.rotation_mutex_lifecycle, "log_rotation");
 
  // Set basic config using atomic stores
  atomic_store_u64(&g_log.force_stderr, force_stderr);
  bool preserve_terminal_output = atomic_load_u64(&g_log.terminal_output_enabled);
 
  // Force logs to stderr if stdout is piped/redirected
  // This prevents logs from contaminating piped/redirected output in snapshot/batch modes
  // Per terminal.h: "force stderr when piped to prevent data corruption"
  if (terminal_is_piped_output()) {
    atomic_store_bool(&g_log.force_stderr, true);
  }
 
  // Close any existing file (atomic load/store)
  int old_file = atomic_load_int(&g_log.file);
  if (lifecycle_is_initialized(&g_log.lifecycle) && old_file >= 0 && old_file != STDERR_FILENO) {
    platform_close(old_file);
    atomic_store_int(&g_log.file, -1);
  }
 
  // Check LOG_LEVEL environment variable
  const char *env_level_str = SAFE_GETENV("LOG_LEVEL");
  if (env_level_str) {
    atomic_store_u64(&g_log.level, (int)parse_log_level_from_env());
  } else {
    atomic_store_u64(&g_log.level, (int)level);
  }
 
  atomic_store_bool(&g_log.level_manually_set, false);
  atomic_store_u64(&g_log.current_size, 0);
 
  if (filename) {
    SAFE_STRNCPY(g_log.filename, filename, sizeof(g_log.filename) - 1);
 
    if (use_mmap) {
      // Lock-free mmap path - writes go to mmap'd file
      asciichat_error_t mmap_result = log_mmap_init_simple(filename, 0);
      if (mmap_result == ASCIICHAT_OK) {
        atomic_store_int(&g_log.file, -1); // No regular fd - using mmap for file output
      } else {
        // Mmap failed - use stderr only (atomic writes, lock-free)
        if (preserve_terminal_output) {
          safe_fprintf(stderr, "Mmap logging failed for %s, using stderr only (lock-free)\n", filename);
        }
        atomic_store_int(&g_log.file, STDERR_FILENO);
        g_log.filename[0] = '\0';
      }
    } else {
      // Lock-free file I/O path - uses atomic write() syscalls
      int fd = platform_open("log_file", filename, O_CREAT | O_RDWR | O_TRUNC, FILE_PERM_PRIVATE);
      atomic_store_int(&g_log.file, (fd >= 0) ? fd : STDERR_FILENO);
      if (fd < 0) {
        if (preserve_terminal_output) {
          safe_fprintf(stderr, "Failed to open log file: %s\n", filename);
        }
        g_log.filename[0] = '\0';
      }
    }
  } else {
    atomic_store_int(&g_log.file, STDERR_FILENO);
    g_log.filename[0] = '\0';
  }
 
  /* Initialize default log format (NULL means use mode-specific default) */
  log_set_format(NULL, false);
 
  /* Mark logging system as initialized (state machine transition) */
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    lifecycle_init(&g_log.lifecycle, "logging");
  }
 
  atomic_store_u64(&g_log.terminal_output_enabled, preserve_terminal_output);
 
  // Reset terminal detection if needed
  if (g_log.terminal_caps_initialized && !g_log.terminal_caps.detection_reliable) {
    g_log.terminal_caps_initialized = false;
  }
 
  // Detect terminal capabilities
  log_redetect_terminal_capabilities();
 
  // NOTE: Color initialization happens separately via log_set_color_scheme()
  // after options are parsed. Logging works without colors until then.
  // NOTE: Grep filter initialization happens in main.c after options_init() completes.
}

References ASCIICHAT_OK, atomic_load_int(), atomic_load_u64(), atomic_store_bool(), atomic_store_int(), atomic_store_u64(), FILE_PERM_PRIVATE, lifecycle_init(), lifecycle_is_initialized(), LIFECYCLE_SYNC_MUTEX, log_mmap_init_simple(), log_redetect_terminal_capabilities(), log_set_format(), platform_close(), platform_open(), safe_fprintf(), SAFE_GETENV, SAFE_STRNCPY, and terminal_is_piped_output().

Referenced by asciichat_shared_init(), client_init_with_args(), main(), and mirror_init_with_args().

log_init_colors()

void log_init_colors

(

void

)

#include <log.h>

Initialize logging color system with current terminal capabilities.

Compiles the active color scheme to ANSI codes based on terminal capabilities. Called automatically during terminal capability detection.

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

                           {
 
  /* Skip color initialization during terminal detection to avoid mutex deadlock */
  if (g_log.terminal_caps_detecting) {
    return;
  }
 
  /* Skip color initialization before logging is fully initialized */
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    return;
  }
 
  if (g_log.log_colorscheme_initialized) {
    return;
  }
 
  /* Get active color scheme - this ensures color system is initialized */
  const color_scheme_t *scheme = colorscheme_get_active_scheme();
  if (!scheme) {
    /* Don't mark as initialized if we can't get a color scheme - return NULL instead */
    return;
  }
 
  /* Acquire mutex for compilation (mutex is now initialized by colorscheme_init) */
  mutex_lock(&g_colorscheme_mutex);
 
  /* Debug: Check if g_log.compiled_colors is actually zero-initialized */
  /* Zero the structure on first use to avoid freeing garbage pointers */
  /* (static = {0} produces garbage in this build for unknown reasons) */
  static bool first_compile = true;
  if (first_compile) {
    memset(&g_log.compiled_colors, 0, sizeof(g_log.compiled_colors));
    first_compile = false;
  }
 
  /* Detect terminal background */
  terminal_background_t background = detect_terminal_background();
  /* Determine color mode for compilation */
  terminal_color_mode_t mode;
  if (g_log.terminal_caps.color_level >= TERM_COLOR_TRUECOLOR) {
    mode = TERM_COLOR_TRUECOLOR;
  } else if (g_log.terminal_caps.color_level >= TERM_COLOR_256) {
    mode = TERM_COLOR_256;
  } else {
    mode = TERM_COLOR_16;
  }
  /* Compile the color scheme to ANSI codes */
  asciichat_error_t result = colorscheme_compile_scheme(scheme, mode, background, &g_log.compiled_colors);
  g_log.log_colorscheme_initialized = true;
  mutex_unlock(&g_colorscheme_mutex);
 
  /* Log outside of mutex lock to avoid recursive lock deadlock */
  if (result != ASCIICHAT_OK) {
    log_debug("Failed to compile color scheme: %d", result);
  }
}

References ASCIICHAT_OK, colorscheme_compile_scheme(), colorscheme_get_active_scheme(), detect_terminal_background(), g_colorscheme_mutex, lifecycle_is_initialized(), log_debug, mutex_lock, mutex_unlock, TERM_COLOR_16, TERM_COLOR_256, and TERM_COLOR_TRUECOLOR.

Referenced by log_get_color_array(), log_system_init(), and main().

log_labeled()

void log_labeled	(	const char *	label,
		log_color_t	color,
		const char *	message,
			...
	)

#include <log.h>

Print a labeled message with color.

Parameters

label	The label text to print (appears before the message)
color	Color for the label (from log_color_t enum)
message	Format string (printf-style) for the message
...	Format arguments

Used for consistent formatting of section headers and labeled output. The label is colored, followed by the message content. Output goes to both stderr and log file.

Definition at line 95 of file asciichat_errno.c.

                                                                                 {
  va_list args;
  va_start(args, message);
  char *formatted_message = format_message(message, args);
  va_end(args);
 
  safe_fprintf(stderr, "%s: %s\n", colored_string(color, label), formatted_message);
 
  log_file("%s: %s", label, formatted_message);
 
  SAFE_FREE(formatted_message);
}

References args, colored_string(), format_message(), log_file, safe_fprintf(), and SAFE_FREE.

Referenced by asciichat_fatal_with_context().

log_level_color()

const char * log_level_color

(

log_color_t

color

)

#include <log.h>

Get color string for a given color enum.

Parameters

color

Color enum value

Returns

ANSI color code string

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

                                               {
  const char **colors = log_get_color_array();
  if (colors == NULL) {
    return ""; /* Return empty string if colors not available */
  }
  if (color >= 0 && color <= LOG_COLOR_RESET) {
    return colors[color];
  }
  return colors[LOG_COLOR_RESET]; /* Return reset color if invalid */
}

References LOG_COLOR_RESET, and log_get_color_array().

Referenced by colored_string().

log_lock_terminal()

bool log_lock_terminal

(

void

)

#include <log.h>

Lock terminal output for exclusive access by the calling thread.

Call this before interactive prompts (like password entry, yes/no questions) to ensure only the calling thread can output to the terminal. Other threads' log messages will be buffered and flushed when the terminal is unlocked.

While locked:

• The locking thread can use log_plain() to write to terminal
• Other threads' log messages go to log file and are buffered
• Buffered messages are flushed to terminal on unlock

Must be paired with log_unlock_terminal().

Returns

The previous terminal lock state (for nested calls)

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

                             {
  bool expected = atomic_load_bool(&g_log.terminal_locked);
  while (!atomic_cas_bool(&g_log.terminal_locked, &expected, true)) {
    // Retry if CAS failed
  }
  atomic_store_u64(&g_log.terminal_owner_thread, (uint64_t)asciichat_thread_self());
  return expected;
}

References asciichat_thread_self, atomic_cas_bool(), atomic_load_bool(), and atomic_store_u64().

Referenced by client_crypto_handshake(), client_main(), prompt_password(), prompt_unknown_host(), and ui_mdns_select().

log_msg()

void log_msg	(	log_level_t	level,
		const char *	file,
		int	line,
		const char *	func,
		const char *	fmt,
			...
	)

#include <log.h>

Log a message at a specific level.

Parameters

level	Log level (LOG_DEV, LOG_DEBUG, LOG_INFO, LOG_WARN, LOG_ERROR, LOG_FATAL)
file	Source file name (or NULL to omit)
line	Source line number (or 0 to omit)
func	Function name (or NULL to omit)
fmt	Format string (printf-style)
...	Format arguments

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

                                                                                                    {
 
  // All state access uses atomic operations - fully lock-free
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    return;
  }
 
  // Safety check: if main format template has been freed during shutdown, skip logging
  // This prevents heap-use-after-free when threads call logging after log_destroy() has freed g_log.format
  if (!g_log.format) {
    return;
  }
 
  uint64_t loaded_level = atomic_load_u64(&g_log.level);
 
  if (level < (log_level_t)loaded_level) {
    return;
  }
  /* =========================================================================
   * MMAP PATH: When mmap logging is active, writes go to mmap'd file
   * ========================================================================= */
  bool mmap_active = log_mmap_is_active();
 
  if (mmap_active) {
    maybe_rotate_log();
 
    va_list args;
    va_start(args, fmt);
    char msg_buffer[LOG_MMAP_MSG_BUFFER_SIZE];
    int msg_len = safe_vsnprintf(msg_buffer, sizeof(msg_buffer), fmt, args);
    va_end(args);
 
    // Truncate at whole line boundaries to avoid UTF-8 issues
    if (msg_len > 0) {
      msg_len = truncate_at_whole_line(msg_buffer, msg_len, sizeof(msg_buffer));
    }
 
    // Validate UTF-8 in formatted message
    validate_log_message_utf8(msg_buffer, "mmap log message");
 
    log_mmap_write(level, file, line, func, "%s", msg_buffer);
 
    // Terminal output (check with atomic loads)
    if (atomic_load_u64(&g_log.terminal_output_enabled) && !atomic_load_bool(&g_log.terminal_locked)) {
      char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
      uint64_t time_ns = time_get_realtime_ns();
      get_current_time_formatted(time_buf);
 
      // Choose output stream using unified routing logic
      int fd = terminal_choose_log_fd(level);
      FILE *output_stream = (fd == STDERR_FILENO) ? stderr : stdout;
      // Check if colors should be used
      // Priority 1: If --color was explicitly passed, force colors
      bool use_colors = true; // Default: enable colors
      if (g_color_flag_passed && !g_color_flag_value) {
        use_colors = false; // --color=false explicitly disables colors
      }
      // Priority 2: If --color NOT explicitly passed, enable colors by default
 
      char header_buffer[512];
      int header_len = format_log_header(header_buffer, sizeof(header_buffer), level, time_buf, file, line, func,
                                         use_colors, time_ns);
 
      if (header_len >= 0 && header_len < (int)sizeof(header_buffer)) {
        if (use_colors) {
          const char *colorized_msg = colorize_log_message(msg_buffer);
          const char **colors = log_get_color_array();
          if (colors) {
            safe_fprintf(output_stream, "%s%s%s%s\n", header_buffer, colors[LOG_COLOR_RESET], colorized_msg,
                         colors[LOG_COLOR_RESET]);
          } else {
            safe_fprintf(output_stream, "%s%s\n", header_buffer, colorized_msg);
          }
        } else {
          safe_fprintf(output_stream, "%s%s\n", header_buffer, msg_buffer);
        }
        (void)fflush(output_stream);
      }
    } else {
    }
    return;
  }
  /* =========================================================================
   * FILE I/O PATH: Lock-free using atomic write() syscalls
   * ========================================================================= */
  char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
  uint64_t time_ns = time_get_realtime_ns();
  get_current_time_formatted(time_buf);
  // Format message for file output
  char log_buffer[LOG_MSG_BUFFER_SIZE];
  va_list args;
  va_start(args, fmt);
  int header_len = format_log_header(log_buffer, sizeof(log_buffer), level, time_buf, file, line, func, false, time_ns);
  if (header_len < 0 || header_len >= (int)sizeof(log_buffer)) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format log header");
    va_end(args);
    return;
  }
  int msg_len = header_len;
  int formatted_len = safe_vsnprintf(log_buffer + header_len, sizeof(log_buffer) - (size_t)header_len, fmt, args);
  if (formatted_len < 0) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format log message");
    va_end(args);
    return;
  }
 
  msg_len += formatted_len;
  // Truncate at whole line boundaries to avoid UTF-8 issues
  msg_len = truncate_at_whole_line(log_buffer, msg_len, sizeof(log_buffer));
  // Add newline if there's room and message doesn't already end with one
  if (msg_len > 0 && msg_len < (int)sizeof(log_buffer) - 1) {
    if (log_buffer[msg_len - 1] != '\n') {
      log_buffer[msg_len++] = '\n';
      log_buffer[msg_len] = '\0';
    }
  }
  va_end(args);
  // Validate UTF-8 in formatted message
  validate_log_message_utf8(log_buffer, "leveled log message");
 
  // Extract the user message part (without header) for JSON logging
  const char *user_message = log_buffer + header_len;
 
  // For JSON output: strip automatic trailing newline (keep explicit ones)
  char json_message_buf[LOG_MSG_BUFFER_SIZE];
  const char *json_message = user_message;
  size_t user_msg_len = strlen(user_message);
 
  // If message ends with newline and it was added automatically (not in original message)
  if (user_msg_len > 0 && user_message[user_msg_len - 1] == '\n') {
    // The newline was added automatically if the message part didn't end with one
    // before we added it on line 1067. We can check this by looking at msg_len - 1
    // If msg_len >= header_len + 2, then msg_len - 2 would be the char before the newline
    int msg_content_len = msg_len - header_len;
    // NOLINTNEXTLINE(clang-analyzer-security.ArrayBound) - msg_content_len > 1 bounds check above
    if (msg_content_len > 1 && log_buffer[msg_len - 2] != '\n') {
      // Newline was added automatically - strip it for JSON
      if (user_msg_len - 1 < sizeof(json_message_buf)) {
        memcpy(json_message_buf, user_message, user_msg_len - 1);
        json_message_buf[user_msg_len - 1] = '\0';
        json_message = json_message_buf;
      }
    }
  }
 
  // Check if JSON format is enabled
  int json_fd = atomic_load_int(&g_log.json_file);
  bool json_format_enabled = (json_fd >= 0);
 
  // If JSON format is enabled, output ONLY JSON (skip text output)
  if (json_format_enabled) {
    // Output JSON to the JSON file descriptor
    log_json_write(json_fd, level, time_ns, file, line, func, json_message);
    // Also output JSON to console using unified routing logic, respecting quiet flag
    if (atomic_load_u64(&g_log.terminal_output_enabled)) {
      int console_fd = terminal_choose_log_fd(level);
      log_json_write(console_fd, level, time_ns, file, line, func, json_message);
    }
  } else {
    // Text format: output to file and terminal
    // No heap allocation - use log_buffer directly
    // Write to file (atomic write syscall) - use original buffer (with ANSI codes)
    int file_fd = (int)atomic_load_u64(&g_log.file);
    if (file_fd >= 0 && file_fd != STDERR_FILENO) {
      write_to_log_file_atomic(log_buffer, msg_len, NULL);
    }
 
    // Write to terminal (atomic state checks)
    va_list args_terminal;
    va_start(args_terminal, fmt);
    write_to_terminal_atomic(level, time_buf, file, line, func, fmt, args_terminal, time_ns);
    va_end(args_terminal);
  }
}

References args, atomic_load_bool(), atomic_load_int(), atomic_load_u64(), colorize_log_message(), ERROR_INVALID_STATE, g_color_flag_passed, g_color_flag_value, get_current_time_formatted(), lifecycle_is_initialized(), LOG_COLOR_RESET, log_get_color_array(), log_json_write(), log_mmap_is_active(), LOG_MMAP_MSG_BUFFER_SIZE, log_mmap_write(), LOG_MSG_BUFFER_SIZE, LOG_TIMESTAMP_BUFFER_SIZE, LOGGING_INTERNAL_ERROR, safe_fprintf(), safe_vsnprintf(), terminal_choose_log_fd(), and time_get_realtime_ns().

Referenced by cond_log_state(), handle_remote_log_packet_from_client(), mutex_log_state(), and rwlock_log_state().

log_named_format_message()

int log_named_format_message	(	const char *	message,
		char *	output,
		size_t	output_size
	)

#include <named.h>

Format hex addresses in a message as named object descriptions.

Parameters

message	Input message (may contain hex addresses like 0x123456)
output	Output buffer for formatted message
output_size	Size of output buffer (must be > 0)

Returns

Length of output string (excluding null terminator) if any formatting was applied, -1 if no formatting was applied or on error

Scans the input message for hex addresses in the format 0x[0-9a-fA-F]+. For each address found, checks the named object registry. If registered, replaces the address with "type: name (0xaddress)" format. If not registered, leaves the original hex address unchanged.

The output buffer is always null-terminated.

Note

The formatting is idempotent - applying it twice gives the same result

This function is efficient for messages with few hex addresses (common case)

Works correctly with 32-bit and 64-bit address formats

Definition at line 591 of file log/named.c.

                                                                                    {
  if (!message || !output || output_size == 0) {
    return -1;
  }
 
  size_t out_pos = 0;
  const char *p = message;
  bool any_transformed = false;
 
  while (*p && out_pos < output_size - 1) {
    /* Look for "0x" prefix indicating a hex address */
    if (*p == '0' && *(p + 1) == 'x' && isxdigit(*(p + 2))) {
      const char *hex_start = p;
      if (try_format_hex_address(message, hex_start, output, output_size, &out_pos, &p)) {
        any_transformed = true;
        continue;
      }
 
      /* Not registered or formatting failed - copy original hex address */
      const char *hex_end = hex_start + 2; /* Start after "0x" */
      while (*hex_end && isxdigit(*hex_end)) {
        hex_end++;
      }
      size_t hex_len = hex_end - hex_start;
      if (hex_len < output_size - out_pos) {
        memcpy(output + out_pos, hex_start, hex_len);
        out_pos += hex_len;
        p = hex_end;
      } else {
        /* Buffer overflow - truncate and stop */
        break;
      }
    } else if (isdigit(*p)) {
      /* Look for decimal integers that might be FDs or packet types */
      const char *int_start = p;
      int fd_value = 0;
      int digit_count = 0;
 
      /* Parse decimal digits */
      while (*p && isdigit(*p) && digit_count < 6) { /* FDs rarely exceed 999999 */
        fd_value = fd_value * 10 + (*p - '0');
        p++;
        digit_count++;
      }
 
      /* Skip if this integer is part of already-formatted output like "(fd=20)" or "(type/name (...))" */
      bool is_already_formatted = false;
      if (int_start - message >= 5) {
        /* Check for "(fd=", "(pkt_type=", "(socket=", "(sockfd=", or "(type/" patterns to prevent re-formatting.
         * Named objects are formatted as: type/name (0xaddress) or type/name (key=value)
         * We need to detect if we're already inside a formatted output.
         */
        const char *check = int_start - 1;
        while (check > message && isspace(*check))
          check--;
 
        // Only access *check if pointer is within bounds
        if (check >= message && *check == '=') {
          /* Found "=", now check what prefix it has for patterns like "(fd=20)" or "(socket=20)" or "(pkt_type=123)" */
          const char *eq_pos = check;
          check--;
          while (check > message && (isalnum(*check) || *check == '_')) {
            check--;
          }
          check++;
 
          size_t prefix_len = eq_pos - check;
          if ((prefix_len == 2 && strncmp(check, "fd", 2) == 0) ||
              (prefix_len == 6 && strncmp(check, "socket", 6) == 0) ||
              (prefix_len == 6 && strncmp(check, "sockfd", 6) == 0) ||
              (prefix_len == 8 && strncmp(check, "pkt_type", 8) == 0)) {
            /* Only mark as already-formatted if inside formatted output:
             * - "(" before keyword: parenthesized value like "(sockfd=15)"
             * - "/" before keyword: name part of type/name like "fd/fd=7"
             * Raw log patterns like "sockfd=15" should still be eligible for replacement. */
            const char *before_kw = check - 1;
            while (before_kw > message && isspace(*before_kw))
              before_kw--;
            if (before_kw >= message && (*before_kw == '(' || *before_kw == '/')) {
              is_already_formatted = true;
            }
          }
        } else if (check >= message && *check == '/') {
          /* Found "/", now check if this is a type/name pattern.
           * Format is "(type/name (...)" where type is word characters (thread, mutex, socket, etc.)
           * Must verify "/" is preceded by word characters AND "(" to ensure it's a formatted type.
           */
          const char *slash_pos = check;
          check--;
          while (check > message && (isalnum(*check) || *check == '_')) {
            check--;
          }
          check++;
 
          /* Check that the "/" was preceded by word characters (indicating a type name) */
          size_t type_len = slash_pos - check;
          if (type_len > 0 && (isalpha(*check) || *check == '_')) {
            /* Verify this is a registered type/name pattern by checking for "(" before the type
             * AND checking if the type actually exists in the registry */
            const char *type_start = check;
            const char *before_type = type_start - 1;
            while (before_type > message && isspace(*before_type)) {
              before_type--;
            }
 
            /* Only mark as formatted if:
             * 1. Preceded by "(" - ensures pattern looks like "(type/name ...)"
             * 2. Type exists in registry - prevents false positives on random text */
            if (before_type >= message && *before_type == '(' && is_type_in_registry(type_start, type_len)) {
              is_already_formatted = true;
            }
          }
        }
      }
 
      /* Check if this is a registered packet type */
      if (!is_already_formatted && digit_count > 0 && has_packet_type_prefix(message, int_start)) {
        const char *name = named_get_packet_type(fd_value);
        if (name) {
          const char *prefix_start = find_packet_type_prefix_start(message, int_start);
          size_t prefix_len = int_start - prefix_start;
          size_t saved_pos = out_pos;
 
          if (out_pos >= prefix_len) {
            out_pos -= prefix_len;
          }
 
          if (write_formatted_packet_type(fd_value, name, output, output_size, &out_pos)) {
            any_transformed = true;
            continue;
          }
 
          out_pos = saved_pos; /* Restore on failure */
        }
      }
 
      /* Check if this is a registered file descriptor */
      if (!is_already_formatted && digit_count > 0 && has_fd_prefix(message, int_start)) {
        const char *name = named_get_fd(fd_value);
        const char *reg_type = NULL;
 
        /* Fallback: check main registry for sockets registered via NAMED_REGISTER_SOCKET
         * (which uses raw integer key, not FD namespace encoding) */
        if (!name) {
          name = named_get((uintptr_t)(intptr_t)fd_value);
          if (name) {
            reg_type = named_get_type((uintptr_t)(intptr_t)fd_value);
          }
        }
 
        if (name) {
          const char *prefix_start = find_fd_prefix_start(message, int_start);
          size_t prefix_len = int_start - prefix_start;
          size_t saved_pos = out_pos;
 
          if (out_pos >= prefix_len) {
            out_pos -= prefix_len;
          }
 
          bool formatted = false;
          if (reg_type) {
            /* From main registry — use registered type and original prefix keyword */
            const char *kw_end = prefix_start;
            while (kw_end < int_start && (isalnum(*kw_end) || *kw_end == '_'))
              kw_end++;
            size_t kw_len = kw_end - prefix_start;
 
            char kw_buf[32];
            if (kw_len > 0 && kw_len < sizeof(kw_buf)) {
              memcpy(kw_buf, prefix_start, kw_len);
              kw_buf[kw_len] = '\0';
            } else {
              snprintf(kw_buf, sizeof(kw_buf), "%s", reg_type);
            }
 
            char temp[512];
            int written = snprintf(temp, sizeof(temp), "%s/%s (%s=%d)", reg_type, name, kw_buf, fd_value);
            if (written > 0 && (size_t)written < sizeof(temp) && out_pos + (size_t)written < output_size - 1) {
              memcpy(output + out_pos, temp, (size_t)written);
              out_pos += (size_t)written;
              formatted = true;
            }
          } else {
            formatted = write_formatted_fd(fd_value, name, output, output_size, &out_pos);
          }
 
          if (formatted) {
            any_transformed = true;
            continue;
          }
 
          out_pos = saved_pos; /* Restore on failure */
        }
      }
 
      /* Check if this integer has a generic type prefix (socket, client, connection, etc.)
       * DISABLED: This feature has a backtracking bug that corrupts output when applied after
       * other formatting operations. Re-enable only after fixing the backtracking logic to
       * properly track correspondence between input and output positions.
       * See commit b86fed2a8 which introduced the bug.
       */
      // NOLINTNEXTLINE(readability-simplify-boolean-expr) - Intentionally disabled code, see comment above
      if (false && !is_already_formatted && digit_count > 0) {
        const char *type_name = NULL;
        size_t type_len = 0;
        const char *prefix_start = find_generic_type_prefix(message, int_start, &type_name, &type_len);
 
        if (type_name && prefix_start != int_start) {
          /* Skip if already formatted with a name (e.g., "socket/listener.0" already has a /) */
          bool skip_format = false;
          /* Check if this looks like it's already been formatted by looking for / in the pattern */
          const char *check_ptr = prefix_start;
          while (check_ptr < int_start && *check_ptr && *check_ptr != '/') {
            check_ptr++;
          }
          if (check_ptr < int_start && *check_ptr == '/') {
            /* Already formatted (contains /), skip */
            skip_format = true;
          }
 
          if (!skip_format) {
            /* We found a type prefix like "socket", "client", etc.
             * Try to look up a registered name for this type+id */
 
            /* Normalize type name aliases: "sockfd" → "socket", "descriptor" → "fd" */
            const char *lookup_type = type_name;
            size_t lookup_len = type_len;
            if (type_len == 6 && strncmp(type_name, "sockfd", 6) == 0) {
              lookup_type = "socket";
              lookup_len = 6;
            } else if (type_len == 10 && strncmp(type_name, "descriptor", 10) == 0) {
              lookup_type = "fd";
              lookup_len = 2;
            }
 
            const char *name = named_get_by_type_and_id(lookup_type, lookup_len, fd_value);
 
            char temp_output[512];
            char type_str[32];
            char id_buffer[64];
 
            /* Safely copy type name */
            if (type_len < sizeof(type_str)) {
              memcpy(type_str, type_name, type_len);
              type_str[type_len] = '\0';
 
              int id_written = snprintf(id_buffer, sizeof(id_buffer), "%d", fd_value);
              if (id_written > 0 && id_written < (int)sizeof(id_buffer)) {
                int temp_written = 0;
                if (name) {
                  /* Format with name: type/name (type=value) */
                  temp_written =
                      snprintf(temp_output, sizeof(temp_output), "%s/%s (%s=%s)", type_str, name, type_str, id_buffer);
 
                  if (temp_written > 0 && (size_t)temp_written < sizeof(temp_output)) {
                    /* Backtrack to remove the prefix we already copied */
                    size_t prefix_len = int_start - prefix_start;
                    if (out_pos >= prefix_len) {
                      out_pos -= prefix_len;
                    }
 
                    int copy_len = temp_written;
                    if (out_pos + copy_len < output_size - 1) {
                      memcpy(output + out_pos, temp_output, copy_len);
                      out_pos += copy_len;
                      any_transformed = true;
                      continue;
                    }
                  }
                }
              }
            }
          }
        }
      }
 
      /* Not a registered FD or formatting failed - copy original number */
      if (!copy_unformatted_decimal(int_start, p, output, output_size, &out_pos)) {
        break;
      }
    } else {
      /* Check if this is the start of "type=DIGIT" pattern */
      if (*p == 't' && p + 4 < message + strlen(message) && is_type_equals_pattern(p)) {
        if (!type_equals_inside_parens(p, message)) {
          const char *digit_end = p + 5;
          int pkt_value = parse_decimal_digits(digit_end, &digit_end);
 
          if (pkt_value > 0) {
            const char *name = named_get_packet_type(pkt_value);
            if (name && write_formatted_type_equals(pkt_value, name, output, output_size, &out_pos)) {
              p = digit_end;
              any_transformed = true;
              continue;
            }
          }
        }
      }
 
      /* Regular character - copy it */
      copy_char_to_output(output, &out_pos, *p++);
    }
  }
 
  /* Null terminate */
  if (out_pos < output_size) {
    output[out_pos] = '\0';
  } else {
    output[output_size - 1] = '\0';
  }
 
  return any_transformed ? (int)out_pos : -1;
}

References named_get(), named_get_by_type_and_id(), named_get_fd(), named_get_packet_type(), and named_get_type().

Referenced by log_named_format_or_original().

log_named_format_or_original()

const char * log_named_format_or_original

(

const char *

message

)

#include <named.h>

Format named objects in a message (thread-local buffer)

Parameters

message

Input message

Returns

Formatted message string if any formatting was applied, original message if no formatting was applied

Convenience wrapper that handles buffer management internally using a thread-local buffer. The returned pointer is valid only until the next call to this function from the same thread.

Safe to use directly in log macros:

log_info("State: %s", log_named_format_or_original(msg));

Note

Maximum formatted message length is 4096 bytes

If format buffer overflows, returns original message

Parameters

message

Input message

Returns

Formatted message string (thread-local buffer, valid only until next call)

Convenience wrapper that uses a thread-local buffer internally. Applies formatting iteratively until the message stops changing (fixpoint). Returns the original message if no formatting was applied.

Definition at line 913 of file log/named.c.

                                                              {
  if (!message) {
    return message;
  }
 
  static _Thread_local char format_buffer[NAMED_FORMAT_BUFFER_SIZE];
  static _Thread_local char work_buffer[NAMED_FORMAT_BUFFER_SIZE];
 
  /* Apply formatting iteratively until the message stabilizes (no more changes) */
  const char *current = message;
  size_t max_iterations =
      3; /* Reduce iterations to prevent recursion (prevent transforming already-transformed output) */
 
  for (size_t iter = 0; iter < max_iterations; iter++) {
    int result = log_named_format_message(current, format_buffer, sizeof(format_buffer));
 
    if (result <= 0) {
      /* No transformation was made, we've reached a fixpoint */
      return current == message ? message : format_buffer;
    }
 
    /* Check if the message changed */
    if (strcmp(current, format_buffer) == 0) {
      /* No actual change, return the current version */
      return format_buffer;
    }
 
    /* Message changed, prepare for next iteration */
    if (current == message) {
      /* First iteration, use format_buffer as input for next iteration */
      current = format_buffer;
    } else {
      /* Subsequent iterations, swap buffers */
      asciichat_error_t strcpy_result = SAFE_STRCPY(work_buffer, sizeof(work_buffer), format_buffer);
      if (strcpy_result != ASCIICHAT_OK) {
        log_error("Failed to copy format buffer: %s", asciichat_error_string(strcpy_result));
        return format_buffer;
      }
      current = work_buffer;
    }
  }
 
  /* Max iterations reached, return last formatted version */
  return format_buffer;
}

References ASCIICHAT_OK, log_error, log_named_format_message(), NAMED_FORMAT_BUFFER_SIZE, and SAFE_STRCPY.

Referenced by log_template_apply().

log_net_message()

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,
			...
	)

#include <log.h>

Log a message to all destinations (network, file, and terminal).

Parameters

sockfd	Destination socket
crypto_ctx	Optional crypto context for encryption (NULL if not ready)
level	Log severity used for remote and local logging
direction	Remote log direction metadata
file	Source file name (or NULL to omit)
line	Source line number (or 0 to omit)
func	Function name (or NULL to omit)
fmt	Format string (printf-style)
...	Format arguments

Returns

ASCIICHAT_OK on success, error code otherwise

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

                                                        {
  va_list args;
  va_start(args, fmt);
  asciichat_error_t result =
      log_network_message_internal(sockfd, crypto_ctx, level, direction, file, line, func, fmt, args);
  va_end(args);
  return result;
}

References args.

log_network_message()

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,
			...
	)

#include <log.h>

Send a formatted log message over the network.

Parameters

sockfd	Destination socket
crypto_ctx	Optional crypto context for encryption (NULL if not ready)
level	Log severity used for remote and local logging
direction	Remote log direction metadata
fmt	Format string (printf-style)
...	Format arguments

Returns

ASCIICHAT_OK on success, error code otherwise

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

                                                                                              {
  va_list args;
  va_start(args, fmt);
  asciichat_error_t result =
      log_network_message_internal(sockfd, crypto_ctx, level, direction, NULL, 0, NULL, fmt, args);
  va_end(args);
  return result;
}

References args.

Referenced by disconnect_client_for_bad_data(), and threaded_send_client_join_packet().

log_plain_msg()

void log_plain_msg	(	const char *	fmt,
			...
	)

#include <log.h>

Plain logging without timestamps or levels.

Parameters

fmt	Format string (printf-style)
...	Format arguments

Writes to both log file and stderr without timestamps or log levels.

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

                                         {
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    return;
  }
 
  if (shutdown_is_requested()) {
    return;
  }
 
  char log_buffer[LOG_MSG_BUFFER_SIZE];
  va_list args;
  va_start(args, fmt);
  int msg_len = safe_vsnprintf(log_buffer, sizeof(log_buffer), fmt, args);
  va_end(args);
 
  if (msg_len <= 0) {
    return;
  }
 
  // Truncate at whole line boundaries to avoid UTF-8 issues
  msg_len = truncate_at_whole_line(log_buffer, msg_len, sizeof(log_buffer));
 
  // Validate UTF-8 in formatted message
  validate_log_message_utf8(log_buffer, "plain text log");
 
  // Write to mmap if active
  if (log_mmap_is_active()) {
    log_mmap_write(LOG_INFO, NULL, 0, NULL, "%s", log_buffer);
  } else {
    // Write to file with headers (atomic write syscall)
    int file_fd = atomic_load_u64(&g_log.file);
    if (file_fd >= 0 && file_fd != STDERR_FILENO) {
      // Add header with timestamp and log level to file output
      char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
      uint64_t time_ns = time_get_realtime_ns();
      get_current_time_formatted(time_buf);
 
      char header_buffer[512];
      int header_len = format_log_header(header_buffer, sizeof(header_buffer), LOG_INFO, time_buf, "lib/log/logging.c",
                                         0, "log_plain_msg", false, time_ns);
 
      if (header_len > 0) {
        write_to_log_file_atomic(header_buffer, header_len, NULL);
      }
      write_to_log_file_atomic(log_buffer, msg_len, NULL);
      write_to_log_file_atomic("\n", 1, NULL);
    }
  }
 
  // Terminal output (atomic state checks)
  if (!atomic_load_u64(&g_log.terminal_output_enabled)) {
    return;
  }
  if (atomic_load_u64(&g_log.terminal_locked)) {
    uint64_t owner = atomic_load_u64(&g_log.terminal_owner_thread);
    if (owner != (uint64_t)asciichat_thread_self()) {
      return;
    }
  }
 
  // Check if JSON format is enabled
  int json_fd = atomic_load_int(&g_log.json_file);
  bool json_format_enabled = (json_fd >= 0);
 
  if (json_format_enabled) {
    // Output JSON for plain messages too
    uint64_t time_ns = time_get_realtime_ns();
    int console_fd = terminal_choose_log_fd(LOG_INFO);
    log_json_write(console_fd, LOG_INFO, time_ns, __FILE__, __LINE__, "log_plain_msg", log_buffer);
  } else {
    // Choose output stream using unified routing logic (LOG_INFO level)
    int fd = terminal_choose_log_fd(LOG_INFO);
    FILE *output_stream = (fd == STDERR_FILENO) ? stderr : stdout;
 
    // Apply colorization for TTY output
    if (terminal_should_color_output(fd)) {
      const char *colorized_msg = colorize_log_message(log_buffer);
      safe_fprintf(output_stream, "%s\n", colorized_msg);
    } else {
      safe_fprintf(output_stream, "%s\n", log_buffer);
    }
    (void)fflush(output_stream);
  }
}

References args, asciichat_thread_self, atomic_load_int(), atomic_load_u64(), colorize_log_message(), get_current_time_formatted(), lifecycle_is_initialized(), LOG_INFO, log_json_write(), log_mmap_is_active(), log_mmap_write(), LOG_MSG_BUFFER_SIZE, LOG_TIMESTAMP_BUFFER_SIZE, safe_fprintf(), safe_vsnprintf(), shutdown_is_requested(), terminal_choose_log_fd(), terminal_should_color_output(), and time_get_realtime_ns().

log_plain_stderr_msg()

void log_plain_stderr_msg	(	const char *	fmt,
			...
	)

#include <log.h>

Plain logging to stderr with newline.

Parameters

fmt	Format string (printf-style)
...	Format arguments

Writes to both log file and stderr without timestamps or log levels, with trailing newline.

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

                                                {
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    return;
  }
  if (shutdown_is_requested()) {
    return;
  }
 
  va_list args;
  va_start(args, fmt);
  log_plain_stderr_internal_atomic(fmt, args, true);
  va_end(args);
}

References args, lifecycle_is_initialized(), and shutdown_is_requested().

log_plain_stderr_nonewline_msg()

void log_plain_stderr_nonewline_msg	(	const char *	fmt,
			...
	)

#include <log.h>

Plain logging to stderr without trailing newline.

Parameters

fmt	Format string (printf-style)
...	Format arguments

Writes to both log file and stderr without timestamps, log levels, or trailing newline. Useful for interactive prompts where the user's response should be on the same line.

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

                                                          {
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    return;
  }
  if (shutdown_is_requested()) {
    return;
  }
 
  va_list args;
  va_start(args, fmt);
  log_plain_stderr_internal_atomic(fmt, args, false);
  va_end(args);
}

References args, lifecycle_is_initialized(), and shutdown_is_requested().

log_plain_stdout_msg()

void log_plain_stdout_msg	(	const char *	fmt,
			...
	)

#include <log.h>

Plain logging to stdout with newline.

Parameters

fmt	Format string (printf-style)
...	Format arguments

Writes to both log file and stdout without timestamps or log levels, with trailing newline. Used for informational output like device listings.

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

                                                {
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    return;
  }
  if (shutdown_is_requested()) {
    return;
  }
 
  va_list args;
  va_start(args, fmt);
  log_plain_stdout_internal_atomic(fmt, args, true);
  va_end(args);
}

References args, lifecycle_is_initialized(), and shutdown_is_requested().

log_recolor_plain_entry()

size_t log_recolor_plain_entry	(	const char *	plain_line,
		char *	colored_buf,
		size_t	buf_size
	)

#include <log.h>

Recolor a plain (non-colored) log line with proper ANSI codes.

Converts a plain text log line (from log file) into a colored version matching the format used for terminal output. Applies colors to:

• Timestamp and level based on log level
• Thread ID in grey
• File path in cyan
• Line number in magenta
• Function name in orange/DEV color
• Message body colorized appropriately

Expected plain format (debug mode): [TIMESTAMP] [LEVEL] [tid:THREAD_ID] FILE:LINE in FUNC(): MESSAGE

Parameters

plain_line	Plain text log line (from log file)
colored_buf	Output buffer for colored version (must be large enough)
buf_size	Size of colored_buf

Returns

Length of colored string, 0 on error or invalid format

Note

Uses static buffer internally, result is reused across calls

Parses plain log format: [TIMESTAMP] [LEVEL] [tid:THREAD_ID] FILE:LINE in FUNC(): MESSAGE And recolors it with appropriate ANSI codes matching the colored format.

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

                                                                                           {
  if (!plain_line || !colored_buf || buf_size < 128) {
    return 0;
  }
 
  static char work_buffer[LOG_MSG_BUFFER_SIZE + 1024];
 
  // Parse format FIRST, regardless of color availability
  // Parse format: [TIMESTAMP] [LEVEL] [tid:THREAD_ID] FILE:LINE in FUNC(): MESSAGE
  const char *p = plain_line;
 
  // Extract timestamp [TIMESTAMP]
  if (*p != '[') {
    return 0; // Invalid format
  }
  p++;
  const char *timestamp_start = p;
 
  // Find the closing ] for timestamp - look for pattern that ends with proper timestamp format
  // Valid timestamp: HH:MM:SS.UUUUUU (time with microseconds, no date)
  while (*p && *p != ']') {
    p++;
  }
  if (*p != ']') {
    return 0; // Malformed - no closing bracket
  }
 
  size_t timestamp_len = p - timestamp_start;
  char timestamp[64];
  if (timestamp_len >= sizeof(timestamp) || timestamp_len == 0) {
    return 0; // Invalid timestamp - empty or too long
  }
  SAFE_STRNCPY(timestamp, timestamp_start, timestamp_len);
  timestamp[timestamp_len] = '\0';
  p++; // Skip ]
 
  // Skip whitespace after timestamp
  while (*p && *p == ' ') {
    p++;
  }
 
  // Extract level [LEVEL]
  if (*p != '[') {
    return 0; // Missing opening bracket for level
  }
  p++;
  const char *level_start = p;
  while (*p && *p != ']') {
    p++;
  }
  if (*p != ']') {
    return 0; // Missing closing bracket for level
  }
  size_t level_len = p - level_start;
  char level_str[16];
  if (level_len >= sizeof(level_str) || level_len == 0) {
    return 0; // Level string too long or empty
  }
  memcpy(level_str, level_start, level_len);
  level_str[level_len] = '\0';
 
  // Determine log level for color selection
  log_level_t level = LOG_INFO; // Default
  if (strstr(level_str, "DEV") || strstr(level_str, "DEBUG")) {
    level = LOG_DEBUG;
  } else if (strstr(level_str, "INFO")) {
    level = LOG_INFO;
  } else if (strstr(level_str, "WARN")) {
    level = LOG_WARN;
  } else if (strstr(level_str, "ERROR")) {
    level = LOG_ERROR;
  } else if (strstr(level_str, "FATAL")) {
    level = LOG_FATAL;
  }
 
  p++; // Skip ]
 
  // Skip whitespace after level
  while (*p && *p == ' ') {
    p++;
  }
 
  // Extract thread ID [tid:THREAD_ID] - optional field
  uint64_t tid = 0;
  if (*p == '[' && strncmp(p, "[tid:", 5) == 0) {
    p += 5;
    char *tid_end = NULL;
    tid = strtoull(p, &tid_end, 10);
    if (!tid_end || *tid_end != ']') {
      // tid parsing failed, but continue anyway (might still recover)
      // Try to find the closing bracket
      while (*p && *p != ']') {
        p++;
      }
      if (*p == ']') {
        p++;
      }
    } else {
      p = tid_end + 1; // Skip past the ]
    }
    // Skip whitespace after tid
    while (*p && *p == ' ') {
      p++;
    }
  }
  // tid is optional - continue parsing if not present
 
  // Extract file path (everything up to :LINE)
  const char *file_start = p;
  while (*p && *p != ':') {
    p++;
  }
  if (*p != ':') {
    return 0; // Malformed
  }
  size_t file_len = p - file_start;
  char file_path[256];
  if (file_len >= sizeof(file_path)) {
    return 0;
  }
  memcpy(file_path, file_start, file_len);
  file_path[file_len] = '\0';
  p++; // Skip :
 
  // Extract line number (digits only)
  int line_num = 0;
  const char *line_start = p;
  while (*p && isdigit((unsigned char)*p)) {
    p++;
  }
  if (p == line_start) {
    return 0; // No line number
  }
  line_num = (int)strtol(line_start, NULL, 10);
 
  // Skip whitespace and find "in" keyword (be very lenient)
  while (*p && (*p == ' ' || *p == '\t' || *p == '\n' || *p == '\r')) {
    p++;
  }
 
  // Try to find "in " - if not found, might still be valid, just harder to parse
  if (strncmp(p, "in ", 3) == 0) {
    p += 3; // Skip "in "
  } else if (*p == 'i' && *(p + 1) == 'n' && (*(p + 2) == ' ' || *(p + 2) == '\t')) {
    // Allow tab after "in"
    p += 2; // Skip "in"
    while (*p && (*p == ' ' || *p == '\t')) {
      p++;
    }
  } else {
    // Missing "in" keyword - this is a format error
    return 0;
  }
 
  // Extract function name (everything up to "()")
  const char *func_start = p;
  while (*p && *p != '(') {
    p++;
  }
  if (*p != '(' || func_start == p) {
    return 0; // Missing function name or parentheses
  }
  size_t func_len = p - func_start;
 
  // Trim trailing whitespace from function name
  while (func_len > 0 && (func_start[func_len - 1] == ' ' || func_start[func_len - 1] == '\t')) {
    func_len--;
  }
 
  char func_name[256];
  if (func_len >= sizeof(func_name)) {
    func_len = sizeof(func_name) - 1;
  }
  if (func_len > 0) {
    memcpy(func_name, func_start, func_len);
  }
  func_name[func_len] = '\0';
 
  // Skip "(" and ")" - be lenient about what's between them
  if (*p == '(') {
    p++;
    while (*p && *p != ')') {
      p++;
    }
    if (*p == ')') {
      p++;
    }
  }
 
  // Skip whitespace and optional colon(s) and other separators
  while (*p && (*p == ' ' || *p == ':' || *p == '\t')) {
    p++;
  }
 
  // Remaining is the message
  const char *message = p;
 
  // Format is valid, get colors from logging system
  const char **colors = log_get_color_array();
  if (!colors) {
    // No colors available, return plain text
    static bool warned_once = false;
    if (!warned_once) {
      log_debug("WARNING: log_recolor_plain_entry() called but colors not initialized - returning plain text");
      warned_once = true;
    }
    size_t len = strlen(plain_line);
    if (len >= buf_size) {
      return 0;
    }
    SAFE_STRNCPY(colored_buf, plain_line, buf_size - 1);
    colored_buf[buf_size - 1] = '\0';
    return len;
  }
 
  // Build colored output
  const char *level_color = colors[level];
  const char *reset = colors[LOG_COLOR_RESET];
  const char *file_color = colors[1]; // DEBUG/Cyan
  const char *line_color = colors[6]; // GREY (matching tid)
  const char *func_color = colors[0]; // DEV/Orange
  const char *tid_color = colors[6];  // GREY
 
  int len = safe_snprintf(work_buffer, sizeof(work_buffer),
                          "[%s%s%s] [%s%s%s] [tid:%s%llu%s] %s%s%s:%s%d%s in %s%s%s(): %s", level_color, timestamp,
                          reset, level_color, level_str, reset, tid_color, (unsigned long long)tid, reset, file_color,
                          file_path, reset, line_color, line_num, reset, func_color, func_name, reset, message);
 
  if (len <= 0 || len >= (int)sizeof(work_buffer)) {
    return 0;
  }
 
  // Colorize the message part
  const char *colorized_msg = colorize_log_message(message);
  len = safe_snprintf(work_buffer, sizeof(work_buffer),
                      "[%s%s%s] [%s%s%s] [tid:%s%llu%s] %s%s%s:%s%d%s in %s%s%s(): %s", level_color, timestamp, reset,
                      level_color, level_str, reset, tid_color, (unsigned long long)tid, reset, file_color, file_path,
                      reset, line_color, line_num, reset, func_color, func_name, reset, colorized_msg);
 
  if (len <= 0 || len >= (int)sizeof(work_buffer) || len >= (int)buf_size) {
    return 0;
  }
 
  SAFE_STRNCPY(colored_buf, work_buffer, buf_size - 1);
  colored_buf[buf_size - 1] = '\0';
  return (size_t)len;
}

References colorize_log_message(), file_path, LOG_COLOR_RESET, log_debug, LOG_DEBUG, LOG_ERROR, LOG_FATAL, log_get_color_array(), LOG_INFO, LOG_MSG_BUFFER_SIZE, LOG_WARN, safe_snprintf(), and SAFE_STRNCPY.

log_redetect_terminal_capabilities()

void log_redetect_terminal_capabilities

(

void

)

#include <log.h>

Re-detect terminal capabilities after logging is initialized.

Useful when terminal capabilities change or need to be refreshed.

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

                                              {
 
  // Guard against recursion
  if (g_log.terminal_caps_detecting) {
    return;
  }
 
  // Detect if not initialized, or if we're using defaults (not reliably detected)
  // This ensures we get proper detection after logging is ready, replacing any defaults
  // Once we have reliable detection, never re-detect to keep colors consistent
  if (!g_log.terminal_caps_initialized || !g_log.terminal_caps.detection_reliable) {
    g_log.terminal_caps_detecting = true;
    g_log.terminal_caps = detect_terminal_capabilities();
    g_log.terminal_caps_detecting = false;
    g_log.terminal_caps_initialized = true;
 
    // Now log the capabilities AFTER colors are set, so this log uses the correct colors
    log_debug("Terminal capabilities: color_level=%d, capabilities=0x%x, utf8=%s, fps=%d",
              g_log.terminal_caps.color_level, g_log.terminal_caps.capabilities,
              g_log.terminal_caps.utf8_support ? "yes" : "no", g_log.terminal_caps.desired_fps);
 
    // Now that we've detected once with reliable results, keep these colors consistent for all future logs
  } else {
  }
  // Once initialized with reliable detection, never re-detect to keep colors consistent
}

References detect_terminal_capabilities(), and log_debug.

Referenced by log_init(), log_system_init(), and main().

log_set_color_scheme()

void log_set_color_scheme

(

const color_scheme_t *

scheme

)

#include <log.h>

Set the color scheme for logging output.

Parameters

scheme

Color scheme to apply (must not be NULL)

Updates the compiled ANSI color codes based on the new color scheme. Must be called after colors_init() to have an effect.

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

                                                        {
  if (!scheme) {
    return;
  }
 
  /* Mutex is managed by colors.c - just use it */
  mutex_lock(&g_colorscheme_mutex);
 
  /* Detect terminal background */
  terminal_background_t background = detect_terminal_background();
 
  /* Determine color mode for compilation */
  terminal_color_mode_t mode;
  if (g_log.terminal_caps.color_level >= TERM_COLOR_TRUECOLOR) {
    mode = TERM_COLOR_TRUECOLOR;
  } else if (g_log.terminal_caps.color_level >= TERM_COLOR_256) {
    mode = TERM_COLOR_256;
  } else {
    mode = TERM_COLOR_16;
  }
 
  /* Compile the new color scheme */
  asciichat_error_t result = colorscheme_compile_scheme(scheme, mode, background, &g_log.compiled_colors);
 
  g_log.log_colorscheme_initialized = true;
  mutex_unlock(&g_colorscheme_mutex);
 
  /* Log outside of mutex lock to avoid recursive lock deadlock */
  if (result != ASCIICHAT_OK) {
    log_debug("Failed to compile color scheme: %d", result);
  }
}

References ASCIICHAT_OK, colorscheme_compile_scheme(), detect_terminal_background(), g_colorscheme_mutex, log_debug, mutex_lock, mutex_unlock, TERM_COLOR_16, TERM_COLOR_256, and TERM_COLOR_TRUECOLOR.

Referenced by main(), and options_init().

log_set_flush_delay()

void log_set_flush_delay

(

unsigned int

delay_ms

)

#include <log.h>

Set the delay between flushing buffered log entries.

When terminal output is re-enabled after an interactive prompt, buffered log entries are flushed to the terminal. This setting adds a delay between each entry for a visual animation effect.

Parameters

delay_ms

Delay in milliseconds between each log entry (0 = no delay)

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

                                                {
  atomic_store_u64(&g_log.flush_delay_ms, delay_ms);
}

References atomic_store_u64().

log_set_force_stderr()

void log_set_force_stderr

(

bool

enabled

)

#include <log.h>

Force all terminal log output to stderr.

Parameters

enabled

true to force all logs to stderr, false for normal routing

When enabled, all log messages (including INFO, DEBUG, DEV) go to stderr instead of the default behavior where INFO/DEBUG/DEV go to stdout and WARN/ERROR/FATAL go to stderr. This is used by the client to keep stdout clean for ASCII art output.

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

                                        {
  atomic_store_u64(&g_log.force_stderr, enabled);
}

References atomic_store_u64(), and enabled.

Referenced by main(), session_client_like_run(), and session_display_create().

log_set_format()

asciichat_error_t log_set_format	(	const char *	format_str,
		bool	console_only
	)

#include <log.h>

Set a custom log format string.

Parameters

format_str	Format string with specifiers like time(H:M:S), level, message, etc. Pass NULL to use default format. Empty string "" also uses default.
console_only	If true, apply format only to console output (file logs use default)

Returns

ASCIICHAT_OK on success, error code on failure

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

                                                                            {
  /* Free old format if it exists */
  if (g_log.format) {
    log_template_free(g_log.format);
    g_log.format = NULL;
  }
  if (g_log.format_console_only) {
    log_template_free(g_log.format_console_only);
    g_log.format_console_only = NULL;
  }
 
  /* Use default format if NULL or empty string */
  const char *format_to_use = (format_str && format_str[0] != '\0') ? format_str : OPT_LOG_TEMPLATE_DEFAULT;
  bool is_custom = (format_str && format_str[0] != '\0');
 
  /* Parse the format string (always parse, never skip) */
  log_template_t *parsed_format = log_template_parse(format_to_use, false);
 
  if (!parsed_format) {
    log_error("Failed to parse log format: %s", format_to_use);
    return SET_ERRNO(ERROR_INVALID_STATE, "Invalid log format string");
  }
 
  /* If console_only is true, we also need the default format for file output */
  if (console_only && is_custom) {
    log_template_t *default_format = log_template_parse(OPT_LOG_TEMPLATE_DEFAULT, false);
 
    if (!default_format) {
      log_template_free(parsed_format);
      log_error("Failed to parse default log format");
      return SET_ERRNO(ERROR_INVALID_STATE, "Failed to parse default format");
    }
    g_log.format = default_format;
    g_log.format_console_only = parsed_format;
  } else {
    g_log.format = parsed_format;
    g_log.format_console_only = NULL;
  }
 
  atomic_store_u64(&g_log.has_custom_format, is_custom);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, atomic_store_u64(), ERROR_INVALID_STATE, log_error, log_template_free(), log_template_parse(), OPT_LOG_TEMPLATE_DEFAULT, and SET_ERRNO.

Referenced by client_init_with_args(), log_init(), main(), and mirror_init_with_args().

log_set_level()

void log_set_level

(

log_level_t

level

)

#include <log.h>

Set the minimum log level.

Parameters

level

Minimum log level to output

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

                                      {
  atomic_store_u64(&g_log.level, (int)level);
  atomic_store_bool(&g_log.level_manually_set, true);
}

References atomic_store_bool(), and atomic_store_u64().

Referenced by main().

log_set_session_log_buffer()

void log_set_session_log_buffer

(

session_log_buffer_t *

buf

)

#include <log.h>

Register a session log buffer with the logger.

Once registered, all log messages are appended to the buffer in addition to being written to files/terminal. Used by splash and status screens.

Parameters

buf	Buffer instance to register (can be NULL to unregister)

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

                                                           {
  atomic_ptr_store(&g_log.session_log_buffer, (void *)buf);
}

References atomic_ptr_store().

Referenced by splash_log_init(), ui_mdns_log_init(), and ui_status_log_init().

log_set_terminal_output()

void log_set_terminal_output

(

bool

enabled

)

#include <log.h>

Control stderr output to terminal.

Parameters

enabled

true to enable terminal output, false to disable

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

                                           {
  // Respect --quiet flag: if quiet is set, never enable terminal output
  // But allow disabling even if options are unavailable (for shutdown cleanup)
 
  // Only check quiet flag when ENABLING output to avoid deadlock with
  // concurrent logging from other threads (options_get() can deadlock when
  // called while other threads are actively logging due to RCU synchronization)
  if (enabled) {
    const options_t *opts = options_get();
    if (opts && opts->quiet) {
      return; // Silently ignore attempts to enable terminal output when --quiet is set
    }
  }
 
  atomic_store_u64(&g_log.terminal_output_enabled, enabled);
}

References atomic_store_u64(), enabled, options_get(), and options_state::quiet.

Referenced by asciichat_shared_init(), display_disable_logging_for_first_frame(), main(), options_init(), server_connection_cleanup(), server_connection_close(), server_connection_establish(), session_client_like_run(), and session_render_loop().

log_shutdown_begin()

void log_shutdown_begin

(

void

)

#include <log.h>

Begin shutdown phase - disable console logging but keep file logging.

Call this before logging shutdown messages. Disables console output but keeps file logging so messages are recorded for debugging.

Useful when you want final messages (like "no servers found") to go to the log file only, not to stdout where it might interfere with output.

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

                              {
  if (g_log.shutdown_in_progress) {
    return; /* Already in shutdown phase */
  }
 
  /* Save current terminal output state and disable console output */
  g_log.shutdown_saved_terminal_output = atomic_load_u64(&g_log.terminal_output_enabled);
  atomic_store_bool(&g_log.terminal_output_enabled, false);
  g_log.shutdown_in_progress = true;
}

References atomic_load_u64(), and atomic_store_bool().

Referenced by asciichat_shared_destroy().

log_shutdown_end()

void log_shutdown_end

(

void

)

#include <log.h>

End shutdown phase - restore previous logging settings.

Call after shutdown messages have been logged to restore console output.

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

                            {
  if (!g_log.shutdown_in_progress) {
    return; /* Not in shutdown phase, skip terminal state restoration */
  }
 
  /* Restore previous terminal output state */
  atomic_store_u64(&g_log.terminal_output_enabled, g_log.shutdown_saved_terminal_output);
  g_log.shutdown_in_progress = false;
}

References atomic_store_u64().

Referenced by asciichat_shared_destroy().

log_system_destroy()

void log_system_destroy

(

void

)

#include <log.h>

Shutdown the logging system internal state (system-level cleanup)

Restores terminal state and clears registered session log buffer. Must be called once at program shutdown AFTER log_destroy(). Safe to call multiple times (idempotent).

Clears registered session log buffer. Color cleanup is handled separately in asciichat_shared_destroy() after memory reporting. Must be called once at program shutdown AFTER log_destroy(). Safe to call multiple times (idempotent).

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

                              {
  // Unregister session log buffer if registered
  log_clear_session_log_buffer();
}

References log_clear_session_log_buffer().

Referenced by asciichat_shared_destroy().

log_system_init()

void log_system_init

(

void

)

#include <log.h>

Initialize the logging system internal state (system-level init)

Initializes g_log struct, detects terminal capabilities, and compiles colors. Must be called once at program startup BEFORE log_init(). Safe to call multiple times (idempotent).

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

                           {
 
  // Detect terminal capabilities if not already done
  log_redetect_terminal_capabilities();
 
  // Initialize color scheme based on terminal capabilities
  log_init_colors();
}

References log_init_colors(), and log_redetect_terminal_capabilities().

Referenced by asciichat_shared_init().

log_template_apply()

int log_template_apply	(	const log_template_t *	format,
		char *	buf,
		size_t	buf_size,
		log_level_t	level,
		const char *	timestamp,
		const char *	file,
		int	line,
		const char *	func,
		uint64_t	tid,
		const char *	message,
		bool	use_colors,
		uint64_t	time_nanoseconds
	)

#include <format.h>

Apply format to a log entry and write result to buffer.

Parameters

format	Compiled format (from log_template_parse)
buf	Output buffer
buf_size	Output buffer size
level	Log level
timestamp	Pre-formatted timestamp string
file	Source file name (or NULL)
line	Source line number (or 0)
func	Function name (or NULL)
tid	Thread ID
message	Log message text
use_colors	If true, apply ANSI color codes
time_nanoseconds	Raw wall-clock time in nanoseconds (for microseconds and nanoseconds)

Returns

Number of characters written (excluding null terminator), or -1 on error

Renders the compiled format using provided log entry values. Evaluates each specifier and writes results to output buffer.

Example:

log_template_t *fmt = log_template_parse("[%time(%H:%M:%S)] [%level] %microseconds %message", false);
char output[512];
uint64_t now = time_get_realtime_ns();
int len = log_template_apply(fmt, output, sizeof(output),
                           LOG_INFO, "14:30:45", "test.c", 42, "main",
                           1234, "Test message", false, now);

Definition at line 491 of file log/format.c.

                                                                                        {
  /* Check all critical pointers - format could be freed by another thread (TOCTOU race) */
  if (!format || !buf || buf_size == 0) {
    return -1;
  }
 
  int total_written = 0;
  char *p = buf;
  size_t remaining = buf_size - 1; /* Reserve space for null terminator */
 
  (void)timestamp; /* May be used in future; for now, LOG_FORMAT_TIME uses custom formatting */
 
  /* Safety check: verify format->specs is valid before dereferencing
   * This protects against use-after-free if format is freed by another thread (TOCTOU race).
   * Between our initial NULL check and here, the main thread may have freed this memory. */
  if (!format || !format->specs || format->spec_count == 0) {
    return -1;
  }
 
  for (size_t i = 0; i < format->spec_count; i++) {
    /* Re-check specs pointer in loop to catch use-after-free during iteration */
    if (!format->specs || i >= format->spec_count) {
      break; /* Format was freed, stop processing */
    }
    const log_format_spec_t *spec = &format->specs[i];
 
    /* Additional safety check: if spec is null or invalid, stop processing */
    if (!spec) {
      break;
    }
 
    int written = 0;
 
    switch (spec->type) {
    case LOG_FORMAT_LITERAL:
      written = safe_snprintf(p, remaining + 1, "%s", spec->literal ? spec->literal : "");
      break;
 
    case LOG_FORMAT_TIME:
      /* Format time using custom time formatter */
      if (spec->literal) {
        written = time_format_now(spec->literal, p, remaining + 1);
        if (written <= 0) {
          log_debug("time_format_now failed for format: %s", spec->literal);
          written = 0;
        }
      }
      break;
 
    case LOG_FORMAT_LEVEL:
      /* Log level as string (DEV, DEBUG, INFO, WARN, ERROR, FATAL) */
      written = safe_snprintf(p, remaining + 1, "%s", get_level_string(level));
      break;
 
    case LOG_FORMAT_LEVEL_ALIGNED:
      /* Log level padded to exactly 5 characters (prevents truncation to [DEBU]/[ERRO]) */
      written = safe_snprintf(p, remaining + 1, "%s", get_level_string_padded(level));
      break;
 
    case LOG_FORMAT_FILE:
      if (file) {
        written = safe_snprintf(p, remaining + 1, "%s", file);
      }
      break;
 
    case LOG_FORMAT_FILE_RELATIVE:
      if (file) {
        const char *rel_file = extract_project_relative_path(file);
        written = safe_snprintf(p, remaining + 1, "%s", rel_file);
      }
      break;
 
    case LOG_FORMAT_LINE:
      if (line > 0) {
        written = safe_snprintf(p, remaining + 1, "%d", line);
      }
      break;
 
    case LOG_FORMAT_FUNC:
      if (func) {
        written = safe_snprintf(p, remaining + 1, "%s", func);
      }
      break;
 
    case LOG_FORMAT_TID:
      written = safe_snprintf(p, remaining + 1, "%llu", (unsigned long long)tid);
      break;
 
    case LOG_FORMAT_TNAME: {
      asciichat_thread_t thread = (asciichat_thread_t)tid;
      uintptr_t key = asciichat_thread_to_key(thread);
      const char *tname = named_get(key);
      if (tname) {
        written = safe_snprintf(p, remaining + 1, "%s", tname);
      } else {
        written = safe_snprintf(p, remaining + 1, "%llu", (unsigned long long)tid);
      }
      break;
    }
 
    case LOG_FORMAT_MICROSECONDS: {
      /* Extract microseconds from nanoseconds (ns_value % 1_000_000_000 / 1000) */
      long nanoseconds = (long)(time_nanoseconds % NS_PER_SEC_INT);
      long microseconds = nanoseconds / 1000;
      if (microseconds < 0)
        microseconds = 0;
      if (microseconds > 999999)
        microseconds = 999999;
      written = safe_snprintf(p, remaining + 1, "%06ld", microseconds);
      break;
    }
 
    case LOG_FORMAT_NANOSECONDS: {
      /* Extract nanoseconds component (ns_value % 1_000_000_000) */
      long nanoseconds = (long)(time_nanoseconds % NS_PER_SEC_INT);
      if (nanoseconds < 0)
        nanoseconds = 0;
      if (nanoseconds > 999999999)
        nanoseconds = 999999999;
      written = safe_snprintf(p, remaining + 1, "%09ld", nanoseconds);
      break;
    }
 
    case LOG_FORMAT_STRFTIME_CODE: {
      /* strftime format code (like %H, %M, %S, %A, %B, etc.)
       * Let strftime handle all the parsing and validation */
      if (spec->literal && spec->literal_len < 64) {
        /* Construct format string with % prefix on stack */
        char format_str[66]; /* 1 (%) + 64 (literal) + 1 (null) */
        format_str[0] = '%';
        memcpy(format_str + 1, spec->literal, spec->literal_len);
        format_str[spec->literal_len + 1] = '\0';
        written = time_format_now(format_str, p, remaining + 1);
        if (written <= 0) {
          log_debug("time_format_now failed for format code: %s", format_str);
          written = 0;
        }
      }
      break;
    }
 
    case LOG_FORMAT_MESSAGE:
      if (message) {
        /* Format hex addresses as named object descriptions (type/name format) */
        const char *formatted_msg = log_named_format_or_original(message);
        written = safe_snprintf(p, remaining + 1, "%s", formatted_msg);
      }
      break;
 
    case LOG_FORMAT_COLORED_MESSAGE: {
      /* Apply colorize_log_message() for number/unit/hex highlighting, then format named objects */
      if (message) {
        const char *formatted_msg = log_named_format_or_original(message);
        const char *colorized_msg = colorize_log_message(formatted_msg);
        written = safe_snprintf(p, remaining + 1, "%s", colorized_msg);
      }
      break;
    }
 
    case LOG_FORMAT_COLORLOG_LEVEL:
      /* Color code for the log level (placeholder for future color support) */
      (void)use_colors; /* Suppress unused parameter warning */
      written = 0;
      break;
 
    case LOG_FORMAT_COLOR: {
      /* Parse and apply %color(LEVEL, content)
       * literal stores "LEVEL,content" where LEVEL is the color level name (or "*" for current level)
       * and content is a format string to render and colorize */
      if (!spec->literal || spec->literal_len == 0) {
        written = 0;
        break;
      }
 
      /* Find the comma separating LEVEL and content */
      const char *comma_pos = strchr(spec->literal, ',');
      if (!comma_pos) {
        /* Invalid format - no comma found */
        log_debug("log_template_apply: %%color format missing comma in: %s", spec->literal);
        written = 0;
        break;
      }
 
      /* Extract level name (before comma) */
      size_t level_len = comma_pos - spec->literal;
      char level_name[32];
      if (level_len >= sizeof(level_name)) {
        /* Level name too long */
        written = 0;
        break;
      }
      memcpy(level_name, spec->literal, level_len);
      level_name[level_len] = '\0';
 
      /* Parse level name to log_color_t (pass current level for "*" support) */
      log_color_t color = parse_color_level(level_name, level);
 
      /* Extract content (after comma), skip leading whitespace */
      const char *content_start = comma_pos + 1;
      while (*content_start == ' ' || *content_start == '\t') {
        content_start++;
      }
 
      /* Render content recursively */
      char content_buf[512];
      int content_len = render_format_content(content_start, content_buf, sizeof(content_buf), level, timestamp, file,
                                              line, func, tid, message, use_colors, time_nanoseconds);
 
      if (content_len < 0 || content_len >= (int)sizeof(content_buf)) {
        written = 0;
        break;
      }
 
      /* Apply color to rendered content using colored_string */
      const char *colored_content = colored_string(color, content_buf);
 
      /* Copy colored content to output buffer */
      written = safe_snprintf(p, remaining + 1, "%s", colored_content);
      break;
    }
 
    case LOG_FORMAT_NEWLINE:
      /* Platform-aware newline */
#ifdef _WIN32
      written = safe_snprintf(p, remaining + 1, "\r\n");
#else
      written = safe_snprintf(p, remaining + 1, "\n");
#endif
      break;
 
    default:
      break;
    }
 
    if (written < 0) {
      /* snprintf error */
      return -1;
    }
 
    if ((size_t)written > remaining) {
      /* Buffer overflow prevention */
      log_debug("log_template_apply: buffer overflow prevented");
      return -1;
    }
 
    p += written;
    remaining -= written;
    total_written += written;
  }
 
  *p = '\0';
  return total_written;
}

References asciichat_thread_to_key(), colored_string(), colorize_log_message(), extract_project_relative_path(), get_level_string_padded(), log_format_spec_t::literal, log_format_spec_t::literal_len, log_debug, LOG_FORMAT_COLOR, LOG_FORMAT_COLORED_MESSAGE, LOG_FORMAT_COLORLOG_LEVEL, LOG_FORMAT_FILE, LOG_FORMAT_FILE_RELATIVE, LOG_FORMAT_FUNC, LOG_FORMAT_LEVEL, LOG_FORMAT_LEVEL_ALIGNED, LOG_FORMAT_LINE, LOG_FORMAT_LITERAL, LOG_FORMAT_MESSAGE, LOG_FORMAT_MICROSECONDS, LOG_FORMAT_NANOSECONDS, LOG_FORMAT_NEWLINE, LOG_FORMAT_STRFTIME_CODE, LOG_FORMAT_TID, LOG_FORMAT_TIME, LOG_FORMAT_TNAME, log_named_format_or_original(), named_get(), NS_PER_SEC_INT, safe_snprintf(), log_template_t::spec_count, log_template_t::specs, time_format_now(), and log_format_spec_t::type.

Referenced by backtrace_print().

log_template_free()

void log_template_free

(

log_template_t *

format

)

#include <format.h>

Free compiled format structure.

Parameters

format

Pointer to format to free (safe to call with NULL)

Definition at line 325 of file log/format.c.

                                               {
  if (!format) {
    SET_ERRNO(ERROR_INVALID_PARAM, "null format");
    return;
  }
 
  if (format->specs) {
    for (size_t i = 0; i < format->spec_count; i++) {
      if (format->specs[i].literal) {
        free(format->specs[i].literal);
        format->specs[i].literal = NULL;
      }
    }
    free(format->specs);
    format->specs = NULL;
  }
 
  if (format->original) {
    free(format->original);
    format->original = NULL;
  }
 
  free(format);
  format = NULL;
}

References ERROR_INVALID_PARAM, log_format_spec_t::literal, log_template_t::original, SET_ERRNO, log_template_t::spec_count, and log_template_t::specs.

Referenced by log_destroy(), and log_set_format().

log_template_parse()

log_template_t * log_template_parse	(	const char *	format_str,
		bool	console_only
	)

#include <format.h>

Parse a format string into compiled format structure.

Parameters

format_str	Format string (e.g., "[%time(%H:%M:%S)] [%level_aligned] %message")
console_only	If true, format applies only to console (not file)

Returns

Compiled format, or NULL on parse error

Parses format string and compiles it into efficient specifier array. Format string must be valid UTF-8. Returns NULL on:

• Invalid UTF-8 in format string
• Invalid format specifiers
• Malformed time(format) syntax
• Memory allocation failure

Note

Errors are logged with details about what failed

Definition at line 321 of file log/format.c.

                                                                              {
  return parse_format_string(format_str, console_only);
}

Referenced by log_set_format().

log_terminal_msg()

void log_terminal_msg	(	log_level_t	level,
		const char *	file,
		int	line,
		const char *	func,
		const char *	fmt,
			...
	)

#include <log.h>

Log a message to terminal only (no file output)

Parameters

level	Log level (LOG_DEV, LOG_DEBUG, LOG_INFO, LOG_WARN, LOG_ERROR, LOG_FATAL)
file	Source file name (or NULL to omit)
line	Source line number (or 0 to omit)
func	Function name (or NULL to omit)
fmt	Format string (printf-style)
...	Format arguments

Logs to terminal only, skipping file/mmap output. WARN/ERROR/FATAL go to stderr, other levels go to stdout (unless force_stderr is enabled).

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

                                                                                                             {
  // Lock-free: only uses atomic loads, no mutex
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    return;
  }
 
  if (level < (log_level_t)atomic_load_u64(&g_log.level)) {
    return;
  }
 
  // Terminal output only - no file/mmap writing
  char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
  uint64_t time_ns = time_get_realtime_ns();
  get_current_time_formatted(time_buf);
 
  va_list args;
  va_start(args, fmt);
  write_to_terminal_atomic(level, time_buf, file, line, func, fmt, args, time_ns);
  va_end(args);
}

References args, atomic_load_u64(), get_current_time_formatted(), lifecycle_is_initialized(), LOG_TIMESTAMP_BUFFER_SIZE, and time_get_realtime_ns().

log_truncate_if_large()

void log_truncate_if_large

(

void

)

#include <log.h>

Manually truncate large log files.

Checks if the log file exceeds MAX_LOG_SIZE and truncates it if necessary.

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

                                 {
  // Log rotation is inherently racy without locks - best-effort only
  // For reliable rotation, use mmap mode or external logrotate
  int file = atomic_load_int(&g_log.file);
  if (file >= 0 && file != STDERR_FILENO && strlen(g_log.filename) > 0) {
    struct stat st;
    if (fstat(file, &st) == 0 && st.st_size > MAX_LOG_SIZE) {
      atomic_store_u64(&g_log.current_size, (size_t)st.st_size);
    }
  }
}

References atomic_load_int(), atomic_store_u64(), and MAX_LOG_SIZE.

Referenced by main().

log_unlock_terminal()

void log_unlock_terminal

(

bool

previous_state

)

#include <log.h>

Release terminal lock and flush buffered messages.

Call this after interactive prompts complete to release the terminal lock. Buffered log messages from other threads will be flushed to terminal.

Parameters

previous_state

The value returned by log_lock_terminal()

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

                                              {
  atomic_store_u64(&g_log.terminal_locked, previous_state);
  if (!previous_state) {
    atomic_store_u64(&g_log.terminal_owner_thread, 0);
  }
}

References atomic_store_u64().

Referenced by client_crypto_handshake(), prompt_password(), prompt_unknown_host(), and ui_mdns_select().