Crate liburlx_ffi 

liburlx-ffi

C ABI compatibility layer for liburlx — a drop-in replacement for libcurl.

This crate provides libcurl-compatible C functions (curl_easy_init, curl_easy_setopt, curl_easy_perform, etc.) backed by the pure-Rust liburlx engine. Existing C/C++ programs can link against liburlx_ffi instead of libcurl without code changes.

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

Usage

#include "urlx.h"

CURL *curl = curl_easy_init();
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
CURLcode res = curl_easy_perform(curl);
curl_easy_cleanup(curl);

Coverage

• 156 CURLOPT options
• 49 CURLINFO queries
• 41 CURLcode error codes
• 57 exported C functions (all wrapped in catch_unwind)

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.

Structs

CURLMsg

CURLMsg — completion message from curl_multi_info_read.

CurlVersionInfo

Version info struct returned by curl_version_info.

curl_blob

curl_blob — in-memory binary data for TLS certificate/key options.

curl_slist

Linked list node for string data (e.g., HTTP headers).

curl_waitfd

curl_waitfd — extra file descriptor for curl_multi_wait/curl_multi_poll.

Enums

CURLINFO

CURLINFO — info codes for curl_easy_getinfo.

CURLMSG

CURLMSG — message types from curl_multi_info_read.

CURLMcode

CURLMcode — result codes for multi handle operations.

CURLMoption

CURLMoption — option codes for curl_multi_setopt.

CURLSHcode

CURLSHcode — result codes for share handle operations.

CURLSHoption

CURLSHoption — option codes for curl_share_setopt.

CURLUPart

CURLUPart — part identifiers for URL manipulation.

CURLUcode

CURLUcode — result codes for URL API operations.

CURLcode

CURLcode — result codes for easy handle operations.

CURLoption

CURLOPT — option codes for curl_easy_setopt.

Constants

CURLPAUSE_ALL

CURLPAUSE_ALL — pause both directions.

CURLPAUSE_CONT

CURLPAUSE_CONT — unpause both directions.

CURLPAUSE_RECV

Pause direction constants. CURLPAUSE_RECV — pause receiving.

CURLPAUSE_SEND

CURLPAUSE_SEND — pause sending.

CURL_GLOBAL_ALL

CURL_GLOBAL_ALL — initialize everything.

CURL_GLOBAL_DEFAULT

CURL_GLOBAL_DEFAULT — same as ALL.

CURL_GLOBAL_SSL

Bitmask constants for curl_global_init. CURL_GLOBAL_SSL — initialize SSL.

CURL_GLOBAL_WIN32

CURL_GLOBAL_WIN32 — initialize Win32 sockets.

CURL_VERSION_ASYNCHDNS

Feature bit: async DNS support.

CURL_VERSION_HTTP2

Feature bit: HTTP/2 support.

CURL_VERSION_PSL

Feature bit: PSL support.

CURL_VERSION_SSL

Feature bit: SSL support.

Functions

curl_easy_cleanup^⚠

curl_easy_cleanup — free an easy handle.

curl_easy_duphandle^⚠

curl_easy_duphandle — clone an easy handle.

curl_easy_escape^⚠

curl_easy_escape — URL-encode a string using an easy handle.

curl_easy_getinfo^⚠

curl_easy_getinfo — get info about the last transfer.

curl_easy_init

curl_easy_init — create a new easy handle.

curl_easy_pause

curl_easy_pause — pause/unpause a transfer (stub).

curl_easy_perform^⚠

curl_easy_perform — perform the transfer.

curl_easy_reset^⚠

curl_easy_reset — reset an easy handle to initial state.

curl_easy_setopt^⚠

curl_easy_setopt — set options on an easy handle.

curl_easy_strerror

curl_easy_strerror — return a human-readable error message.

curl_easy_unescape^⚠

curl_easy_unescape — URL-decode a string using an easy handle.

curl_easy_upkeep

curl_easy_upkeep — perform connection upkeep (no-op).

curl_escape^⚠

curl_escape — URL-encode a string.

curl_formadd^⚠

curl_formadd — deprecated multipart form API.

curl_formfree^⚠

curl_formfree — free a form created by curl_formadd.

curl_free^⚠

curl_free — free memory allocated by curl functions.

curl_getdate^⚠

curl_getdate — parse a date string to a Unix timestamp.

curl_global_cleanup

curl_global_cleanup — global cleanup (no-op in urlx).

curl_global_init

curl_global_init — global initialization (no-op in urlx).

curl_mime_addpart^⚠

curl_mime_addpart — add a new part to a MIME handle.

curl_mime_data^⚠

curl_mime_data — set data for a MIME part.

curl_mime_filename^⚠

curl_mime_filename — set the filename for a MIME part.

curl_mime_free^⚠

curl_mime_free — free a MIME handle and all its parts.

curl_mime_init^⚠

curl_mime_init — create a new MIME handle.

curl_mime_name^⚠

curl_mime_name — set the name of a MIME part.

curl_mime_type^⚠

curl_mime_type — set the MIME type for a MIME part.

curl_multi_add_handle^⚠

curl_multi_add_handle — add an easy handle to a multi handle.

curl_multi_assign

curl_multi_assign — assign custom pointer to socket (no-op stub).

curl_multi_cleanup^⚠

curl_multi_cleanup — free a multi handle.

curl_multi_fdset^⚠

curl_multi_fdset — extract file descriptors from the multi handle.

curl_multi_info_read^⚠

curl_multi_info_read — read a completion message from the multi handle.

curl_multi_init

curl_multi_init — create a new multi handle.

curl_multi_perform^⚠

curl_multi_perform — perform all queued transfers.

curl_multi_poll^⚠

curl_multi_poll — poll for activity on any of the multi handle’s transfers.

curl_multi_remove_handle^⚠

curl_multi_remove_handle — remove an easy handle from a multi handle.

curl_multi_setopt^⚠

curl_multi_setopt — set options on a multi handle.

curl_multi_socket_action^⚠

curl_multi_socket_action — socket action interface for event-driven programs.

curl_multi_strerror

curl_multi_strerror — return a human-readable multi error message.

curl_multi_timeout^⚠

curl_multi_timeout — return the timeout value for the multi handle.

curl_multi_wait^⚠

curl_multi_wait — wait for activity on any of the multi handle’s transfers.

curl_multi_wakeup^⚠

curl_multi_wakeup — wake up a sleeping curl_multi_poll.

curl_share_cleanup^⚠

curl_share_cleanup — free a share handle.

curl_share_init

curl_share_init — create a new share handle.

curl_share_setopt^⚠

curl_share_setopt — set options on a share handle.

curl_share_strerror

curl_share_strerror — return a human-readable share error message.

curl_slist_append^⚠

curl_slist_append — append a string to a linked list.

curl_slist_free_all^⚠

curl_slist_free_all — free an entire linked list.

curl_unescape^⚠

curl_unescape — URL-decode a string.

curl_url

curl_url — create a new URL handle.

curl_url_cleanup^⚠

curl_url_cleanup — free a URL handle.

curl_url_dup^⚠

curl_url_dup — duplicate a URL handle.

curl_url_get^⚠

curl_url_get — get a URL component.

curl_url_set^⚠

curl_url_set — set a URL component.

curl_version

curl_version — returns the version string (libcurl compatibility).

curl_version_info

curl_version_info — return version info struct.

urlx_version

urlx_version — returns the version string.