Module errors 

Error subsystem (§21, §85 Phase 1).

Implements the libxml2 error reporting infrastructure:

• xmlError struct management
• Error domain/code registry
• Structured error callbacks (thread-local storage)
• Generic error callbacks (thread-local storage)
• Last-error tracking (thread-local xmlGetLastError, xmlResetLastError, xmlCopyError)
• Error message formatting
• xmlRaiseError() — the central error reporting function

UPSTREAM-PARITY

libxml2 has a two-tier error system:

1. Structured errors — xmlStructuredErrorFunc receives an xmlErrorPtr with all structured fields (domain, code, level, line, etc.)

2. Generic errors — xmlGenericErrorFunc receives a formatted string (printf-style). This is the older system, still widely used.

Both systems coexist. When both handlers are set, both are called. The last error is stored thread-locally for retrieval via xmlGetLastError.

Phase 1 status

Complete — all error functions are implemented. Variadic message formatting will be enhanced in Phase 2+.

Upstream contract

Mirrors upstream error.c (SRC-LIBXML2-2.15.0-ERROR-C, oracle tree oracle/historical/src/libxml2-2.15.0/error.c): xmlRaiseError / xmlVRaiseError routing, xmlFormatError, xmlGenericErrorDefaultFunc, xmlGetLastError / xmlCtxtGetLastError / xmlResetLastError, xmlCopyError and the legacy xmlParserError / xmlParserWarning SAX handlers.

Conceptual behavior

Two-tier error system: structured errors (xmlStructuredErrorFunc with the full xmlError) and generic errors (printf-style fragments). The 11.1-M/K rework routes each raise through ONE channel: a structured handler, else the custom SAX channel (channel(data, msg) once), else the legacy default streaming the xmlFormatError fragments (file/line, domain, level, message, source window, caret) as 6 variadic calls (R-000161).

Ownership & safety invariants

Ownership: the thread-local last error owns its file/str1-3 copies; raise_error_streamed copies transient CStrings (R-000163: dangling pointers were the bug). The exported xmlLastError mirror is synced under lock (R-000170). SAFETY: the variadic xmlGenericErrorDefaultFunc and xmlParserError legacy handlers are x86_64 SysV inline-asm va_list shims — stable Rust cannot define variadic extern fns.

Historical quirks & epochs

E-005: fatal parser errors are reported twice from 2.13.0 (attr-markup- entity); the xmlFormatError fragment stream and the 80-column source window cap are 2.15 semantics (xmlParserInputGetWindow, caret clamp). R-000163 pinned all XML_ERR_* 64-96 constants to upstream numbering (SPACE_REQUIRED 65, NAME_REQUIRED 68, GT_REQUIRED 73, TAG_NAME_MISMATCH 76, TAG_NOT_FINISHED 77 — not the synthetic renumbering).

Deliberate oddities

Deliberate oddities: warnings only bump nbWarnings while other levels update errNo / nbErrors / wellFormed per xmlCtxtVErr; the source window replicates the 80-char cap, continuation-byte skip, UTF-8 forward scan and the 2.15 caret clamp (col >= n maps to size-1).

Proving courts

ERROR and CALLBACK court families; ERROR-001 (48 deterministic malformed inputs x 4 passes, byte-identical), GLOBALS-THREADING, DATA-GLOBALS-001, and cargo test --lib (ASan-clean).

Tempting simplifications that would break parity

The tempting simplification is one generic call plus a direct stderr write — a counting handler would observe 1 call instead of the 6 xmlFormatError fragments the oracle emits (R-000161). Do not route errors to stderr when a handler is installed. Never renumber the XML_ERR_* constants (R-000163).

Structs

VaListTag

System V AMD64 __va_list_tag (24 bytes) — same layout as the writer’s shims and data_globals.rs.

Enums

GenericDelivery

How a raise delivers to the generic side of the error system (upstream xmlVRaiseError channel selection, error.c 2.15).

Constants

XML_PARSER_ERROR_SAX1

The variadic xmlParserError shim, transmuted to the fixed-arity SAX v1 callback type. The shim’s declared arity is a Rust-side fiction (stable Rust cannot express c_variadic); the ABI is a plain code pointer and the C variadic call contract is preserved (11.1-Z.2, R-000176).

XML_PARSER_VALIDITY_ERROR_SAX1

The variadic xmlParserValidityError shim as the validation callback type (xmlValidityErrorFunc-compatible fixed-arity pointer).

XML_PARSER_VALIDITY_WARNING_SAX1

The variadic xmlParserValidityWarning shim as the validation callback type.

XML_PARSER_WARNING_SAX1

The variadic xmlParserWarning shim as the SAX v1 callback type.

Functions

copy_error^⚠

Copy an error from one location to another.

format_error_message

Format an error message.

get_last_error

Get the last error for the current thread.

raise_error^⚠

Raise an error — the central error reporting function.

raise_error_streamed^⚠

Raise an error with upstream’s full routing (error.c 2.15 xmlVRaiseError): update the last error, then deliver to the structured handler or the selected generic channel — never both.

reset_error^⚠

Reset an error structure to its default state.

reset_last_error

Reset the last error for the current thread.

set_generic_error_func^⚠

Set the generic error handler.

set_structured_error_func^⚠

Set the structured error handler.

xmlParserError^⚠

Default SAX v1 error handler — upstream void xmlParserError(void *ctx, const char *msg, ...). Variadic x86_64 SysV shim (11.1-Z.2, R-000176: the previous fixed-arity body silently dropped the varargs; upstream error.c formats them via xmlVFormatLegacyError).

xmlParserErrorV^⚠

Variadic receiver for the xmlParserError shim: formats msg with the caller’s varargs and emits "error: " + formatted text through the generic channel (upstream error.c xmlVFormatLegacyError).

xmlParserValidityError^⚠

Default validity error handler — upstream void xmlParserValidityError(void *ctx, const char *msg, ...). Variadic shim as xmlParserError.

xmlParserValidityErrorV^⚠

Variadic receiver for the xmlParserValidityError shim.

xmlParserValidityWarning^⚠

Default validity warning handler — upstream void xmlParserValidityWarning(void *ctx, const char *msg, ...). Variadic shim as xmlParserError.

xmlParserValidityWarningV^⚠

Variadic receiver for the xmlParserValidityWarning shim.

xmlParserWarning^⚠

Default SAX v1 warning handler — upstream void xmlParserWarning(void *ctx, const char *msg, ...). Variadic shim as xmlParserError.

xmlParserWarningV^⚠

Variadic receiver for the xmlParserWarning shim.