libcurl-url(3) Library Functions Manual libcurl-url(3)

# [NAME](#NAME)

libcurl-url - URL interface overview

# [DESCRIPTION](#DESCRIPTION)

The URL interface provides functions for parsing and generating URLs.

# [INCLUDE](#INCLUDE)

You still only include <curl/curl.h> in your code.

# [CREATE](#CREATE)

Create a handle that holds URL info and resources with [*curl\_url(3)*](/man/os/curl/curl_url.3):

```


  CURLU *h = curl_url();
```

# [CLEANUP](#CLEANUP)

When done with it, clean it up with [*curl\_url\_cleanup(3)*](/man/os/curl/curl_url_cleanup.3)

```


  curl_url_cleanup(h);
```

# [DUPLICATE](#DUPLICATE)

When you need a copy of a handle, duplicate it with [*curl\_url\_dup(3)*](/man/os/curl/curl_url_dup.3):

```


  CURLU *nh = curl_url_dup(h);
```

# [PARSING](#PARSING)

By setting a URL to the handle with [*curl\_url\_set(3)*](/man/os/curl/curl_url_set.3), the URL is parsed and stored in the handle. If the URL is not syntactically correct it returns an error instead.

```


  rc = curl_url_set(h, CURLUPART_URL,


                    "https://example.com:449/foo/bar?name=moo", 0);
```

The zero in the fourth argument is a bitmask for changing specific features.

If successful, this stores the URL in its individual parts within the handle.

# [REDIRECT](#REDIRECT)

When a handle already contains info about a URL, setting a relative URL makes it "redirect" to that.

```


  rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0);
```

# [GET URL](#GET_URL)

The **CURLU** handle represents a URL and you can easily extract that with [*curl\_url\_get(3)*](/man/os/curl/curl_url_get.3):

```


  char *url;


  rc = curl_url_get(h, CURLUPART_URL, &url, 0);


  curl_free(url);
```

The zero in the fourth argument is a bitmask for changing specific features.

# [GET PARTS](#GET_PARTS)

When a URL has been parsed or parts have been set, you can extract those pieces from the handle at any time.

```


  rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0);


  rc = curl_url_get(h, CURLUPART_HOST, &host, 0);


  rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0);


  rc = curl_url_get(h, CURLUPART_PATH, &path, 0);


  rc = curl_url_get(h, CURLUPART_PORT, &port, 0);


  rc = curl_url_get(h, CURLUPART_QUERY, &query, 0);


  rc = curl_url_get(h, CURLUPART_SCHEME, &scheme, 0);


  rc = curl_url_get(h, CURLUPART_USER, &user, 0);


  rc = curl_url_get(h, CURLUPART_ZONEID, &zoneid, 0);
```

Extracted parts are not URL decoded unless the user also asks for it with the *CURLU\_URLDECODE* flag set in the fourth bitmask argument.

Remember to free the returned string with [*curl\_free(3)*](/man/os/curl/curl_free.3) when you are done with it.

# [SET PARTS](#SET_PARTS)

A user can set individual URL parts, either after having parsed a full URL or instead of parsing one.

```


  rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0);


  rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0);


  rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0);


  rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0);


  rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0);


  rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0);


  rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0);


  rc = curl_url_set(urlp, CURLUPART_USER, "john", 0);


  rc = curl_url_set(urlp, CURLUPART_ZONEID, "eth0", 0);
```

Set parts are not URL encoded unless the user asks for it with the *CURLU\_URLENCODE* flag.

# [CURLU\_APPENDQUERY](#CURLU_APPENDQUERY)

An application can append a string to the right end of the query part with the *CURLU\_APPENDQUERY* flag to [*curl\_url\_set(3)*](/man/os/curl/curl_url_set.3).

Imagine a handle that holds the URL "https://example.com/?shoes=2". An application can then add the string "hat=1" to the query part like this:

```


  rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY);
```

It notices the lack of an ampersand (&) separator and injects one, and the handle's full URL then equals "https://example.com/?shoes=2&hat=1".

The appended string can of course also get URL encoded on add, and if asked to URL encode, the encoding process skips the '=' character. For example, append "candy=N&N" to what we already have, and URL encode it to deal with the ampersand in the data:

```


  rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N",


                    CURLU_APPENDQUERY | CURLU_URLENCODE);
```

Now the URL looks like

```


  https://example.com/?shoes=2&hat=1&candy=N%26N
```

# [NOTES](#NOTES)

A URL with a literal IPv6 address can be parsed even when IPv6 support is not enabled.

# [SEE ALSO](#SEE_ALSO)

[**CURLOPT\_URL**(3)](/man/os/curl/CURLOPT_URL.3), [**curl\_url**(3)](/man/os/curl/curl_url.3), [**curl\_url\_cleanup**(3)](/man/os/curl/curl_url_cleanup.3), [**curl\_url\_dup**(3)](/man/os/curl/curl_url_dup.3), [**curl\_url\_get**(3)](/man/os/curl/curl_url_get.3), [**curl\_url\_set**(3)](/man/os/curl/curl_url_set.3), [**curl\_url\_strerror**(3)](/man/os/curl/curl_url_strerror.3)

2026-09-24 libcurl

---

Document: libcurl-url(3) from curl 8.22.0-r3 (Chainguard OS)
Source: https://github.com/curl/curl.git