curlx

Active contributors: Daniel Stenberg, Viktor Szakats, Stefan Eissing

Purpose

curlx is curl's internal portability layer. It is not part of libcurl's public API — symbols use the Curl_ prefix and are explicitly hidden from the linker. Both libcurl (from lib/) and the curl command-line tool (from src/) statically link against it. This is the layer that lets curl's source assume "modern enough" POSIX/Windows behaviour without each .c file repeating the workarounds.

The directory has its own README at lib/curlx/README (not present in this checkout — the layer is described inline in source comments and in docs/INTERNALS.md).

Directory layout

lib/curlx/
├── base64.[ch]        # Base64 + base64url + base32 encode/decode
├── basename.[ch]      # Cross-platform basename()
├── dynbuf.[ch]        # Growable byte buffer (Curl_dyn_*)
├── fopen.[ch]         # Atomic-rename fopen for cookie/HSTS/alt-svc files
├── inet_ntop.[ch]     # Local inet_ntop() implementation
├── inet_pton.[ch]     # Local inet_pton() implementation
├── multibyte.[ch]     # UTF-8 / multibyte / wchar conversions
├── nonblock.[ch]      # set/clear non-blocking on a socket
├── snprintf.[ch]      # Strict snprintf wrapper
├── strcopy.[ch]       # Bounded string copy
├── strdup.[ch]        # strdup with NULL-safety
├── strerr.[ch]        # System error → string
├── strparse.[ch]      # Non-allocating tokenizer for ASCII parsing
├── timediff.[ch]      # Cross-platform monotonic-clock difference
├── timeval.[ch]       # struct timeval helpers + monotonic time
├── version_win32.[ch] # Windows version detection
├── wait.[ch]          # Sleep / poll wrappers
├── warnless.[ch]      # Implicit-conversion-safe casts (silences -Wsign-conversion)
└── winapi.[ch]        # Loadable Windows API helpers

Key abstractions

Component	Header	Used by
dynbuf	lib/curlx/dynbuf.h	Almost every lib/*.c file builds output via Curl_dyn_addn/Curl_dyn_addf. Replaces realloc(buf, n).
strparse	lib/curlx/strparse.h	Header parsing, URL parsing, cookie parsing, alt-svc parsing — non-allocating, length-bounded
timeval	lib/curlx/timeval.h	Curl_now() (monotonic) used everywhere for timeouts and progress measurement
wait	lib/curlx/wait.h	The Curl_wait_ms helper used by the multi loop's idle-spin
fopen	lib/curlx/fopen.h	Atomic-rename writes for ~/.curl-cookies, HSTS file, alt-svc file
multibyte	lib/curlx/multibyte.h	All Windows-side filename and command-line handling
nonblock	lib/curlx/nonblock.h	Single point of "make this socket non-blocking" across platforms

How it works

curlx is a regular static archive: the Makefile.am and CMakeLists.txt in lib/curlx/ compile the sources into libcurlx.a (or equivalent), which is then linked into both libcurl-* and src/curl-tool. The naming convention Curl_ keeps the private symbols out of the libcurl ABI; on systems with version scripts, the build also strips them from the export set.

Because curlx is internal, it is allowed to evolve more freely than libcurl proper — but in practice it changes slowly because it underpins everything.

Integration points

• Every lib/*.c source includes curlx/ headers via paths like #include "curlx/dynbuf.h". The include path is set up by lib/Makefile.inc and lib/CMakeLists.txt.
• The CLI tool also includes curlx headers for command-line and filename handling: see src/tool_main.c, src/tool_paramhlp.c.
• Tests under tests/unit/ exercise curlx directly — there are dedicated unit tests for dynbuf, strparse, base64, etc.

Entry points for modification

• A new portable helper that more than one lib/*.c needs → write it under lib/curlx/ and add it to lib/curlx/Makefile.inc and lib/curlx/CMakeLists.txt. Public-API exposure is forbidden by convention.
• A platform-specific compatibility shim → it almost certainly belongs here rather than in lib/curl_setup.h.
• Replacing a realloc loop with dynbuf → see existing patterns in lib/headers.c or lib/cookie.c for examples.

Related pages

• libcurl — what curlx supports
• Patterns and conventions — when to reach for curlx vs libc