Error Handling

⚠️ Thread-Local Error Number System with Context More...

Files
file	asciichat_errno.c
	🚨 Custom error code system with formatted messages, thread-local storage, and errno mapping
file	asciichat_errno.h
	⚠️‼️ Comprehensive thread-local error context system for ascii-chat

Data Structures
struct	backtrace_t
struct	asciichat_error_context_t
	Error context structure. More...
struct	asciichat_error_stats_t
	Error statistics structure. More...

Macros
#define	SET_ERRNO(code, context_msg, ...)
	Set error code with custom context message and log it, returning the error code.
#define	SET_ERRNO_SYS(code, context_msg, ...)
	Set error code with custom message and system error context, returning the error code.
#define	HAS_ERRNO(var)   asciichat_has_errno(var)
	Check if an error occurred and get full context.
#define	CLEAR_ERRNO()   asciichat_clear_errno()
	Clear the current error state.
#define	GET_ERRNO()   asciichat_get_errno()
	Get current error code (0 if no error)

Functions
void	asciichat_set_errno (asciichat_error_t code, const char *file, int line, const char *function, const char *context_message)
	Set error code with basic context.
void	asciichat_set_errno_with_message (asciichat_error_t code, const char *file, int line, const char *function, const char *format,...)
	Set error code with formatted message.
void	asciichat_set_errno_with_system_error (asciichat_error_t code, const char *file, int line, const char *function, int sys_errno)
	Set error code with system error (errno)
void	asciichat_set_errno_with_system_error_and_message (asciichat_error_t code, const char *file, int line, const char *function, int sys_errno, const char *format,...)
	Set error code with system error and formatted message.
void	asciichat_set_errno_with_wsa_error (asciichat_error_t code, const char *file, int line, const char *function, int wsa_error)
	Set error code with Windows socket error (WSA error)
bool	asciichat_has_errno (asciichat_error_context_t *context)
	Check if error occurred and get full context.
bool	asciichat_has_wsa_error (void)
	Check if current error has WSA error code.
void	asciichat_clear_errno (void)
	Clear the current error state.
asciichat_error_t	asciichat_get_errno (void)
	Get current error code.
void	asciichat_fatal_with_context (asciichat_error_t code, const char *file, int line, const char *function, const char *format,...)
	Exit with error code and context (used by FATAL macro)
void	asciichat_print_error_context (const asciichat_error_context_t *context)
	Print full error context to stderr.
void	asciichat_error_stats_init (void)
	Initialize error statistics system.
void	asciichat_error_stats_record (asciichat_error_t code)
	Record an error in statistics.
void	asciichat_error_stats_print (void)
	Print error statistics to stderr.
void	asciichat_error_stats_reset (void)
	Reset all error statistics to zero.
asciichat_error_stats_t	asciichat_error_stats_get (void)
	Get current error statistics.
asciichat_error_t	asciichat_get_thread_error (int thread_id)
	Get error code for a specific thread.
void	asciichat_set_thread_error (int thread_id, asciichat_error_t code)
	Set error code for a specific thread.
void	asciichat_clear_thread_error (int thread_id)
	Clear error code for a specific thread.
void	asciichat_errno_suppress (bool suppress)
	Suppress error logging and reporting.
void	asciichat_errno_destroy (void)
	Cleanup error system resources.

Variables
__thread asciichat_error_context_t	asciichat_errno_context
	Thread-local error context storage.
__thread asciichat_error_t	asciichat_errno
	Thread-local current error code.

Detailed Description

⚠️ Thread-Local Error Number System with Context

Overview

This header defines ascii-chat's centralized error handling system: a thread-local error number system with full context capture including location information, stack traces (debug builds), and system error integration. Rather than the limited errno semantics of standard C (which loses context), this system captures the full error story: where it happened, why it happened, and what the calling code was trying to do.

This is NOT a cosmetic improvement. Error handling is one of the most critical parts of ascii-chat. With 2,880+ SET_ERRNO calls throughout 250+ library files and 50+ source files, nearly every significant operation in the codebase uses this system. The densest users are network (91 calls in packet parsing alone), crypto (86+ in SSH key parsing, 86+ in crypto context, 68+ in handshakes), and utilities (53+ in IP parsing).

Why This Matters

Good error messages save hours of debugging. Without context:

• Network packet parsing fails silently with "invalid packet"
• Crypto handshakes break with "key exchange failed"
• IP parsing rejects addresses with "parse error"

With this system:

• "Invalid packet magic: 0xDEADBEEF (expected 0xCAFEBABE) [packet.c:247 in parse_packet_header]"
• "Server signature verification FAILED - rejecting connection [client.c:892 in handle_key_exchange_reply]"
• "Failed to parse IP address: unexpected port specifier at position 15 [ip.c:184 in parse_ipv4_address]"

Core Architecture

Thread-Local Error Context (asciichat_error_context_t):

• Error code: One of 256 possible asciichat_error_t values
• Location: File, line, function where error occurred (debug builds capture all three)
• Context message: Formatted printf-style explanation of what failed and why
• Stack trace: Full backtrace from error site (debug builds with ENABLE_ERRNO_BACKTRACES)
• System error: Integration with errno (POSIX) and WSA errors (Windows)
• Timestamp: When the error occurred (microseconds since epoch)

Library Interface (lib/ code):

• Use SET_ERRNO(code, "format", ...) to set errors with context
• Use SET_ERRNO_SYS(code, "format", ...) to capture system errno alongside app error
• Errors bubble up through the call stack (SET_ERRNO in deeper functions sets context)
• Higher-level code can CHECK errors and decide: propagate, recover, or fail

Application Interface (src/ code):

• Use HAS_ERRNO(&ctx) to check if an error occurred and get full context
• Use GET_ERRNO() to check just the error code (returns ASCIICHAT_OK if no error)
• Use CLEAR_ERRNO() to reset error state after handling
• Integrate with FATAL() to exit with full error details

Usage Patterns (From Real Code)

Pattern 1: Input Validation (Network Packet Parsing)

~1000+ locations - the most common pattern

if (!header || !pkt_type) {
  return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: header=%p, pkt_type=%p", header, pkt_type);
}
if (magic != PACKET_MAGIC) {
  return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Invalid packet magic: 0x%x (expected 0x%x)",
                   magic, PACKET_MAGIC);
}
if (len > MAX_PACKET_SIZE) {
  return SET_ERRNO(ERROR_NETWORK_SIZE, "Packet too large: %u > %d", len, MAX_PACKET_SIZE);
}

Pattern 2: Memory Allocation Failure (Crypto Operations)

~400+ locations

uint8_t *key = SAFE_MALLOC(key_size, uint8_t *);
if (!key) {
  return SET_ERRNO(ERROR_MEMORY, "Failed to allocate %zu bytes for ephemeral key", key_size);
}

Pattern 3: System Call Failure with errno (File I/O, Networking)

~166 locations - use SET_ERRNO_SYS to capture both errno and context

int fd = open(path, O_RDONLY);
if (fd < 0) {
  return SET_ERRNO_SYS(ERROR_CONFIG, "Failed to open config: %s", path);
  // Logs: "Failed to open config: /etc/ascii-chat.conf (errno: 2 - No such file)"
}

Pattern 4: Error Context Propagation

~50+ locations - deepest call checks error without overwriting

// In crypto_perform_handshake() - deep function
asciichat_error_t result = validate_server_signature(sig_data, server_key);
if (result != ASCIICHAT_OK) {
  return result;  // Propagates original error context up the call stack
}

Pattern 5: Application-Level Error Handling

~30 locations - entry points check errors after library calls

// In src/client/main.c
asciichat_error_context_t err_ctx;
if (HAS_ERRNO(&err_ctx)) {
  FATAL(err_ctx.code, "Connection failed: %s at %s:%d",
        err_ctx.context_message, err_ctx.file, err_ctx.line);
}

Thread Safety Guarantee

Each thread has completely independent error state via __thread storage:

• Setting error in thread A doesn't affect thread B's error state
• No mutex needed (no contention, no lock ordering issues)
• Perfect for multi-threaded network servers with per-client threads

Context Capture Details

In Release Builds (NDEBUG):

• File, line, function are NULL (stripped for performance)
• Context message is captured (explains what went wrong)
• System errno captured if SET_ERRNO_SYS used
• No stack trace (compiler optimizations make backtraces unreliable)
• Total overhead: one string allocation + context copy per error

In Debug Builds:

• File, line, function are captured (automatic via FILE, LINE, func)
• Context message is formatted with arguments
• System errno and/or WSA error captured
• Stack trace captured if ENABLE_ERRNO_BACKTRACES defined (configurable)
• Timestamp captured for performance analysis

Error Statistics (Monitoring & Diagnostics)

The system tracks cumulative error counts per error code across all threads:

asciichat_error_stats_t stats = asciichat_error_stats_get();
printf("Total errors seen: %llu\\n", stats.total_errors);
printf("Network errors: %llu\\n", stats.error_counts[ERROR_NETWORK]);
printf("Crypto errors: %llu\\n", stats.error_counts[ERROR_CRYPTO]);

Useful for:

• Detecting error storms (too many of one error type = bug)
• Performance monitoring (which errors consume resources?)
• Testing validation (no errors in unit tests = good)
• Production alerting (sudden spike in specific error = something broke)

Common Error Codes (From error_codes.h)

• ERROR_MEMORY: Allocation failed (malloc/calloc)
• ERROR_INVALID_PARAM: Invalid function argument
• ERROR_INVALID_STATE: Operation invalid in current state
• ERROR_NETWORK_*: Network-related errors (bind, listen, connect, etc.)
• ERROR_CRYPTO: Cryptographic operation failed
• ERROR_CONFIG: Configuration file or parsing error
• ERROR_AUDIO: Audio capture/playback error
• See lib/common/error_codes.h for complete list

Debugging with Error Context

In GDB:

(gdb) print asciichat_errno_context
$1 = {code = ERROR_CRYPTO, file = "lib/crypto/handshake/client.c", line = 892,
      function = "handle_key_exchange_reply", context_message = "Signature verification failed",
      timestamp = 1730851234567890, ...}

In Running Program (if dumped by FATAL):

[ERROR] ERROR_CRYPTO: Signature verification failed
Location: lib/crypto/handshake/client.c:892 in handle_key_exchange_reply()
Timestamp: 2025-10-06 14:07:14.567890 UTC
System error: 0 (success)
Stack trace (11 frames):
  [0] handle_key_exchange_reply (lib/crypto/handshake/client.c:892)
  [1] crypto_perform_handshake (lib/crypto/crypto.c:156)
  [2] connection_authenticate (src/client/connection.c:289)
  ... (8 more frames)

Note

Use SET_ERRNO() in library code. Macros auto-capture file/line/function.

Use HAS_ERRNO() in application code to check errors after library calls.

Stack traces are only captured in debug builds with ENABLE_ERRNO_BACKTRACES.

Thread-local storage ensures thread safety automatically (no synchronization).

This is the error handling backbone of ascii-chat. Understand it well.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

October 2025

asciichat_errno

Overview

The Error Handling System provides comprehensive error tracking and reporting for ascii-chat. It uses typed error codes, error context capture, and thread-local storage for safe multi-threaded error handling.

Implementation: lib/asciichat_errno.h

Key Features:

• Typed error codes via asciichat_error_t enum
• Thread-local error context storage
• Automatic file/line/function capture
• System error integration (errno capture)
• Error context stack traces (debug builds)
• Comprehensive error messages with context

Architecture

Error Code System:

• All functions return asciichat_error_t instead of int
• ASCIICHAT_OK (0) indicates success
• Negative values indicate specific error types
• Error codes are categorized by subsystem

Thread-Local Storage:

• Each thread has its own error context
• No cross-thread error contamination
• Safe for concurrent error handling

Error Context Capture:

• File name and line number where error occurred
• Function name where error was set
• Custom error message with printf-style formatting
• System errno value (when applicable)
• Stack trace (debug builds only)

Usage Patterns

Setting Errors

SET_ERRNO Macro (preferred):

// Set error with custom message
if (socket_fd < 0) {
    return SET_ERRNO(ERROR_NETWORK_SOCKET, "Failed to create socket");
}
 
// Set error with formatted message
if (bind(sockfd, &addr, sizeof(addr)) < 0) {
    return SET_ERRNO(ERROR_NETWORK_BIND, "Cannot bind to port %d", port);
}

SET_ERRNO_SYS Macro (captures system errno):

// Capture both error code and system errno
int fd = open(path, O_RDONLY);
if (fd < 0) {
    return SET_ERRNO_SYS(ERROR_CONFIG, "Failed to open config: %s", path);
}

Checking Errors

Check for Error:

asciichat_error_context_t err_ctx;
if (HAS_ERRNO(&err_ctx)) {
    log_error("Error: %s", err_ctx.context_message);
    log_error("  at %s:%d in %s()", err_ctx.file, err_ctx.line, err_ctx.function);
}

Get Current Error Code:

asciichat_error_t current_error = GET_ERRNO();
if (current_error != ASCIICHAT_OK) {
    // Handle error
}

Clear Error State:

CLEAR_ERRNO();  // Reset error state for this thread

Debug Output

Print Error Context (debug builds only):

asciichat_error_context_t err_ctx;
if (HAS_ERRNO(&err_ctx)) {
    PRINT_ERRNO_CONTEXT(&err_ctx);  // Prints full context including stack trace
}

Error Code Categories

General Errors:

• ASCIICHAT_OK (0) - Success
• ERROR_UNKNOWN (-1) - Unknown error
• ERROR_INVALID_PARAM (-2) - Invalid parameter
• ERROR_OUT_OF_MEMORY (-3) - Memory allocation failed

Network Errors:

• ERROR_NETWORK_SOCKET - Socket creation failed
• ERROR_NETWORK_BIND - Socket bind failed
• ERROR_NETWORK_LISTEN - Socket listen failed
• ERROR_NETWORK_CONNECT - Connection failed
• ERROR_NETWORK_SEND - Send operation failed
• ERROR_NETWORK_RECV - Receive operation failed

Crypto Errors:

• ERROR_CRYPTO_INIT - Crypto initialization failed
• ERROR_CRYPTO_KEY - Key loading/parsing failed
• ERROR_CRYPTO_HANDSHAKE - Handshake failed
• ERROR_CRYPTO_ENCRYPT - Encryption failed
• ERROR_CRYPTO_DECRYPT - Decryption failed

Platform Errors:

• ERROR_PLATFORM_THREAD - Thread operation failed
• ERROR_PLATFORM_MUTEX - Mutex operation failed
• ERROR_PLATFORM_SOCKET - Platform-specific socket error

Configuration Errors:

• ERROR_CONFIG - Configuration loading failed
• ERROR_CONFIG_PARSE - Configuration parsing failed
• ERROR_CONFIG_INVALID - Invalid configuration value

Integration with Logging

Automatic Logging:

• SET_ERRNO() automatically logs errors at ERROR level
• SET_ERRNO_SYS() logs with system error details
• Error messages include context automatically

Example Integration:

asciichat_error_t process_client(client_t *client) {
    if (!client) {
        return SET_ERRNO(ERROR_INVALID_PARAM, "Client is NULL");
        // Automatically logged: "ERROR: Client is NULL"
    }
 
    int result = some_operation();
    if (result < 0) {
        return SET_ERRNO_SYS(ERROR_OPERATION_FAILED, "Operation failed");
        // Automatically logged with errno details
    }
 
    return ASCIICHAT_OK;
}

Best Practices

DO:

• Always use asciichat_error_t for return types
• Use SET_ERRNO() for all error conditions
• Use SET_ERRNO_SYS() when capturing system errors
• Provide descriptive error messages
• Check return values and propagate errors

DON'T:

• Don't use int return values with -1 for errors
• Don't ignore return values
• Don't use generic error messages
• Don't access errno directly (use SET_ERRNO_SYS)
• Don't forget to check errors from called functions

Thread Safety

Thread-Local Storage:

• Each thread maintains its own error context
• No locks needed for error operations
• Safe for concurrent error handling
• Thread ID captured in error context

Example Multi-threaded Usage:

void* worker_thread(void *arg) {
    // This thread's error context is independent
    asciichat_error_t err = do_work();
    if (err != ASCIICHAT_OK) {
        asciichat_error_context_t ctx;
        if (HAS_ERRNO(&ctx)) {
            log_error("Worker failed: %s", ctx.context_message);
        }
    }
    return NULL;
}

See also

asciichat_errno.h

logging.h

Macro Definition Documentation

CLEAR_ERRNO

#define CLEAR_ERRNO

(

)

asciichat_clear_errno()

#include <asciichat_errno.h>

Clear the current error state.

Definition at line 375 of file asciichat_errno.h.

GET_ERRNO

#define GET_ERRNO

(

)

asciichat_get_errno()

#include <asciichat_errno.h>

Get current error code (0 if no error)

Definition at line 380 of file asciichat_errno.h.

HAS_ERRNO

#define HAS_ERRNO

(

var

)

asciichat_has_errno(var)

#include <asciichat_errno.h>

Check if an error occurred and get full context.

Parameters

var	Variable to store error context

Usage in src/ code: asciichat_error_context_t err_ctx; if (HAS_ERRNO(&err_ctx)) { FATAL(err_ctx.code, "Library error occurred"); }

Definition at line 370 of file asciichat_errno.h.

SET_ERRNO

#define SET_ERRNO	(		code,
			context_msg,
			...
	)

#include <asciichat_errno.h>

Value:

  (asciichat_set_errno_with_message(code, __FILE__, __LINE__, __func__, context_msg, ##__VA_ARGS__),                   \
   log_error("SET_ERRNO: " context_msg " (code: %d, meaning: %s)", ##__VA_ARGS__, code, asciichat_error_string(code)), \
   (code))

Set error code with custom context message and log it, returning the error code.

Parameters

code	Error code to set
context_msg	Custom message explaining the error

Usage in lib/ code: if (bind(sockfd, ...) < 0) { return SET_ERRNO(ERROR_NETWORK_BIND, "Cannot bind to port %d", port); }

Definition at line 316 of file asciichat_errno.h.

                       : " context_msg " (code: %d, meaning: %s)", ##__VA_ARGS__, code, asciichat_error_string(code)), \
   (code))

SET_ERRNO_SYS

#define SET_ERRNO_SYS	(		code,
			context_msg,
			...
	)

#include <asciichat_errno.h>

Value:

  (asciichat_set_errno_with_system_error_and_message(code, __FILE__, __LINE__, __func__, platform_get_last_error(),    \
                                                     context_msg, ##__VA_ARGS__),                                      \
   log_error("SETERRNO_SYS: " context_msg " (code: %d - %s, system error: %d - %s)", ##__VA_ARGS__, code,              \
             asciichat_error_string(code), platform_get_last_error(), platform_strerror(platform_get_last_error())),   \
   (code))

Set error code with custom message and system error context, returning the error code.

Parameters

code	Error code to set
context_msg	Custom message explaining the error

Usage in lib/ code: if (open(file, O_RDONLY) < 0) { return SET_ERRNO_SYS(ERROR_CONFIG, "Failed to open config file: %s", path); }

Definition at line 340 of file asciichat_errno.h.

                          : " context_msg " (code: %d - %s, system error: %d - %s)", ##__VA_ARGS__, code,              \
             asciichat_error_string(code), platform_get_last_error(), platform_strerror(platform_get_last_error())),   \
   (code))

Function Documentation

asciichat_clear_errno()

void asciichat_clear_errno

(

void

)

#include <asciichat_errno.h>

Clear the current error state.

Clears the thread-local error state, resetting error code to ASCIICHAT_OK and freeing any associated context message. This is the low-level function used by CLEAR_ERRNO() macro.

Note

Error context structure is reset to default state.

Any context message is freed automatically.

Thread-safe: Uses thread-local storage.

Warning

Use CLEAR_ERRNO() macro instead of calling this directly.

Definition at line 233 of file asciichat_errno.c.

                                 {
  if (asciichat_errno_context.context_message) {
    SAFE_FREE(asciichat_errno_context.context_message);
    asciichat_errno_context.context_message = NULL;
  }
 
  backtrace_t_free(&asciichat_errno_context.backtrace);
 
  memset(&asciichat_errno_context, 0, sizeof(asciichat_errno_context));
  asciichat_errno_context.code = ASCIICHAT_OK;
  asciichat_errno_context.system_errno = 0;
  asciichat_errno_context.has_system_error = false;
  asciichat_errno_context.has_wsa_error = false;
  asciichat_errno_context.wsa_error = 0;
 
  /* Clear platform-specific error state */
  platform_clear_error_state();
}

References asciichat_errno_context, ASCIICHAT_OK, asciichat_error_context_t::backtrace, backtrace_t_free(), asciichat_error_context_t::code, asciichat_error_context_t::context_message, asciichat_error_context_t::has_system_error, asciichat_error_context_t::has_wsa_error, platform_clear_error_state(), SAFE_FREE, asciichat_error_context_t::system_errno, and asciichat_error_context_t::wsa_error.

asciichat_clear_thread_error()

void asciichat_clear_thread_error

(

int

thread_id

)

#include <asciichat_errno.h>

Clear error code for a specific thread.

Parameters

thread_id

Thread ID to clear error for

Clears the error code for a specific thread, resetting it to ASCIICHAT_OK.

Note

Thread ID must be valid (positive integer).

Definition at line 486 of file asciichat_errno.c.

                                                 {
  for (int i = 0; i < MAX_THREAD_ERRORS; i++) {
    if (thread_errors[i].valid && thread_errors[i].thread_id == thread_id) {
      thread_errors[i].valid = false;
      break;
    }
  }
}

References MAX_THREAD_ERRORS, thread_id, and valid.

asciichat_errno_destroy()

void asciichat_errno_destroy

(

void

)

#include <asciichat_errno.h>

Cleanup error system resources.

Cleans up error system resources including statistics and thread error storage. Should be called at application shutdown after all error handling is complete.

Note

Safe to call multiple times (no-op after first call).

All error statistics and context messages are freed.

Definition at line 504 of file asciichat_errno.c.

                                   {
  backtrace_t_free(&asciichat_errno_context.backtrace);
 
  if (asciichat_errno_context.context_message != NULL) {
    SAFE_FREE(asciichat_errno_context.context_message);
  }
 
  // Reset the context to a clean state
  memset(&asciichat_errno_context, 0, sizeof(asciichat_errno_context));
  asciichat_errno_context.code = ASCIICHAT_OK;
 
  // Suppress any further error context allocation to prevent cleanup-phase leaks
  // This prevents other atexit() functions from allocating new contexts after we've cleaned up
  g_suppress_error_context = true;
}

References asciichat_errno_context, ASCIICHAT_OK, asciichat_error_context_t::backtrace, backtrace_t_free(), asciichat_error_context_t::code, asciichat_error_context_t::context_message, and SAFE_FREE.

Referenced by asciichat_shared_destroy(), client_audio_render_thread(), client_receive_thread(), client_send_thread_func(), client_video_render_thread(), and stats_logger_thread().

asciichat_errno_suppress()

void asciichat_errno_suppress

(

bool

suppress

)

#include <asciichat_errno.h>

Suppress error logging and reporting.

Parameters

suppress

If true, suppress error logging; if false, enable logging

Controls whether errors are automatically logged when set. When suppressed, errors are still set in thread-local storage but logging is disabled. Useful for testing or when error logging would be too verbose.

Note

Suppression only affects automatic logging, not manual error checking.

Errors can still be checked using HAS_ERRNO() and GET_ERRNO().

Definition at line 500 of file asciichat_errno.c.

                                             {
  g_suppress_error_context = suppress;
}

asciichat_error_stats_get()

asciichat_error_stats_t asciichat_error_stats_get

(

void

)

#include <asciichat_errno.h>

Get current error statistics.

Returns

Current error statistics structure (copy)

Retrieves a copy of the current error statistics. Returns all statistics including per-error-code counts, total errors, and last error information.

Note

Returns a copy of statistics (caller can modify without affecting internal state).

Thread-safe: Can be called from any thread.

Definition at line 440 of file asciichat_errno.c.

                                                        {
  if (!lifecycle_is_initialized(&g_error_stats.lifecycle)) {
    lifecycle_init(&g_error_stats.lifecycle, "error_stats");
  }
 
  mutex_lock(&g_error_stats.mutex);
  asciichat_error_stats_t result = g_error_stats.stats;
  mutex_unlock(&g_error_stats.mutex);
 
  return result;
}

References lifecycle_init(), lifecycle_is_initialized(), mutex_lock, and mutex_unlock.

asciichat_error_stats_init()

void asciichat_error_stats_init

(

void

)

#include <asciichat_errno.h>

Initialize error statistics system.

Initializes the error statistics tracking system. Must be called before recording any error statistics. Statistics are initialized to zero.

Note

Idempotent: Safe to call multiple times (no-op after first call).

Thread-safe: Can be called from any thread.

Definition at line 365 of file asciichat_errno.c.

                                      {
  if (lifecycle_init(&g_error_stats.lifecycle, "error_stats")) {
    memset(&g_error_stats.stats, 0, sizeof(g_error_stats.stats));
  }
}

References lifecycle_init().

asciichat_error_stats_print()

void asciichat_error_stats_print

(

void

)

#include <asciichat_errno.h>

Print error statistics to stderr.

Prints comprehensive error statistics including per-error-code counts, total errors, and last error information. Useful for periodic monitoring and debugging.

Note

Statistics are formatted and printed at INFO level.

Requires statistics system to be initialized.

Definition at line 391 of file asciichat_errno.c.

                                       {
  if (!lifecycle_is_initialized(&g_error_stats.lifecycle)) {
    log_plain("No errors recorded.\n");
    return;
  }
 
  mutex_lock(&g_error_stats.mutex);
 
  if (g_error_stats.stats.total_errors == 0) {
    mutex_unlock(&g_error_stats.mutex);
    log_plain("No errors recorded.\n");
    return;
  }
 
  // Copy stats to local variable to minimize lock hold time
  asciichat_error_stats_t local_stats = g_error_stats.stats;
  mutex_unlock(&g_error_stats.mutex);
 
  log_plain("\n=== ascii-chat Error Statistics ===\n");
  log_plain("Total errors: %llu\n", (unsigned long long)local_stats.total_errors);
 
  if (local_stats.last_error_time > 0) {
    time_t sec = (time_t)(local_stats.last_error_time / NS_PER_MS_INT);
    struct tm tm_info;
    if (platform_localtime(&sec, &tm_info) == ASCIICHAT_OK) {
      char time_str[64];
      strftime(time_str, sizeof(time_str), "%Y-%m-%d %H:%M:%S", &tm_info);
      log_plain("Last error: %s (code %d)\n", time_str, (int)local_stats.last_error_code);
    }
  }
 
  log_plain("\nError breakdown:\n");
  for (int i = 0; i < 256; i++) {
    if (local_stats.error_counts[i] > 0) {
      log_plain("  %3d (%s): %llu\n", i, asciichat_error_string((asciichat_error_t)i),
                (unsigned long long)local_stats.error_counts[i]);
    }
  }
  log_plain("\n");
}

References ASCIICHAT_OK, asciichat_error_stats_t::error_counts, asciichat_error_stats_t::last_error_code, asciichat_error_stats_t::last_error_time, lifecycle_is_initialized(), log_plain, mutex_lock, mutex_unlock, NS_PER_MS_INT, platform_localtime(), and asciichat_error_stats_t::total_errors.

Referenced by stats_logger_thread().

asciichat_error_stats_record()

void asciichat_error_stats_record

(

asciichat_error_t

code

)

#include <asciichat_errno.h>

Record an error in statistics.

Parameters

code	Error code to record (asciichat_error_t)

Records an error occurrence in the statistics system. Updates per-error-code count, total error count, and last error information.

Note

Thread-safe: Can be called from multiple threads simultaneously.

Statistics counters are updated atomically.

Definition at line 371 of file asciichat_errno.c.

                                                          {
  if (!lifecycle_is_initialized(&g_error_stats.lifecycle)) {
    if (lifecycle_init(&g_error_stats.lifecycle, "error_stats")) {
      mutex_init(&g_error_stats.mutex, "error_stats");
      memset(&g_error_stats.stats, 0, sizeof(g_error_stats.stats));
    }
  }
 
  mutex_lock(&g_error_stats.mutex);
 
  if (code >= 0 && code < 256) {
    g_error_stats.stats.error_counts[code]++;
  }
  g_error_stats.stats.total_errors++;
  g_error_stats.stats.last_error_time = time_ns_to_us(time_get_realtime_ns());
  g_error_stats.stats.last_error_code = code;
 
  mutex_unlock(&g_error_stats.mutex);
}

References lifecycle_init(), lifecycle_is_initialized(), mutex_init(), mutex_lock, mutex_unlock, and time_get_realtime_ns().

Referenced by asciichat_set_errno().

asciichat_error_stats_reset()

void asciichat_error_stats_reset

(

void

)

#include <asciichat_errno.h>

Reset all error statistics to zero.

Resets all error statistics counters to zero. Useful for resetting statistics between test runs or monitoring periods.

Note

Thread-safe: Can be called from any thread.

All counters are reset to zero (total_errors, error_counts, etc.).

Definition at line 432 of file asciichat_errno.c.

                                       {
  if (lifecycle_is_initialized(&g_error_stats.lifecycle)) {
    mutex_lock(&g_error_stats.mutex);
    memset(&g_error_stats.stats, 0, sizeof(g_error_stats.stats));
    mutex_unlock(&g_error_stats.mutex);
  }
}

References lifecycle_is_initialized(), mutex_lock, and mutex_unlock.

asciichat_fatal_with_context()

void asciichat_fatal_with_context	(	asciichat_error_t	code,
		const char *	file,
		int	line,
		const char *	function,
		const char *	format,
			...
	)

#include <asciichat_errno.h>

Exit with error code and context (used by FATAL macro)

Parameters

code	Error code (asciichat_error_t)
file	Source file name (can be NULL)
line	Line number (0 if not provided)
function	Function name (can be NULL)
format	Format string (printf-style)
...	Format arguments

Low-level function used by FATAL() macro. Sets error context and exits the program with the specified error code. In debug builds, prints stack trace before exiting.

Note

This function never returns (terminates program).

In debug builds, prints full error context and stack trace.

Thread-safe: Uses thread-local storage.

Warning

This function terminates the program. Use FATAL() macro instead of calling this directly.

Definition at line 261 of file asciichat_errno.c.

                                                           {
  (void)file;
  (void)line;
  (void)function;
 
  // Print library error context if available
  asciichat_error_context_t err_ctx;
  if (HAS_ERRNO(&err_ctx)) {
    log_labeled("\nasciichat_errno: libary code error context", LOG_COLOR_ERROR, "");
    asciichat_print_error_context(&err_ctx);
  } else {
    log_plain("WARNING: No error context found (asciichat_errno_context.code=%d)", asciichat_errno_context.code);
  }
 
  safe_fprintf(stderr, "\n");
  log_labeled("FATAL ERROR", LOG_COLOR_FATAL, "exit code %d (%s)", (int)code, asciichat_error_string(code));
#ifndef NDEBUG
  const char *relative_file = extract_project_relative_path(file);
  log_plain("  Location: %s:%d in %s()", relative_file, line, function);
#endif
 
  if (format) {
    va_list args;
    va_start(args, format);
    char *formatted_message = format_message(format, args);
    log_plain("  Error message: %s", formatted_message);
    SAFE_FREE(formatted_message);
    va_end(args);
  }
 
#ifndef NDEBUG
  // Always print platform backtrace in debug/dev builds
  backtrace_t bt = {0};
  backtrace_capture_and_symbolize(&bt);
  if (bt.count > 0) {
    backtrace_print("\nFATAL BACKTRACE", &bt, 0, 0, skip_backtrace_frame);
    backtrace_t_free(&bt);
  }
#endif
 
#ifdef EMSCRIPTEN_BUILD
  // In WASM builds, do not call exit() — it permanently kills the module runtime.
  // Instead, set the error and return so callers can handle it gracefully.
  SET_ERRNO(code, "FATAL (non-exit in WASM): code=%d", (int)code);
#else
  exit(code);
#endif
}

asciichat_get_errno()

asciichat_error_t asciichat_get_errno

(

void

)

#include <asciichat_errno.h>

Get current error code.

Returns

Current error code (ASCIICHAT_OK if no error)

Returns the current thread-local error code. Returns ASCIICHAT_OK if no error has occurred. This is the low-level function used by GET_ERRNO().

Note

Thread-safe: Uses thread-local storage.

For full error context, use HAS_ERRNO() instead.

Warning

Use GET_ERRNO() macro instead of calling this directly.

Definition at line 252 of file asciichat_errno.c.

                                            {
  return asciichat_errno_context.code;
}

References asciichat_errno_context, and asciichat_error_context_t::code.

asciichat_get_thread_error()

asciichat_error_t asciichat_get_thread_error

(

int

thread_id

)

#include <asciichat_errno.h>

Get error code for a specific thread.

Parameters

thread_id

Thread ID to query

Returns

Error code for thread, or ASCIICHAT_OK if no error

Retrieves the error code for a specific thread. Useful for checking errors from other threads or propagating errors across thread boundaries.

Note

Thread ID must be valid (positive integer).

Returns ASCIICHAT_OK if thread has no error or thread ID is invalid.

Definition at line 457 of file asciichat_errno.c.

                                                            {
  for (int i = 0; i < MAX_THREAD_ERRORS; i++) {
    if (thread_errors[i].valid && thread_errors[i].thread_id == thread_id) {
      return thread_errors[i].error_code;
    }
  }
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, MAX_THREAD_ERRORS, thread_id, and valid.

asciichat_has_errno()

bool asciichat_has_errno

(

asciichat_error_context_t *

context

)

#include <asciichat_errno.h>

Check if error occurred and get full context.

Parameters

context

Output structure for error context (must not be NULL)

Returns

true if error occurred, false if no error

Checks if an error has occurred and copies the full error context into the provided structure. This is the low-level function used by HAS_ERRNO().

Note

Returns false if no error has occurred (asciichat_errno == ASCIICHAT_OK).

If error occurred, context structure is filled with all error information.

Thread-safe: Uses thread-local storage.

Warning

Use HAS_ERRNO() macro instead of calling this directly.

Definition at line 221 of file asciichat_errno.c.

                                                             {
  if (asciichat_errno_context.code == ASCIICHAT_OK) {
    return false;
  }
 
  if (context) {
    *context = asciichat_errno_context;
  }
 
  return true;
}

References asciichat_errno_context, ASCIICHAT_OK, and asciichat_error_context_t::code.

asciichat_has_wsa_error()

bool asciichat_has_wsa_error

(

void

)

#include <asciichat_errno.h>

Check if current error has WSA error code.

Returns

true if error has WSA error code, false otherwise

Checks whether the current thread-local error context includes a Windows socket error (WSA error) code. Useful for platform-specific error handling.

Note

Only meaningful on Windows platforms.

Returns false if no error occurred or error doesn't have WSA code.

Thread-safe: Uses thread-local storage.

Definition at line 212 of file asciichat_errno.c.

                                   {
  return asciichat_errno_context.has_wsa_error;
}

References asciichat_errno_context, and asciichat_error_context_t::has_wsa_error.

asciichat_print_error_context()

void asciichat_print_error_context

(

const asciichat_error_context_t *

context

)

#include <asciichat_errno.h>

Print full error context to stderr.

Parameters

context

Error context to print (must not be NULL)

Prints comprehensive error information including error code, location, context message, system errors, and stack trace (if available) to stderr. Useful for debugging and error reporting.

Note

Stack trace is only printed in debug builds.

System errors (errno, WSA) are included if present.

Timestamp and location information are included.

Definition at line 316 of file asciichat_errno.c.

                                                                             {
  if (!context || context->code == ASCIICHAT_OK) {
    return;
  }
 
  if (context->file && context->line && context->function) {
    log_plain("  Location: %s:%d in %s()", extract_project_relative_path(context->file), context->line,
              context->function);
  } else {
    log_plain("  Location: unknown (set by system code)");
  }
 
  if (context->context_message) {
    safe_fprintf(stderr, "  %s %s\n", colored_string(LOG_COLOR_WARN, "Context:"), context->context_message);
    log_file("  Context: %s", context->context_message);
  }
 
  if (context->has_system_error) {
    log_plain("  System error: %s (code: %d, meaning: %s)", SAFE_STRERROR(context->system_errno), context->system_errno,
              SAFE_STRERROR(context->system_errno));
  }
 
  // Print timestamp
  if (context->timestamp > 0) {
    time_t sec = (time_t)(context->timestamp / NS_PER_MS_INT);
    long usec = (long)(context->timestamp % NS_PER_MS_INT);
    struct tm tm_info;
    if (platform_localtime(&sec, &tm_info) == ASCIICHAT_OK) {
      char time_str[64];
      (void)strftime(time_str, sizeof(time_str), "%Y-%m-%d %H:%M:%S", &tm_info);
      log_plain("  Timestamp: %s.%06ld", time_str, usec);
    }
  }
 
  // Print stack trace from library error
  if (context->backtrace.count > 0) {
    // Symbolize backtrace only when actually printing it (not at capture time)
    backtrace_symbolize(&context->backtrace);
    if (context->backtrace.symbols) {
      backtrace_print("\nBacktrace from library error", &context->backtrace, 0, 0, skip_backtrace_frame);
    }
  }
}

References ASCIICHAT_OK, asciichat_error_context_t::backtrace, backtrace_print(), backtrace_symbolize(), asciichat_error_context_t::code, colored_string(), asciichat_error_context_t::context_message, backtrace_t::count, extract_project_relative_path(), asciichat_error_context_t::file, asciichat_error_context_t::function, asciichat_error_context_t::has_system_error, asciichat_error_context_t::line, LOG_COLOR_WARN, log_file, log_plain, NS_PER_MS_INT, platform_localtime(), safe_fprintf(), SAFE_STRERROR, backtrace_t::symbols, asciichat_error_context_t::system_errno, and asciichat_error_context_t::timestamp.

Referenced by asciichat_fatal_with_context().

asciichat_set_errno()

void asciichat_set_errno	(	asciichat_error_t	code,
		const char *	file,
		int	line,
		const char *	function,
		const char *	context_message
	)

#include <asciichat_errno.h>

Set error code with basic context.

Parameters

code	Error code to set (asciichat_error_t)
file	Source file name (can be NULL)
line	Line number (0 if not provided)
function	Function name (can be NULL)
context_message	Custom context message (can be NULL, will be copied)

Sets the thread-local error code with basic context information. This is the low-level function used by SET_ERRNO() macros.

Note

In debug builds, automatically captures stack trace if enabled.

Context message is copied if provided (caller can free original).

Thread-safe: Uses thread-local storage (no synchronization needed).

Warning

Use SET_ERRNO() macros instead of calling this directly.

Definition at line 113 of file asciichat_errno.c.

                                                      {
  // Suppress error context allocation during cleanup to prevent leaks
  if (g_suppress_error_context) {
    return;
  }
 
  // Clear any existing context message
  if (asciichat_errno_context.context_message) {
    SAFE_FREE(asciichat_errno_context.context_message);
    asciichat_errno_context.context_message = NULL;
  }
 
  // Set the error context
  asciichat_errno_context.code = code;
  asciichat_errno_context.file = file;
  asciichat_errno_context.line = line;
  asciichat_errno_context.function = function;
  asciichat_errno_context.timestamp = time_ns_to_us(time_get_realtime_ns());
  asciichat_errno_context.has_system_error = false;
 
  // Set the simple error code variable
  asciichat_errno = code;
 
  // Copy context message if provided
  if (context_message == NULL) {
    log_error("context_message is NULL");
    const char *fallback = "No context message (this is invalid - set a context message)";
    size_t len = strlen(fallback) + 1;
    asciichat_errno_context.context_message = SAFE_MALLOC(len, char *);
    if (asciichat_errno_context.context_message) {
      SAFE_STRNCPY(asciichat_errno_context.context_message, fallback, len);
    } else {
      log_error("SAFE_MALLOC failed for fallback context_message");
    }
  } else {
    size_t len = strlen(context_message) + 1;
    asciichat_errno_context.context_message = SAFE_MALLOC(len, char *);
    if (asciichat_errno_context.context_message) {
      SAFE_STRNCPY(asciichat_errno_context.context_message, context_message, len);
    } else {
      log_error("SAFE_MALLOC failed for context_message");
    }
  }
 
  // Capture stack trace in debug builds
  backtrace_t_free(&asciichat_errno_context.backtrace);
  capture_backtrace(&asciichat_errno_context.backtrace);
 
  // Record in statistics
  asciichat_error_stats_record(code);
}

References asciichat_errno, asciichat_errno_context, asciichat_error_stats_record(), asciichat_error_context_t::backtrace, backtrace_t_free(), asciichat_error_context_t::code, asciichat_error_context_t::context_message, asciichat_error_context_t::file, asciichat_error_context_t::function, asciichat_error_context_t::has_system_error, asciichat_error_context_t::line, log_error, SAFE_FREE, SAFE_MALLOC, SAFE_STRNCPY, time_get_realtime_ns(), and asciichat_error_context_t::timestamp.

Referenced by asciichat_set_errno_with_message(), asciichat_set_errno_with_system_error(), asciichat_set_errno_with_system_error_and_message(), and asciichat_set_errno_with_wsa_error().

asciichat_set_errno_with_message()

void asciichat_set_errno_with_message	(	asciichat_error_t	code,
		const char *	file,
		int	line,
		const char *	function,
		const char *	format,
			...
	)

#include <asciichat_errno.h>

Set error code with formatted message.

Parameters

code	Error code to set (asciichat_error_t)
file	Source file name (can be NULL)
line	Line number (0 if not provided)
function	Function name (can be NULL)
format	Format string (printf-style)
...	Format arguments

Sets the thread-local error code with a formatted context message. This is the low-level function used by SET_ERRNO() macros.

Note

Message is formatted using vsnprintf and stored in error context.

In debug builds, automatically captures stack trace if enabled.

Thread-safe: Uses thread-local storage.

Warning

Use SET_ERRNO() macros instead of calling this directly.

Definition at line 166 of file asciichat_errno.c.

                                                               {
  va_list args;
  va_start(args, format);
 
  char *context_message = format_message(format, args);
  asciichat_set_errno(code, file, line, function, context_message);
 
  if (context_message) {
    SAFE_FREE(context_message);
  }
 
  va_end(args);
}

References args, asciichat_set_errno(), format_message(), and SAFE_FREE.

asciichat_set_errno_with_system_error()

void asciichat_set_errno_with_system_error	(	asciichat_error_t	code,
		const char *	file,
		int	line,
		const char *	function,
		int	sys_errno
	)

#include <asciichat_errno.h>

Set error code with system error (errno)

Parameters

code	Error code to set (asciichat_error_t)
file	Source file name (can be NULL)
line	Line number (0 if not provided)
function	Function name (can be NULL)
sys_errno	System errno value

Sets the thread-local error code with system error context. Captures the system errno value for detailed error reporting.

Note

System errno is stored in error context for later retrieval.

In debug builds, automatically captures stack trace if enabled.

Thread-safe: Uses thread-local storage.

Warning

Use SET_ERRNO_SYS() macro instead of calling this directly.

Definition at line 181 of file asciichat_errno.c.

                                                          {
  asciichat_set_errno(code, file, line, function, NULL);
  asciichat_errno_context.system_errno = sys_errno;
  asciichat_errno_context.has_system_error = true;
}

References asciichat_errno_context, asciichat_set_errno(), asciichat_error_context_t::has_system_error, and asciichat_error_context_t::system_errno.

asciichat_set_errno_with_system_error_and_message()

void asciichat_set_errno_with_system_error_and_message	(	asciichat_error_t	code,
		const char *	file,
		int	line,
		const char *	function,
		int	sys_errno,
		const char *	format,
			...
	)

#include <asciichat_errno.h>

Set error code with system error and formatted message.

Parameters

code	Error code to set (asciichat_error_t)
file	Source file name (can be NULL)
line	Line number (0 if not provided)
function	Function name (can be NULL)
sys_errno	System errno value
format	Format string (printf-style)
...	Format arguments

Sets the thread-local error code with both system error context and a formatted message. This is the low-level function used by SET_ERRNO_SYS().

Note

Combines system error capture with formatted message.

In debug builds, automatically captures stack trace if enabled.

Thread-safe: Uses thread-local storage.

Warning

Use SET_ERRNO_SYS() macro instead of calling this directly.

Definition at line 188 of file asciichat_errno.c.

                                                                                                                     {
  va_list args;
  va_start(args, format);
 
  char *context_message = format_message(format, args);
  asciichat_set_errno(code, file, line, function, context_message);
  asciichat_errno_context.system_errno = sys_errno;
  asciichat_errno_context.has_system_error = true;
 
  if (context_message) {
    SAFE_FREE(context_message);
  }
 
  va_end(args);
}

References args, asciichat_errno_context, asciichat_set_errno(), format_message(), asciichat_error_context_t::has_system_error, SAFE_FREE, and asciichat_error_context_t::system_errno.

asciichat_set_errno_with_wsa_error()

void asciichat_set_errno_with_wsa_error	(	asciichat_error_t	code,
		const char *	file,
		int	line,
		const char *	function,
		int	wsa_error
	)

#include <asciichat_errno.h>

Set error code with Windows socket error (WSA error)

Parameters

code	Error code to set (asciichat_error_t)
file	Source file name (can be NULL)
line	Line number (0 if not provided)
function	Function name (can be NULL)
wsa_error	Windows socket error code

Sets the thread-local error code with Windows-specific socket error context. Used for Windows socket operations that fail with WSA error codes.

Note

WSA error is stored in error context for later retrieval.

This function is only useful on Windows platforms.

Thread-safe: Uses thread-local storage.

Definition at line 205 of file asciichat_errno.c.

                                                       {
  asciichat_set_errno(code, file, line, function, NULL);
  asciichat_errno_context.wsa_error = wsa_error;
  asciichat_errno_context.has_wsa_error = true;
}

References asciichat_errno_context, asciichat_set_errno(), asciichat_error_context_t::has_wsa_error, and asciichat_error_context_t::wsa_error.

asciichat_set_thread_error()

void asciichat_set_thread_error	(	int	thread_id,
		asciichat_error_t	code
	)

#include <asciichat_errno.h>

Set error code for a specific thread.

Parameters

thread_id	Thread ID to set error for
code	Error code to set (asciichat_error_t)

Sets the error code for a specific thread. Useful for propagating errors from one thread to another or storing thread-specific error states.

Note

Thread ID must be valid (positive integer).

This is separate from thread-local error state (asciichat_errno).

Definition at line 466 of file asciichat_errno.c.

                                                                       {
  // Find existing entry or empty slot
  int slot = -1;
  for (int i = 0; i < MAX_THREAD_ERRORS; i++) {
    if (thread_errors[i].valid && thread_errors[i].thread_id == thread_id) {
      slot = i;
      break;
    }
    if (!thread_errors[i].valid && slot == -1) {
      slot = i;
    }
  }
 
  if (slot >= 0) {
    thread_errors[slot].thread_id = thread_id;
    thread_errors[slot].error_code = code;
    thread_errors[slot].valid = true;
  }
}

References MAX_THREAD_ERRORS, thread_id, and valid.

Variable Documentation

asciichat_errno

__thread asciichat_error_t asciichat_errno

extern

#include <asciichat_errno.h>

Thread-local current error code.

Current error code for the calling thread. Set to ASCIICHAT_OK when no error. Updated automatically when errors are set via SET_ERRNO() macros.

Note

Use GET_ERRNO() macro to read the current error code.

Use CLEAR_ERRNO() macro to clear the error state.

Definition at line 43 of file asciichat_errno.c.

Referenced by accept_with_timeout(), asciichat_set_errno(), and recv_with_timeout().

asciichat_errno_context

__thread asciichat_error_context_t asciichat_errno_context

extern

#include <asciichat_errno.h>

Thread-local error context storage.

Each thread has its own independent error context. This ensures thread-safe error handling without synchronization overhead.

Note

Use HAS_ERRNO() macro to check for errors and get context.

Context is automatically updated when errors are set via SET_ERRNO().

Definition at line 33 of file asciichat_errno.c.

                                                             {.code = ASCIICHAT_OK,
                                                              .file = NULL,
                                                              .line = 0,
                                                              .function = NULL,
                                                              .context_message = NULL,
                                                              .timestamp = 0,
                                                              .system_errno = 0,
                                                              .backtrace = {.count = 0, .symbols = NULL},
                                                              .has_system_error = false};

Referenced by accept_with_timeout(), asciichat_clear_errno(), asciichat_errno_destroy(), asciichat_fatal_with_context(), asciichat_get_errno(), asciichat_has_errno(), asciichat_has_wsa_error(), asciichat_set_errno(), asciichat_set_errno_with_system_error(), asciichat_set_errno_with_system_error_and_message(), asciichat_set_errno_with_wsa_error(), and recv_with_timeout().