liburlx-ffi — C ABI compatibility layer for liburlx.

This crate provides a libcurl-compatible C API, allowing liburlx to serve as a drop-in replacement for libcurl at the binary level.

All unsafe code in the urlx project is confined to this crate.

Safety Invariants

The following safety contracts apply throughout this crate:

• Handle pointers (*mut c_void for easy/multi/share/url/mime handles): All callers must provide valid, non-null pointers obtained from the corresponding _init function. Every exported function null-checks its handle argument before dereferencing. Handles are Box-allocated and cast to *mut c_void; Box::from_raw reclaims ownership in _cleanup.

• C strings (*const c_char): Callers must provide valid, null-terminated strings. The helper read_cstr() combines null-check + CStr::from_ptr + UTF-8 validation. Direct CStr::from_ptr calls appear where read_cstr is insufficient (e.g., when the pointer type differs or when non-UTF-8 data is acceptable).

• Output pointers in curl_easy_getinfo: Callers must provide a valid pointer to the expected output type (*mut c_long, *mut f64, *mut *const c_char, *mut i64). Each match arm casts out to the documented type and writes through it. The function null-checks out before the match.

• Callback function pointers: std::mem::transmute converts *const c_void to the appropriate callback signature. Callers must ensure the pointer is actually a function with the documented C signature. Callbacks are invoked during curl_easy_perform with the corresponding *data pointer passed as the user-data argument.

• curl_slist traversal: Linked-list nodes are caller-allocated. The list is walked via (*node).next until null. Each node.data is a caller-owned C string. curl_slist_free_all reclaims all nodes.

• Panic safety: All exported #[no_mangle] functions wrap their body in std::panic::catch_unwind to prevent Rust panics from unwinding across the FFI boundary.