149 lines
5.4 KiB
Groff
149 lines
5.4 KiB
Groff
|
.\" **************************************************************************
|
||
|
|
.\" * _ _ ____ _
|
||
|
|
.\" * Project ___| | | | _ \| |
|
||
|
|
.\" * / __| | | | |_) | |
|
||
|
|
.\" * | (__| |_| | _ <| |___
|
||
|
|
.\" * \___|\___/|_| \_\_____|
|
||
|
|
.\" *
|
||
|
|
.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
|
||
|
|
.\" *
|
||
|
|
.\" * This software is licensed as described in the file COPYING, which
|
||
|
|
.\" * you should have received as part of this distribution. The terms
|
||
|
|
.\" * are also available at https://curl.se/docs/copyright.html.
|
||
|
|
.\" *
|
||
|
|
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
||
|
|
.\" * copies of the Software, and permit persons to whom the Software is
|
||
|
|
.\" * furnished to do so, under the terms of the COPYING file.
|
||
|
|
.\" *
|
||
|
|
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
||
|
|
.\" * KIND, either express or implied.
|
||
|
|
.\" *
|
||
|
|
.\" * SPDX-License-Identifier: curl
|
||
|
|
.\" *
|
||
|
|
.\" **************************************************************************
|
||
|
|
.TH libcurl 3 "August 22, 2023" "libcurl 8.3.0" "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'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:
|
||
|
|
.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 AVAILABILITY
|
||
|
|
The URL API was introduced in libcurl 7.62.0.
|
||
|
|
|
||
|
|
A URL with a literal IPv6 address can be parsed even when IPv6 support is not
|
||
|
|
enabled.
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
.BR curl_url "(3), " curl_url_cleanup "(3), " curl_url_get "(3), "
|
||
|
|
.BR curl_url_dup "(3), " curl_url_set "(3), " curl_url_strerror "(3), "
|
||
|
|
.BR CURLOPT_URL "(3)"
|