| Server IP : 153.92.12.133 / Your IP : 216.73.217.6 Web Server : LiteSpeed System : Linux id-dci-web1986.main-hosting.eu 5.14.0-611.26.1.el9_7.x86_64 #1 SMP PREEMPT_DYNAMIC Thu Jan 29 05:24:47 EST 2026 x86_64 User : u686484674 ( 686484674) PHP Version : 8.0.30 Disable Function : system, exec, shell_exec, passthru, mysql_list_dbs, ini_alter, dl, symlink, link, chgrp, leak, popen, apache_child_terminate, virtual, mb_send_mail MySQL : OFF | cURL : ON | WGET : ON | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : /proc/self/root/opt/alt/curlssl30/usr/share/man/man3/ |
Upload File : |
.\" generated by cd2nroff 0.1 from libcurl-url.md
.TH libcurl-url 3 "2025-06-27" libcurl
.SH NAME
libcurl\-url \- URL interface overview
.SH DESCRIPTION
The URL interface provides functions for parsing and generating URLs.
.SH INCLUDE
You still only include <curl/curl.h> in your code.
.SH CREATE
Create a handle that holds URL info and resources with \fIcurl_url(3)\fP:
.nf
CURLU *h = curl_url();
.fi
.SH CLEANUP
When done with it, clean it up with \fIcurl_url_cleanup(3)\fP
.nf
curl_url_cleanup(h);
.fi
.SH DUPLICATE
When you need a copy of a handle, just duplicate it with \fIcurl_url_dup(3)\fP:
.nf
CURLU *nh = curl_url_dup(h);
.fi
.SH PARSING
By setting a URL to the handle with \fIcurl_url_set(3)\fP, the URL is parsed
and stored in the handle. If the URL is not syntactically correct it returns
an error instead.
.nf
rc = curl_url_set(h, CURLUPART_URL,
"https://example.com:449/foo/bar?name=moo", 0);
.fi
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.
.SH REDIRECT
When a handle already contains info about a URL, setting a relative URL makes
it "redirect" to that.
.nf
rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0);
.fi
.SH GET URL
The \fBCURLU\fP handle represents a URL and you can easily extract that with
\fIcurl_url_get(3)\fP:
.nf
char *url;
rc = curl_url_get(h, CURLUPART_URL, &url, 0);
curl_free(url);
.fi
The zero in the fourth argument is a bitmask for changing specific features.
.SH GET PARTS
When a URL has been parsed or parts have been set, you can extract those
pieces from the handle at any time.
.nf
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);
.fi
Extracted parts are not URL decoded unless the user also asks for it with the
\fICURLU_URLDECODE\fP flag set in the fourth bitmask argument.
Remember to free the returned string with \fIcurl_free(3)\fP when you are done
with it.
.SH SET PARTS
A user set individual URL parts, either after having parsed a full URL or
instead of parsing such.
.nf
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);
.fi
Set parts are not URL encoded unless the user asks for it with the
\fICURLU_URLENCODE\fP flag.
.SH CURLU_APPENDQUERY
An application can append a string to the right end of the query part with the
\fICURLU_APPENDQUERY\fP flag to \fIcurl_url_set(3)\fP.
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:
.nf
rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY);
.fi
It notices the lack of an ampersand (&) separator and injects one, and the
handle\(aqs 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 \(aq=\(aq character. For example, append
\&"candy=N&N" to what we already have, and URL encode it to deal with the
ampersand in the data:
.nf
rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N",
CURLU_APPENDQUERY | CURLU_URLENCODE);
.fi
Now the URL looks like
.nf
https://example.com/?shoes=2&hat=1&candy=N%26N
.fi
.SH NOTES
A URL with a literal IPv6 address can be parsed even when IPv6 support is not
enabled.
.SH SEE ALSO
.BR CURLOPT_URL (3),
.BR curl_url (3),
.BR curl_url_cleanup (3),
.BR curl_url_dup (3),
.BR curl_url_get (3),
.BR curl_url_set (3),
.BR curl_url_strerror (3)