Logging System

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

Files
file	logging.c
	📝 Multi-level logging with terminal color support, file rotation, and async output
file	logging.h
	📝 Logging API with multiple log levels and terminal output control
file	mmap.c
	Lock-free memory-mapped text logging implementation.
file	mmap.h
	Lock-free memory-mapped text logging with crash safety.
file	logging.h
	Network logging macros and remote log direction enumeration.

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

Macros
#define	LOG_ATOMIC_UINT64   _Atomic uint64_t
#define	LOG_ATOMIC_UINT64_INIT(val)   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_COMPILE_LEVEL   LOG_DEV
	Compile-time minimum log level (DEV keeps all, allowing runtime -vvv)
#define	log_every(log_level, interval_us, fmt, ...)
	Rate-limited logging macro (thread-safe)
#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 log_mmap_config	log_mmap_config_t
typedef enum remote_log_direction	remote_log_direction_t
	Remote log packet direction enumeration.

Enumerations
enum	log_level_t {   LOG_DEV = 0 , LOG_DEBUG , LOG_INFO , LOG_WARN ,   LOG_ERROR , LOG_FATAL }
	Logging levels enumeration. More...
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_RESET = 6 }
	Color enum for logging - indexes into color arrays. 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
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_set_level (log_level_t level)
	Set the minimum log level.
log_level_t	log_get_level (void)
	Get the current minimum log level.
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_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_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_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.
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.

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_dev(...)   log_msg(LOG_DEV, __FILE__, __LINE__, __func__, __VA_ARGS__)
	Log a DEV message (most verbose, development only)
#define	log_debug(...)   log_msg(LOG_DEBUG, __FILE__, __LINE__, __func__, __VA_ARGS__)
	Log a DEBUG message.
#define	log_info(...)   log_msg(LOG_INFO, __FILE__, __LINE__, __func__, __VA_ARGS__)
	Log an INFO message.
#define	log_warn(...)   log_msg(LOG_WARN, __FILE__, __LINE__, __func__, __VA_ARGS__)
	Log a WARN message.
#define	log_error(...)   log_msg(LOG_ERROR, __FILE__, __LINE__, __func__, __VA_ARGS__)
	Log an ERROR message.
#define	log_fatal(...)   log_msg(LOG_FATAL, __FILE__, __LINE__, __func__, __VA_ARGS__)
	Log a FATAL message.
#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_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.

Rate-Limited Logging Macros
#define	log_dev_every(interval_us, fmt, ...)   log_every(DEV, interval_us, fmt, ##__VA_ARGS__)
	Rate-limited DEV logging.
#define	log_debug_every(interval_us, fmt, ...)   log_every(DEBUG, interval_us, fmt, ##__VA_ARGS__)
	Rate-limited DEBUG logging.
#define	log_info_every(interval_us, fmt, ...)   log_every(INFO, interval_us, fmt, ##__VA_ARGS__)
	Rate-limited INFO logging.
#define	log_warn_every(interval_us, fmt, ...)   log_every(WARN, interval_us, fmt, ##__VA_ARGS__)
	Rate-limited WARN logging.
#define	log_error_every(interval_us, fmt, ...)   log_every(ERROR, interval_us, fmt, ##__VA_ARGS__)
	Rate-limited ERROR logging.
#define	log_fatal_every(interval_us, fmt, ...)   log_every(FATAL, interval_us, fmt, ##__VA_ARGS__)
	Rate-limited FATAL logging.

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.

Logging README

Overview

Welcome to the logging system! If you've ever tried to debug a complex program without good logging, you know the pain. The logging system is your debugging best friend—it helps you understand what's happening in your application, track down bugs, and monitor behavior in production.

Think of logging as your application's diary. It writes down everything that happens: when clients connect, when errors occur, when packets are processed. You can configure how chatty it should be (from super verbose DEBUG mode to quiet ERROR-only mode), and you can send the output to the console, to a file, or both!

Implementation: lib/logging.h

What makes this logging system helpful?

• Six log levels: DEV, DEBUG, INFO, WARN, ERROR, FATAL (choose your verbosity)
• Rate limiting: Prevents log spam in tight loops (your disk will thank you)
• Flexible output: Console, file, or both simultaneously
• Thread-safe: Multiple threads can log without stepping on each other
• Context tracking: Automatic timestamps and source location (file:line)
• Pretty colors: Colored console output so errors jump out at you
• Runtime configuration: Change log level on the fly via environment variable

Log Levels

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

DEV (0) - The super chatty one:

• Use this for development-only messages that are too verbose for normal debugging
• Useful for tracing code paths during active development
• Usually disabled even in debug builds unless you need extreme detail

DEBUG (1) - The chatty one:

• Use this when you need detailed diagnostic information
• Only available in debug builds (stripped out in release for performance)
• Perfect for understanding exactly what's happening step by step

INFO (2) - The reporter:

• General informational messages about normal operations
• "Client connected", "Frame processed", that sort of thing
• What you'd want to see during normal operation

WARN (3) - The concerned citizen:

• Something's not quite right, but we can keep going
• "Buffer is getting full", "Retrying connection"
• Pay attention, but don't panic

ERROR (4) - Houston, we have a problem:

• Operation failures that are recoverable
• "Failed to send packet", "Client disconnected unexpectedly"
• Things went wrong, but we're handling it

FATAL (5) - The showstopper:

• Unrecoverable errors that mean we can't continue
• "Cannot initialize crypto", "Out of memory"
• Time to gracefully shut down

Basic Usage

Basic Logging

Log Messages:

log_debug("Processing frame %d", frame_number);
log_info("Client connected: %s:%d", ip, port);
log_warn("Buffer nearly full: %zu/%zu", used, capacity);
log_error("Failed to send packet: %s", error_msg);
log_fatal("Cannot initialize crypto: %s", reason);

Format Specifiers:

log_info("Integer: %d", 42);
log_info("String: %s", "hello");
log_info("Pointer: %p", ptr);
log_info("Size: %zu bytes", size);
log_info("Hex: 0x%08x", value);

Rate-Limited Logging

Rate Limiting (prevents log spam in tight loops):

// Log at most once per second (1,000,000 microseconds)
for (int i = 0; i < 1000000; i++) {
    log_debug_every(1000000, "Processing item %d", i);
}
 
// Log at most once per 5 seconds
while (video_running) {
    log_info_every(5000000, "Video frames processed: %d", frame_count);
    process_frame();
}

Available Rate-Limited Macros:

• log_debug_every(usec, ...)
• log_info_every(usec, ...)
• log_warn_every(usec, ...)
• log_error_every(usec, ...)

Configuration

Setting Log Level

Runtime Configuration:

// Set log level to DEBUG
set_log_level(LOG_LEVEL_DEBUG);
 
// Set log level to INFO (hide debug messages)
set_log_level(LOG_LEVEL_INFO);
 
// Set log level to ERROR (only errors and fatal)
set_log_level(LOG_LEVEL_ERROR);

Environment Variable:

# Set log level via environment
export LOG_LEVEL=0  # DEV
export LOG_LEVEL=1  # DEBUG
export LOG_LEVEL=2  # INFO
export LOG_LEVEL=3  # WARN
export LOG_LEVEL=4  # ERROR
export LOG_LEVEL=5  # FATAL
 
# Run with debug logging
LOG_LEVEL=1 ./bin/ascii-chat server

File Output

Configure File Logging:

// Enable logging to file
set_log_file("/tmp/ascii-chat-server.log");
 
// Logs now go to both console and file
log_info("This appears in both console and file");
 
// Close log file
close_log_file();

Command-line Option:

# Log to file via command line
./bin/ascii-chat server --log-file=/tmp/server.log
./bin/ascii-chat client --log-file=/tmp/client.log

Output Format

Log messages have a consistent format that makes them easy to read and understand. Every message includes a timestamp, level, source location, and the actual message text. Let's look at the format:

What does a log message look like?

Log Message Format:

[TIMESTAMP] LEVEL [file:line] message

The format is simple and consistent—timestamp first (so you can see when things happened), level next (so you know how important it is), source location (so you know where in the code it came from), and the message itself.

Example Output:

[2025-01-15 14:23:45] DEBUG [server.c:234] Starting video capture thread
[2025-01-15 14:23:45] INFO  [network.c:456] Client connected: 192.168.1.100:54321
[2025-01-15 14:23:46] WARN  [audio.c:123] Audio buffer 80% full
[2025-01-15 14:23:47] ERROR [crypto.c:789] Handshake failed: invalid signature

Notice how you can see exactly when things happened, what level they are, where in the code they came from, and what the message is. This makes debugging much easier!

What about colors?

Console Colors (ANSI terminals):

• DEV: Dim Gray (even more subtle, for development tracing)
• DEBUG: Gray (subtle, so it doesn't distract from important messages)
• INFO: White (default color, for normal messages)
• WARN: Yellow (gets your attention, but not too alarming)
• ERROR: Red (you should pay attention to this!)
• FATAL: Bold Red (this is serious!)

Colors make it easy to scan logs—errors jump out in red, warnings in yellow. If you're in a terminal that supports colors, this makes debugging much easier.

Thread Safety

Mutex Protection:

• All logging operations are protected by a global mutex
• Safe for concurrent logging from multiple threads
• No output interleaving

Thread Identification:

• Thread ID automatically captured (debug builds)
• Helps trace multi-threaded execution

Example Multi-threaded Logging:

void* worker_thread(void *arg) {
    log_info("Worker thread started");  // Thread-safe
 
    for (int i = 0; i < 1000; i++) {
        // Rate-limited, thread-safe
        log_debug_every(1000000, "Processing item %d", i);
    }
 
    log_info("Worker thread finished");
    return NULL;
}

Performance Considerations

Logging performance is important—you don't want logging to slow down your application. We've designed the system to be efficient, but there are some things to keep in mind:

How do we keep logging fast?

Rate Limiting:

• Use log_*_every() in high-frequency code paths: If you're logging in a tight loop, use rate limiting so you don't flood the logs
• Prevents log spam and performance degradation: Without rate limiting, logging can slow down your application significantly
• Minimal overhead when rate limit is active: Once the rate limit is active, logging is essentially free (we just check if enough time has passed, then skip logging)

Rate limiting is your friend in tight loops—you can log every iteration without actually logging every iteration!

How about file I/O?

File I/O:

• File logging adds I/O overhead: Writing to a file is slower than writing to console, but it's still pretty fast for most use cases
• Consider async file writing for high-throughput: If you're logging a lot (thousands of messages per second), you might want async file writing
• Use buffered output for better performance: We use buffered I/O, so multiple log messages can be written in one operation

File logging is pretty fast—we use buffered I/O, so most of the time you won't notice the overhead. If you're logging hundreds of messages per second, you might want to consider rate limiting or async logging.

What about string formatting?

String Formatting:

• Avoid expensive formatting in hot paths: String formatting (like sprintf()) can be slow if you're doing it thousands of times per second
• Use rate limiting for frequent messages: If you're logging frequently, rate limiting reduces the number of format operations
• Consider conditional compilation for debug logs: Debug logs can be compiled out entirely in release builds, so they have zero overhead

String formatting is usually pretty fast, but if you're doing it millions of times per second, it can add up. Use rate limiting for frequent messages, and remember that debug logs are compiled out in release builds!

Best Practices

DO:

• Use appropriate log levels
• Use rate limiting in tight loops
• Include relevant context (IDs, values)
• Use structured messages
• Log errors with error codes

DON'T:

• Don't use printf() directly (use log_*() instead)
• Don't log in tight loops without rate limiting
• Don't log sensitive data (passwords, keys)
• Don't use DEBUG level for production
• Don't log every iteration of a loop

Examples:

// ✅ GOOD - Rate limited
for (int i = 0; i < 1000000; i++) {
    log_debug_every(1000000, "Processed %d items", i);
}
 
// ❌ BAD - Logs 1 million times!
for (int i = 0; i < 1000000; i++) {
    log_debug("Processing item %d", i);
}
 
// ✅ GOOD - Contextual error message
log_error("Failed to send packet to client %u: %s", client_id, error_msg);
 
// ❌ BAD - Generic message
log_error("Send failed");

Integration with Error System

Automatic Error Logging:

• SET_ERRNO() macros automatically log errors
• Error context included in log messages
• File/line/function captured automatically

Example:

if (socket_fd < 0) {
    // Automatically logs: "ERROR: Failed to create socket"
    return SET_ERRNO(ERROR_NETWORK_SOCKET, "Failed to create socket");
}

See also

logging.h

asciichat_errno.h

common.h

Macro Definition Documentation

DEFAULT_LOG_LEVEL

#define DEFAULT_LOG_LEVEL   LOG_DEBUG

#include <logging.h>

Default log level for debug builds (DEBUG and above)

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

LOG_ATOMIC_UINT64

#define LOG_ATOMIC_UINT64   _Atomic uint64_t

#include <logging.h>

Definition at line 42 of file log/logging.h.

LOG_ATOMIC_UINT64_INIT

#define LOG_ATOMIC_UINT64_INIT

(

val

)

val

#include <logging.h>

Definition at line 44 of file log/logging.h.

LOG_CLIENT_IMPL

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

#include <logging.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/logging.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_COMPILE_LEVEL

#define LOG_COMPILE_LEVEL   LOG_DEV

#include <logging.h>

Compile-time minimum log level (DEV keeps all, allowing runtime -vvv)

Definition at line 119 of file log/logging.h.

log_debug

#define log_debug

(

...

)

log_msg(LOG_DEBUG, __FILE__, __LINE__, __func__, __VA_ARGS__)

#include <logging.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 450 of file log/logging.h.

log_debug_client

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

#include <logging.h>

Server sends DEBUG log message to client.

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

log_debug_every

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

#include <logging.h>

Rate-limited DEBUG logging.

Definition at line 604 of file log/logging.h.

log_debug_server

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

#include <logging.h>

Client sends DEBUG log message to server.

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

log_dev

#define log_dev

(

...

)

log_msg(LOG_DEV, __FILE__, __LINE__, __func__, __VA_ARGS__)

#include <logging.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 432 of file log/logging.h.

log_dev_every

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

#include <logging.h>

Rate-limited DEV logging.

Definition at line 601 of file log/logging.h.

log_error

#define log_error

(

...

)

log_msg(LOG_ERROR, __FILE__, __LINE__, __func__, __VA_ARGS__)

#include <logging.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 501 of file log/logging.h.

log_error_client

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

#include <logging.h>

Server sends ERROR log message to client.

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

log_error_every

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

#include <logging.h>

Rate-limited ERROR logging.

Definition at line 613 of file log/logging.h.

log_error_server

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

#include <logging.h>

Client sends ERROR log message to server.

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

log_every

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

#include <logging.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_explicit(&_log_every_last_time, memory_order_relaxed);                      \
    if (_log_every_now - _log_every_last >= (uint64_t)(interval_us)) {                                                 \
      if (atomic_compare_exchange_weak_explicit(&_log_every_last_time, &_log_every_last, _log_every_now,               \
                                                memory_order_relaxed, memory_order_relaxed)) {                         \
        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 581 of file log/logging.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_explicit(&_log_every_last_time, memory_order_relaxed);                      \
    if (_log_every_now - _log_every_last >= (uint64_t)(interval_us)) {                                                 \
      if (atomic_compare_exchange_weak_explicit(&_log_every_last_time, &_log_every_last, _log_every_now,               \
                                                memory_order_relaxed, memory_order_relaxed)) {                         \
        log_msg(LOG_##log_level, __FILE__, __LINE__, __func__, fmt, ##__VA_ARGS__);                                    \
      }                                                                                                                \
    }                                                                                                                  \
  } while (0)

log_fatal

#define log_fatal

(

...

)

log_msg(LOG_FATAL, __FILE__, __LINE__, __func__, __VA_ARGS__)

#include <logging.h>

Log a FATAL message.

Parameters

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

Note

FATAL messages are never stripped (always compiled in).

Definition at line 517 of file log/logging.h.

log_fatal_client

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

#include <logging.h>

Server sends FATAL log message to client.

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

log_fatal_every

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

#include <logging.h>

Rate-limited FATAL logging.

Definition at line 616 of file log/logging.h.

log_fatal_server

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

#include <logging.h>

Client sends FATAL log message to server.

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

log_file

#define log_file

(

...

)

log_file_msg(__VA_ARGS__)

#include <logging.h>

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

Parameters

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

Definition at line 546 of file log/logging.h.

LOG_HEADER_BUFFER_SIZE

#define LOG_HEADER_BUFFER_SIZE   512

#include <logging.h>

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

Definition at line 101 of file log/logging.h.

log_info

#define log_info

(

...

)

log_msg(LOG_INFO, __FILE__, __LINE__, __func__, __VA_ARGS__)

#include <logging.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 467 of file log/logging.h.

log_info_client

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

#include <logging.h>

Server sends INFO log message to client.

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

log_info_every

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

#include <logging.h>

Rate-limited INFO logging.

Definition at line 607 of file log/logging.h.

log_info_server

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

#include <logging.h>

Client sends INFO log message to server.

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

LOG_MMAP_MSG_BUFFER_SIZE

#define LOG_MMAP_MSG_BUFFER_SIZE   1024

#include <logging.h>

Maximum size of a log message in mmap mode.

Definition at line 98 of file log/logging.h.

LOG_MSG_BUFFER_SIZE

#define LOG_MSG_BUFFER_SIZE   4096

#include <logging.h>

Maximum size of a single log message (including formatting)

Definition at line 95 of file log/logging.h.

log_plain

#define log_plain

(

...

)

log_plain_msg(__VA_ARGS__)

#include <logging.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 525 of file log/logging.h.

log_plain_stderr

#define log_plain_stderr

(

...

)

log_plain_stderr_msg(__VA_ARGS__)

#include <logging.h>

Plain logging to stderr with newline.

Parameters

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

Definition at line 532 of file log/logging.h.

log_plain_stderr_nonewline

#define log_plain_stderr_nonewline

(

...

)

log_plain_stderr_nonewline_msg(__VA_ARGS__)

#include <logging.h>

Plain logging to stderr without newline - for interactive prompts.

Parameters

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

Definition at line 539 of file log/logging.h.

LOG_SERVER_IMPL

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

#include <logging.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/logging.h.

LOG_TIMESTAMP_BUFFER_SIZE

#define LOG_TIMESTAMP_BUFFER_SIZE   32

#include <logging.h>

Maximum size of a timestamp string.

Definition at line 104 of file log/logging.h.

log_warn

#define log_warn

(

...

)

log_msg(LOG_WARN, __FILE__, __LINE__, __func__, __VA_ARGS__)

#include <logging.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 484 of file log/logging.h.

log_warn_client

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

#include <logging.h>

Server sends WARN log message to client.

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

log_warn_every

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

#include <logging.h>

Rate-limited WARN logging.

Definition at line 610 of file log/logging.h.

log_warn_server

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

#include <logging.h>

Client sends WARN log message to server.

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

MAX_LOG_SIZE

#define MAX_LOG_SIZE   (3 * 1024 * 1024)

#include <logging.h>

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

Definition at line 79 of file log/logging.h.

MAX_TERMINAL_BUFFER_ENTRIES

#define MAX_TERMINAL_BUFFER_ENTRIES   256

#include <logging.h>

Maximum number of buffered log entries.

Definition at line 85 of file log/logging.h.

MAX_TERMINAL_BUFFER_SIZE

#define MAX_TERMINAL_BUFFER_SIZE   (64 * 1024)

#include <logging.h>

Maximum size of terminal output buffer (64KB)

Definition at line 82 of file log/logging.h.

Typedef Documentation

log_mmap_config_t

typedef struct log_mmap_config log_mmap_config_t

#include <logging.h>

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

remote_log_direction_t

typedef enum remote_log_direction remote_log_direction_t

#include <logging.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

Enumeration Type Documentation

log_color_t

enum log_color_t

#include <logging.h>

Color enum for logging - indexes into color arrays.

These values directly index into level_colors arrays. Order matches DEV, DEBUG, INFO, WARN, ERROR, FATAL, 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_RESET	Reset to default

Definition at line 137 of file log/logging.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_RESET = 6  
} log_color_t;

log_level_t

enum log_level_t

#include <logging.h>

Logging levels enumeration.

Note

This typedef MUST be defined before #include "network/logging.h" to avoid circular dependency issues with packet.h

Enumerator
LOG_DEV	Development messages (most verbose)
LOG_DEBUG	Debug messages
LOG_INFO	Informational messages
LOG_WARN	Warning messages
LOG_ERROR	Error messages
LOG_FATAL	Fatal error messages (most severe)

Definition at line 59 of file log/logging.h.

             {
  LOG_DEV = 0, 
  LOG_DEBUG,   
  LOG_INFO,    
  LOG_WARN,    
  LOG_ERROR,   
  LOG_FATAL    
} log_level_t;

remote_log_direction

enum remote_log_direction

#include <logging.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/logging.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

format_message()

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

#include <logging.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 157 of file log/logging.c.

                                                       {
  if (!format) {
    return NULL;
  }
 
  // First, determine the size needed
  va_list args_copy;
  va_copy(args_copy, args);
  int size = 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 = 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 ERROR_INVALID_STATE, LOGGING_INTERNAL_ERROR, SAFE_FREE, and SAFE_MALLOC.

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 <logging.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 126 of file log/logging.c.

                                                  {
  /* Log the rotation event */
  struct timespec ts;
  (void)clock_gettime(CLOCK_REALTIME, &ts);
  struct tm tm_info;
  platform_localtime(&ts.tv_sec, &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
  long microseconds = ts.tv_nsec / 1000;
  if (microseconds < 0)
    microseconds = 0;
  if (microseconds > 999999)
    microseconds = 999999;
 
  int result = 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, and platform_localtime().

Referenced by log_msg().

log_destroy()

void log_destroy

(

void

)

#include <logging.h>

Destroy the logging system and close log file.

Definition at line 459 of file log/logging.c.

                       {
  // Destroy mmap logging first (if active)
  if (log_mmap_is_active()) {
    log_mmap_destroy();
  }
 
  // Lock-free cleanup using atomic operations
  int old_file = atomic_load(&g_log.file);
  if (old_file >= 0 && old_file != STDERR_FILENO) {
    platform_close(old_file);
  }
  atomic_store(&g_log.file, -1);
  atomic_store(&g_log.initialized, false);
 
  // Destroy rotation mutex
  if (atomic_load(&g_log.rotation_mutex_initialized)) {
    mutex_destroy(&g_log.rotation_mutex);
    atomic_store(&g_log.rotation_mutex_initialized, false);
  }
}

References log_mmap_destroy(), log_mmap_is_active(), mutex_destroy(), and platform_close().

Referenced by main(), and server_main().

log_disable_mmap()

void log_disable_mmap

(

void

)

#include <logging.h>

Disable mmap logging and return to mutex-based logging.

Flushes remaining entries and closes the mmap file.

Definition at line 1129 of file log/logging.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 <logging.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 1110 of file log/logging.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 <logging.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 1114 of file log/logging.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 <logging.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 923 of file log/logging.c.

                                        {
  if (!atomic_load(&g_log.initialized)) {
    return;
  }
 
  char log_buffer[LOG_MSG_BUFFER_SIZE];
  va_list args;
  va_start(args, fmt);
  int msg_len = vsnprintf(log_buffer, sizeof(log_buffer), fmt, args);
  va_end(args);
 
  if (msg_len <= 0 || msg_len >= (int)sizeof(log_buffer)) {
    return;
  }
 
  // 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(&g_log.file);
    if (file_fd >= 0 && file_fd != STDERR_FILENO) {
      write_to_log_file_atomic(log_buffer, msg_len);
      write_to_log_file_atomic("\n", 1);
    }
  }
}

References LOG_INFO, log_mmap_is_active(), log_mmap_write(), and LOG_MSG_BUFFER_SIZE.

Referenced by client_main().

log_get_color_array()

const char ** log_get_color_array

(

void

)

#include <logging.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 1079 of file log/logging.c.

                                       {
  init_terminal_capabilities();
 
  log_color_mode_t mode;
  if (g_terminal_caps.color_level >= TERM_COLOR_TRUECOLOR) {
    mode = LOG_CMODE_TRUECOLOR;
  } else if (g_terminal_caps.color_level >= TERM_COLOR_256) {
    mode = LOG_CMODE_256;
  } else {
    mode = LOG_CMODE_16;
  }
 
  /* Cast away const for the pointer-to-pointer return - the array is still const */
  return (const char **)level_colors[mode];
}

References terminal_capabilities_t::color_level, LOG_CMODE_16, LOG_CMODE_256, LOG_CMODE_TRUECOLOR, TERM_COLOR_256, and TERM_COLOR_TRUECOLOR.

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

log_get_force_stderr()

bool log_get_force_stderr

(

void

)

#include <logging.h>

Get current force_stderr setting.

Returns

true if all logs are forced to stderr, false otherwise

Definition at line 510 of file log/logging.c.

                                {
  return atomic_load(&g_log.force_stderr);
}

log_get_level()

log_level_t log_get_level

(

void

)

#include <logging.h>

Get the current minimum log level.

Returns

Current log level

Definition at line 485 of file log/logging.c.

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

Referenced by options_init().

log_get_terminal_output()

bool log_get_terminal_output

(

void

)

#include <logging.h>

Get current terminal output setting.

Returns

true if terminal output is enabled, false otherwise

Definition at line 502 of file log/logging.c.

                                   {
  return atomic_load(&g_log.terminal_output_enabled);
}

log_init()

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

#include <logging.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 386 of file log/logging.c.

                                                                                         {
  // Initialize rotation mutex (only operation that uses a mutex)
  if (!atomic_load(&g_log.rotation_mutex_initialized)) {
    mutex_init(&g_log.rotation_mutex);
    atomic_store(&g_log.rotation_mutex_initialized, true);
  }
 
  // Set basic config using atomic stores
  atomic_store(&g_log.force_stderr, force_stderr);
  bool preserve_terminal_output = atomic_load(&g_log.terminal_output_enabled);
 
  // Close any existing file (atomic load/store)
  int old_file = atomic_load(&g_log.file);
  if (atomic_load(&g_log.initialized) && old_file >= 0 && old_file != STDERR_FILENO) {
    platform_close(old_file);
    atomic_store(&g_log.file, -1);
  }
 
  // Check LOG_LEVEL environment variable
  const char *env_level_str = SAFE_GETENV("LOG_LEVEL");
  if (env_level_str) {
    atomic_store(&g_log.level, (int)parse_log_level_from_env());
  } else {
    atomic_store(&g_log.level, (int)level);
  }
 
  atomic_store(&g_log.level_manually_set, false);
  atomic_store(&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(&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(&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(filename, O_CREAT | O_RDWR | O_TRUNC, FILE_PERM_PRIVATE);
      atomic_store(&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(&g_log.file, STDERR_FILENO);
    g_log.filename[0] = '\0';
  }
 
  atomic_store(&g_log.initialized, true);
  atomic_store(&g_log.terminal_output_enabled, preserve_terminal_output);
 
  // Reset terminal detection if needed
  if (g_terminal_caps_initialized && !g_terminal_caps.detection_reliable) {
    g_terminal_caps_initialized = false;
  }
 
  // Detect terminal capabilities
  log_redetect_terminal_capabilities();
}

References ASCIICHAT_OK, terminal_capabilities_t::detection_reliable, FILE_PERM_PRIVATE, log_mmap_init_simple(), log_redetect_terminal_capabilities(), mutex_init(), platform_close(), platform_open(), safe_fprintf(), SAFE_GETENV, and SAFE_STRNCPY.

Referenced by asciichat_shared_init(), and main().

log_labeled()

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

#include <logging.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 98 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%s: %s\n", log_level_color(color), label, log_level_color(LOG_COLOR_RESET),
               formatted_message);
 
  log_file("%s: %s", label, formatted_message);
 
  SAFE_FREE(formatted_message);
}

References format_message(), LOG_COLOR_RESET, log_file, log_level_color(), safe_fprintf(), and SAFE_FREE.

Referenced by asciichat_fatal_with_context().

log_level_color()

const char * log_level_color

(

log_color_t

color

)

#include <logging.h>

Get color string for a given color enum.

Parameters

color

Color enum value

Returns

ANSI color code string

Definition at line 1095 of file log/logging.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 asciichat_print_error_context(), and log_labeled().

log_lock_terminal()

bool log_lock_terminal

(

void

)

#include <logging.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 514 of file log/logging.c.

                             {
  bool previous_state = atomic_exchange(&g_log.terminal_locked, true);
  atomic_store(&g_log.terminal_owner_thread, (uint64_t)asciichat_thread_self());
  return previous_state;
}

References asciichat_thread_self().

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

log_msg()

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

#include <logging.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 695 of file log/logging.c.

                                                                                                    {
  // All state access uses atomic operations - fully lock-free
  if (!atomic_load(&g_log.initialized)) {
    return;
  }
 
  if (level < (log_level_t)atomic_load(&g_log.level)) {
    return;
  }
 
  /* =========================================================================
   * MMAP PATH: When mmap logging is active, writes go to mmap'd file
   * ========================================================================= */
  if (log_mmap_is_active()) {
    maybe_rotate_log();
 
    va_list args;
    va_start(args, fmt);
    char msg_buffer[LOG_MMAP_MSG_BUFFER_SIZE];
    vsnprintf(msg_buffer, sizeof(msg_buffer), fmt, args);
    va_end(args);
 
    log_mmap_write(level, file, line, func, "%s", msg_buffer);
 
    // Terminal output (check with atomic loads)
    if (atomic_load(&g_log.terminal_output_enabled) && !atomic_load(&g_log.terminal_locked)) {
      char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
      get_current_time_formatted(time_buf);
 
      FILE *output_stream;
      if (atomic_load(&g_log.force_stderr)) {
        output_stream = stderr;
      } else {
        output_stream = (level == LOG_ERROR || level == LOG_WARN || level == LOG_FATAL) ? stderr : stdout;
      }
      int fd = output_stream == stderr ? STDERR_FILENO : STDOUT_FILENO;
      bool use_colors = isatty(fd);
 
      char header_buffer[512];
      int header_len =
          format_log_header(header_buffer, sizeof(header_buffer), level, time_buf, file, line, func, use_colors, false);
 
      if (header_len > 0 && header_len < (int)sizeof(header_buffer)) {
        if (use_colors) {
          const char **colors = log_get_color_array();
          if (colors) {
            safe_fprintf(output_stream, "%s%s%s%s\n", header_buffer, colors[LOG_COLOR_RESET], msg_buffer,
                         colors[LOG_COLOR_RESET]);
          } else {
            safe_fprintf(output_stream, "%s%s\n", header_buffer, msg_buffer);
          }
        } else {
          safe_fprintf(output_stream, "%s%s\n", header_buffer, msg_buffer);
        }
        (void)fflush(output_stream);
      }
    }
    return;
  }
 
  /* =========================================================================
   * FILE I/O PATH: Lock-free using atomic write() syscalls
   * ========================================================================= */
  char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
  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, false);
  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 = 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;
  if (msg_len >= (int)sizeof(log_buffer)) {
    msg_len = sizeof(log_buffer) - 1;
    log_buffer[msg_len] = '\0';
  }
 
  if (msg_len > 0 && msg_len < (int)sizeof(log_buffer) - 1) {
    log_buffer[msg_len++] = '\n';
    log_buffer[msg_len] = '\0';
  }
 
  va_end(args);
 
  // Write to file (atomic write syscall)
  int file_fd = atomic_load(&g_log.file);
  if (file_fd >= 0 && file_fd != STDERR_FILENO) {
    write_to_log_file_atomic(log_buffer, msg_len);
  }
 
  // 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);
  va_end(args_terminal);
}

References ERROR_INVALID_STATE, get_current_time_formatted(), LOG_COLOR_RESET, LOG_ERROR, LOG_FATAL, log_get_color_array(), log_mmap_is_active(), LOG_MMAP_MSG_BUFFER_SIZE, log_mmap_write(), LOG_MSG_BUFFER_SIZE, LOG_TIMESTAMP_BUFFER_SIZE, LOG_WARN, LOGGING_INTERNAL_ERROR, and safe_fprintf().

Referenced by handle_remote_log_packet_from_client().

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 <logging.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 1010 of file log/logging.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;
}

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 <logging.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 1000 of file log/logging.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;
}

Referenced by disconnect_client_for_bad_data(), tcp_client_send_join(), and threaded_send_client_join_packet().

log_plain_msg()

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

#include <logging.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 807 of file log/logging.c.

                                         {
  if (!atomic_load(&g_log.initialized)) {
    return;
  }
 
  if (shutdown_is_requested()) {
    return;
  }
 
  char log_buffer[LOG_MSG_BUFFER_SIZE];
  va_list args;
  va_start(args, fmt);
  int msg_len = vsnprintf(log_buffer, sizeof(log_buffer), fmt, args);
  va_end(args);
 
  if (msg_len <= 0 || msg_len >= (int)sizeof(log_buffer)) {
    return;
  }
 
  // 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 (atomic write syscall)
    int file_fd = atomic_load(&g_log.file);
    if (file_fd >= 0 && file_fd != STDERR_FILENO) {
      write_to_log_file_atomic(log_buffer, msg_len);
      write_to_log_file_atomic("\n", 1);
    }
  }
 
  // Terminal output (atomic state checks)
  if (!atomic_load(&g_log.terminal_output_enabled)) {
    return;
  }
  if (atomic_load(&g_log.terminal_locked)) {
    uint64_t owner = atomic_load(&g_log.terminal_owner_thread);
    if (owner != (uint64_t)asciichat_thread_self()) {
      return;
    }
  }
 
  safe_fprintf(stdout, "%s\n", log_buffer);
  (void)fflush(stdout);
}

References asciichat_thread_self(), LOG_INFO, log_mmap_is_active(), log_mmap_write(), LOG_MSG_BUFFER_SIZE, safe_fprintf(), and shutdown_is_requested().

log_plain_stderr_msg()

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

#include <logging.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 895 of file log/logging.c.

                                                {
  if (!atomic_load(&g_log.initialized)) {
    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 shutdown_is_requested().

log_plain_stderr_nonewline_msg()

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

#include <logging.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 909 of file log/logging.c.

                                                          {
  if (!atomic_load(&g_log.initialized)) {
    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 shutdown_is_requested().

log_redetect_terminal_capabilities()

void log_redetect_terminal_capabilities

(

void

)

#include <logging.h>

Re-detect terminal capabilities after logging is initialized.

Useful when terminal capabilities change or need to be refreshed.

Definition at line 1054 of file log/logging.c.

                                              {
  // Guard against recursion
  if (g_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_terminal_caps_initialized || !g_terminal_caps.detection_reliable) {
    g_terminal_caps_detecting = true;
    g_terminal_caps = detect_terminal_capabilities();
    g_terminal_caps_detecting = false;
    g_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_terminal_caps.color_level,
              g_terminal_caps.capabilities, g_terminal_caps.utf8_support ? "yes" : "no", g_terminal_caps.desired_fps);
 
    // Now that we've detected once with reliable results, keep these colors consistent for all future logs
  }
  // Once initialized with reliable detection, never re-detect to keep colors consistent
}

References terminal_capabilities_t::capabilities, terminal_capabilities_t::color_level, terminal_capabilities_t::desired_fps, detect_terminal_capabilities(), terminal_capabilities_t::detection_reliable, log_debug, and terminal_capabilities_t::utf8_support.

Referenced by log_init().

log_set_flush_delay()

void log_set_flush_delay

(

unsigned int

delay_ms

)

#include <logging.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 527 of file log/logging.c.

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

log_set_force_stderr()

void log_set_force_stderr

(

bool

enabled

)

#include <logging.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 506 of file log/logging.c.

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

log_set_level()

void log_set_level

(

log_level_t

level

)

#include <logging.h>

Set the minimum log level.

Parameters

level

Minimum log level to output

Definition at line 480 of file log/logging.c.

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

Referenced by options_init().

log_set_terminal_output()

void log_set_terminal_output

(

bool

enabled

)

#include <logging.h>

Control stderr output to terminal.

Parameters

enabled

true to enable terminal output, false to disable

Definition at line 489 of file log/logging.c.

                                           {
  // Respect --quiet flag: if quiet is set, never enable terminal output
  const options_t *opts = options_get();
  if (!opts) {
    log_error("Options not initialized");
    return;
  }
  if (enabled && opts && opts->quiet) {
    return; // Silently ignore attempts to enable terminal output when --quiet is set
  }
  atomic_store(&g_log.terminal_output_enabled, enabled);
}

References log_error, options_get(), and options_state::quiet.

Referenced by asciichat_shared_init(), client_main(), display_disable_logging_for_first_frame(), mirror_main(), server_connection_cleanup(), server_connection_close(), server_connection_establish(), server_connection_lost(), and server_main().

log_shutdown_begin()

void log_shutdown_begin

(

void

)

#include <logging.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 1140 of file log/logging.c.

                              {
  if (g_shutdown_in_progress) {
    return; /* Already in shutdown phase */
  }
 
  /* Save current terminal output state and disable console output */
  g_shutdown_saved_terminal_output = atomic_load(&g_log.terminal_output_enabled);
  atomic_store(&g_log.terminal_output_enabled, false);
  g_shutdown_in_progress = true;
}

log_shutdown_end()

void log_shutdown_end

(

void

)

#include <logging.h>

End shutdown phase - restore previous logging settings.

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

Definition at line 1151 of file log/logging.c.

                            {
  if (!g_shutdown_in_progress) {
    return; /* Not in shutdown phase */
  }
 
  /* Restore previous terminal output state */
  atomic_store(&g_log.terminal_output_enabled, g_shutdown_saved_terminal_output);
  g_shutdown_in_progress = false;
}

log_truncate_if_large()

void log_truncate_if_large

(

void

)

#include <logging.h>

Manually truncate large log files.

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

Definition at line 531 of file log/logging.c.

                                 {
  // Log rotation is inherently racy without locks - best-effort only
  // For reliable rotation, use mmap mode or external logrotate
  int file = atomic_load(&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(&g_log.current_size, (size_t)st.st_size);
    }
  }
}

References MAX_LOG_SIZE.

Referenced by asciichat_shared_init().

log_unlock_terminal()

void log_unlock_terminal

(

bool

previous_state

)

#include <logging.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 520 of file log/logging.c.

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

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