URL API

Active contributors: Daniel Stenberg, Viktor Szakats

Purpose

The URL API is a standalone parser and builder for RFC 3986 URLs (with curl's pragmatic extensions for IDN, scheme guessing, and bracket-style globbing during the tool — globbing itself is not part of the API). It is exposed for applications that want to parse, normalize, or compose URLs without performing a transfer. The same parser is what libcurl uses internally for every URL it handles.

Public surface

include/curl/urlapi.h:

CURLU *curl_url(void);
void   curl_url_cleanup(CURLU *handle);
CURLU *curl_url_dup(const CURLU *handle);

CURLUcode curl_url_set(CURLU *handle, CURLUPart what,
                       const char *part, unsigned int flags);
CURLUcode curl_url_get(const CURLU *handle, CURLUPart what,
                       char **part, unsigned int flags);
const char *curl_url_strerror(CURLUcode);

Parts addressable via CURLUPart: URL, SCHEME, USER, PASSWORD, OPTIONS, HOST, ZONEID, PORT, PATH, QUERY, FRAGMENT. Each can be read or written individually; URL reads/writes the assembled string.

Minimal example

CURLU *u = curl_url();
curl_url_set(u, CURLUPART_URL, "https://example.com/foo?a=1", 0);

char *host = NULL;
curl_url_get(u, CURLUPART_HOST, &host, 0);
printf("%s\n", host);          /* example.com */
curl_free(host);

curl_url_set(u, CURLUPART_PORT, "8080", 0);
char *full = NULL;
curl_url_get(u, CURLUPART_URL, &full, 0);
printf("%s\n", full);          /* https://example.com:8080/foo?a=1 */
curl_free(full);

curl_url_cleanup(u);

Reference: docs/examples/parseurl.c.

Flags

curl_url_set and curl_url_get accept option flags: CURLU_DEFAULT_SCHEME, CURLU_NON_SUPPORT_SCHEME, CURLU_GUESS_SCHEME, CURLU_NO_AUTHORITY, CURLU_PATH_AS_IS, CURLU_DISALLOW_USER, CURLU_URLENCODE / CURLU_URLDECODE, CURLU_APPENDQUERY, CURLU_PUNYCODE, CURLU_PUNY2IDN, CURLU_GET_EMPTY, CURLU_NO_GUESS_SCHEME, CURLU_NO_DEFAULT_PORT, CURLU_ALLOW_SPACE. Each is documented in docs/libcurl/curl_url_set.md etc.

Implementation

The parser lives in lib/urlapi.c (~56 KB). Internal layout in lib/urlapi-int.h. The handle is a struct Curl_URL with separate components and lazy normalization. The parser is non-allocating where possible (uses curlx strparse helpers) and produces a deterministic, escaping-safe rebuilt string when asked.

The same parser is used by lib/url.c to populate connection metadata, by lib/cookie.c to scope cookies, by lib/altsvc.c for alt-svc rewrites, and by lib/hsts.c for HSTS lookups.

libcurl-url subset library

For applications that only need URL parsing, the build can produce a separate library (libcurlu) containing just the URL API and the curlx pieces it needs. The build flag is --with-libcurl-pc/CMake equivalent.

trurl

The standalone trurl tool (started March 2023) is a thin wrapper around the URL API for shell scripting. It lives in https://github.com/curl/trurl rather than this repository, but it is the canonical "what does the URL API look like in practice" example.

Related pages

• Easy interface — CURLOPT_URL uses the same parser
• Cookies and state — cookie scope rules