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
	⚠️‼️ Error and/or exit() when things go bad.

Data Structures
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.
#define	SET_ERRNO_SYS(code, context_msg, ...)
	Set error code with custom message and system error context.
#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_cleanup (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

This header provides a comprehensive thread-local error number system that captures full error context including location, stack traces, and system errors. The system integrates with ascii-chat's error handling to provide detailed debugging information.

CORE FEATURES:

• Thread-local error storage (each thread has independent error state)
• Full error context capture (file, line, function, stack trace)
• System error integration (errno, WSA errors)
• Automatic error logging with context
• Debug build stack trace capture
• Error statistics tracking

ERROR CONTEXT:

The system captures:

• Error code (asciichat_error_t)
• File, line, function where error occurred
• Stack trace at error site (debug builds)
• Optional custom context message
• Timestamp of error
• System error context (errno, WSA errors)

LIBRARY MACROS:

Use SET_ERRNO and SET_ERRNO_SYS in lib/ code:

• Automatically captures file/line/function (debug builds)
• Logs error with context message
• Sets thread-local error state
• Integrates with system error codes

APPLICATION MACROS:

Use HAS_ERRNO, GET_ERRNO, CLEAR_ERRNO in src/ code:

• Check for library errors
• Retrieve error context
• Clear error state
• Integrate with FATAL() macro

THREAD SAFETY:

• Thread-local storage ensures thread safety
• Each thread has independent error state
• No synchronization overhead
• Thread-specific error statistics

DEBUG FEATURES:

In debug builds, the system:

• Captures stack traces at error sites
• Includes file/line/function in all errors
• Provides ASSERT_NO_ERRNO() for validation
• Enables error context printing

Note

Use SET_ERRNO() in library code to set errors.

Use HAS_ERRNO() in application code to check errors.

Stack traces are only captured in debug builds.

Thread-local storage ensures thread safety automatically.

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 259 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 264 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 254 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.

Parameters

code	Error code to set
context_msg	Custom message explaining the error

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

Definition at line 190 of file asciichat_errno.h.

   {                                                                                                                   \
    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_ERRNO_SYS

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

#include <asciichat_errno.h>

Value:

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

Set error code with custom message and system error context.

Parameters

code	Error code to set
context_msg	Custom message explaining the error

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

Definition at line 221 of file asciichat_errno.h.

   {                                                                                                                   \
    int captured_errno = platform_get_last_error();                                                                    \
    asciichat_set_errno_with_system_error_and_message(code, __FILE__, __LINE__, __func__, captured_errno, context_msg, \
                                                      ##__VA_ARGS__);                                                  \
    log_error("SETERRNO_SYS: " context_msg " (code: %d - %s, system error: %d - %s)", ##__VA_ARGS__, code,             \
              asciichat_error_string(code), captured_errno, platform_strerror(captured_errno));                        \
    (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 241 of file asciichat_errno.c.

                                 {
  if (asciichat_errno_context.context_message) {
    SAFE_FREE(asciichat_errno_context.context_message);
    asciichat_errno_context.context_message = NULL;
  }
 
  if (asciichat_errno_context.backtrace_symbols != NULL) {
    platform_backtrace_symbols_free(asciichat_errno_context.backtrace_symbols);
    asciichat_errno_context.backtrace_symbols = NULL;
  }
 
  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;
 
#ifdef _WIN32
  WSASetLastError(0);
  asciichat_errno_context.wsa_error = 0;
#endif
 
  errno = 0;
}

References asciichat_errno_context, ASCIICHAT_OK, asciichat_error_context_t::backtrace_symbols, asciichat_error_context_t::code, asciichat_error_context_t::context_message, errno, asciichat_error_context_t::has_system_error, asciichat_error_context_t::has_wsa_error, platform_backtrace_symbols_free(), 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 468 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_cleanup()

void asciichat_errno_cleanup

(

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 486 of file asciichat_errno.c.

                                   {
  if (asciichat_errno_context.backtrace_symbols != NULL) {
    platform_backtrace_symbols_free(asciichat_errno_context.backtrace_symbols);
    asciichat_errno_context.backtrace_symbols = NULL;
  }
 
  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_symbols, asciichat_error_context_t::code, asciichat_error_context_t::context_message, platform_backtrace_symbols_free(), and SAFE_FREE.

Referenced by __attribute__(), asciichat_shared_init(), client_audio_render_thread(), client_receive_thread(), client_send_thread_func(), client_video_render_thread(), server_main(), 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 482 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 427 of file asciichat_errno.c.

                                                        {
  if (!stats_initialized) {
    asciichat_error_stats_init();
  }
  return error_stats;
}

References asciichat_error_stats_init().

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 374 of file asciichat_errno.c.

                                      {
  if (!stats_initialized) {
    memset(&error_stats, 0, sizeof(error_stats));
    stats_initialized = true;
  }
}

Referenced by asciichat_error_stats_get(), and asciichat_error_stats_record().

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 394 of file asciichat_errno.c.

                                       {
  if (!stats_initialized || error_stats.total_errors == 0) {
    log_plain("No errors recorded.\n");
    return;
  }
 
  log_plain("\n=== ascii-chat Error Statistics ===\n");
  log_plain("Total errors: %llu\n", (unsigned long long)error_stats.total_errors);
 
  if (error_stats.last_error_time > 0) {
    time_t sec = (time_t)(error_stats.last_error_time / 1000000);
    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)error_stats.last_error_code);
    }
  }
 
  log_plain("\nError breakdown:\n");
  for (int i = 0; i < 256; i++) {
    if (error_stats.error_counts[i] > 0) {
      log_plain("  %3d (%s): %llu\n", i, asciichat_error_string((asciichat_error_t)i),
                (unsigned long long)error_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, log_plain, platform_localtime(), and asciichat_error_stats_t::total_errors.

Referenced by server_main(), and 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 381 of file asciichat_errno.c.

                                                          {
  if (!stats_initialized) {
    asciichat_error_stats_init();
  }
 
  if (code >= 0 && code < 256) {
    error_stats.error_counts[code]++;
  }
  error_stats.total_errors++;
  error_stats.last_error_time = get_timestamp_microseconds();
  error_stats.last_error_code = code;
}

References asciichat_error_stats_init(), asciichat_error_stats_t::error_counts, asciichat_error_stats_t::last_error_code, asciichat_error_stats_t::last_error_time, and asciichat_error_stats_t::total_errors.

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 423 of file asciichat_errno.c.

                                       {
  memset(&error_stats, 0, sizeof(error_stats));
}

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 275 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
  void *buffer[32];
  int size = platform_backtrace(buffer, 32);
  if (size > 0) {
    char **symbols = platform_backtrace_symbols(buffer, size);
    if (symbols) {
      platform_print_backtrace_symbols("\nFATAL BACKTRACE", symbols, size, 0, 0, skip_backtrace_frame);
      platform_backtrace_symbols_free(symbols);
    }
  }
#endif
 
  exit(code);
}

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 266 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 439 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 229 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 220 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 327 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  Context:%s %s\n", log_level_color(LOG_COLOR_WARN), log_level_color(LOG_COLOR_RESET),
                 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 / 1000000);
    long usec = (long)(context->timestamp % 1000000);
    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->stack_depth > 0 && context->backtrace_symbols) {
    platform_print_backtrace_symbols("\nBacktrace from library error", context->backtrace_symbols, context->stack_depth,
                                     0, 0, skip_backtrace_frame);
  }
}

References ASCIICHAT_OK, asciichat_error_context_t::backtrace_symbols, asciichat_error_context_t::code, asciichat_error_context_t::context_message, 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_RESET, LOG_COLOR_WARN, log_file, log_level_color(), log_plain, platform_localtime(), platform_print_backtrace_symbols(), safe_fprintf(), SAFE_STRERROR, asciichat_error_context_t::stack_depth, 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 117 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 = get_timestamp_microseconds();
  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
  if (asciichat_errno_context.backtrace_symbols != NULL) {
    platform_backtrace_symbols_free(asciichat_errno_context.backtrace_symbols);
    asciichat_errno_context.backtrace_symbols = NULL;
  }
  capture_backtrace(asciichat_errno_context.backtrace, &asciichat_errno_context.backtrace_symbols,
                    &asciichat_errno_context.stack_depth);
 
  // Record in statistics
  asciichat_error_stats_record(code);
}

References asciichat_errno, asciichat_errno_context, asciichat_error_stats_record(), asciichat_error_context_t::backtrace, asciichat_error_context_t::backtrace_symbols, 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, platform_backtrace_symbols_free(), SAFE_FREE, SAFE_MALLOC, SAFE_STRNCPY, asciichat_error_context_t::stack_depth, 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 174 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 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 189 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 196 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 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 213 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.

Referenced by accept_with_timeout().

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 448 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 39 of file asciichat_errno.c.

Referenced by accept_with_timeout(), and asciichat_set_errno().

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 27 of file asciichat_errno.c.

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

Referenced by accept_with_timeout(), asciichat_clear_errno(), asciichat_errno_cleanup(), 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(), and asciichat_set_errno_with_wsa_error().