error.c File Reference

Implements the thread-local error reporting system. More...

#include "common/infix_internals.h"
#include <infix/infix.h>
#include <stdarg.h>
#include <stdio.h>
#include <string.h>

Include dependency graph for error.c:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	INFIX_TLS
#define	_INFIX_SAFE_STRNCPY(dest, src, count)

Functions
static const char *	_get_error_message_for_code (infix_error_code_t code)
void	_infix_set_error (infix_error_category_t category, infix_error_code_t code, size_t position)
	Sets the thread-local error state with detailed information.
void	_infix_set_system_error (infix_error_category_t category, infix_error_code_t code, long system_code, const char *msg)
	Sets the thread-local error state for a system-level error.
void	_infix_clear_error (void)
	Clears the thread-local error state.
infix_error_details_t	infix_get_last_error (void)
	Retrieves detailed information about the last error that occurred on the current thread.

Variables
static INFIX_TLS infix_error_details_t	g_infix_last_error = {INFIX_CATEGORY_NONE, INFIX_CODE_SUCCESS, 0, 0, {0}}
	The thread-local variable that stores the details of the last error.
INFIX_TLS const char *	g_infix_last_signature_context = nullptr
	A thread-local pointer to the full signature string being parsed.

Detailed Description

Implements the thread-local error reporting system.

Copyright (c) 2025 Sanko Robinson

This source code is dual-licensed under the Artistic License 2.0 or the MIT License. You may choose to use this code under the terms of either license.

SPDX-License-Identifier: (Artistic-2.0 OR MIT)

The documentation blocks within this file are licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).

SPDX-License-Identifier: CC-BY-4.0

This module provides the infrastructure for robust and thread-safe error handling within the infix library.

The core principle is that all detailed error information is stored in thread-local storage (TLS). This means that an error occurring in one thread will never interfere with or be accidentally reported by an operation in another thread.

The workflow is as follows:

1. Every public API function calls _infix_clear_error() upon entry to reset the error state for the current thread.
2. If an internal function encounters an error, it calls _infix_set_error() or _infix_set_system_error() to record detailed diagnostic information, including an error code, category, and a descriptive message.
3. For parser errors, _infix_set_error() generates a rich, multi-line diagnostic message with a code snippet and a caret pointing to the error location, similar to a compiler error.
4. The user can call the public infix_get_last_error() function at any time to retrieve a copy of the last error that occurred on their thread.

Macro Definition Documentation

_INFIX_SAFE_STRNCPY

#define _INFIX_SAFE_STRNCPY	(		dest,
			src,
			count
	)

Value:

    do {                                      \
        strncpy(dest, src, (count));          \
        (dest)[(sizeof(dest)) - 1] = '\0';    \
    } while (0)

INFIX_TLS

#define INFIX_TLS

Function Documentation

_get_error_message_for_code()

static const char * _get_error_message_for_code ( infix_error_code_t  code )

static

_infix_clear_error()

void _infix_clear_error

(

void

)

Clears the thread-local error state.

Located in src/core/error.c. This is called at the beginning of every public API function to ensure that a prior error from an unrelated call is not accidentally returned.

_infix_set_error()

void _infix_set_error	(	infix_error_category_t	category,
		infix_error_code_t	code,
		size_t	position
	)

Sets the thread-local error state with detailed information.

Located in src/core/error.c, this function is the primary mechanism for reporting errors from within the library. It populates the thread-local g_infix_last_error struct. For parser errors, it generates a rich diagnostic message with a code snippet.

Parameters

category	The general category of the error.
code	The specific error code.
position	For parser errors, the byte offset into the signature string where the error occurred.

_infix_set_system_error()

void _infix_set_system_error	(	infix_error_category_t	category,
		infix_error_code_t	code,
		long	system_code,
		const char *	msg
	)

Sets the thread-local error state for a system-level error.

Located in src/core/error.c, this is used for errors originating from the operating system, such as dlopen or mmap failures.

Parameters

category	The general category of the error.
code	The infix error code that corresponds to the failure.
system_code	The OS-specific error code (e.g., from errno or GetLastError).
msg	An optional custom message from the OS (e.g., from dlerror).

Variable Documentation

g_infix_last_error

g_infix_last_error = {INFIX_CATEGORY_NONE, INFIX_CODE_SUCCESS, 0, 0, {0}}

static

The thread-local variable that stores the details of the last error.

Each thread gets its own independent instance of this variable. It is initialized to a "no error" state.

g_infix_last_signature_context

g_infix_last_signature_context = nullptr

A thread-local pointer to the full signature string being parsed.

This is set by the high-level API functions (infix_type_from_signature, etc.) before parsing begins. If a parser error occurs, _infix_set_error uses this context to generate a rich, contextual error message.