"Fossies" - the Fresh Open Source Software Archive

Member "curl-7.67.0/docs/libcurl/libcurl-url.3" (6 Nov 2019, 5285 Bytes) of package /linux/www/curl-7.67.0.tar.xz:


Caution: As a special service "Fossies" has tried to format the requested manual source page into HTML format but links to other man pages may be missing or even erroneous. Alternatively you can here view or download the uninterpreted manual source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the latest Fossies "Diffs" side-by-side code changes report for "libcurl-url.3": 7.66.0_vs_7.67.0.

libcurl

NAME
DESCRIPTION
INCLUDE
CREATE
CLEANUP
DUPLICATE
PARSING
REDIRECT
GET URL
GET PARTS
SET PARTS
APPENDQUERY
SEE ALSO

NAME

libcurl-url − URL interface overview

DESCRIPTION

The URL interface provides a set of functions for parsing and generating URLs.

INCLUDE

You still only include <curl/curl.h> in your code. Note that the URL API was introduced in 7.62.0.

CREATE

Create a handle that holds URL info and resources with curl_url(3):

CURLU *h = curl_url();

CLEANUP

When done with it, clean it up with curl_url_cleanup(3):

curl_url_cleanup(h);

DUPLICATE

When you need a copy of a handle, just duplicate it with curl_url_dup(3):

CURLU *nh = curl_url_dup(h);

PARSING

By "setting" a URL to the handle with curl_url_set(3), the URL is parsed and stored in the handle. If the URL is not syntactically correct it will return 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

When a handle already contains info about a URL, setting a relative URL will make it "redirect" to adapt to it.

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

GET URL

The ‘CURLU‘ handle represents a URL and you can easily extract that with 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

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_HOST, &host, 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_PASSWORD, &password, 0);
rc = curl_url_get(h, CURLUPART_PORT, &port, 0);
rc = curl_url_get(h, CURLUPART_PATH, &path, 0);
rc = curl_url_get(h, CURLUPART_QUERY, &query, 0);
rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 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) when you’re done with it!

SET PARTS

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

rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 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_PASSWORD, "doe", 0);
rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0);
rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0);
rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0);
rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0);

Set parts are not URL encoded unless the user asks for it with the ‘CURLU_URLENCODE‘ flag.

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).

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 will even notice the lack of an ampersand (‘&‘) separator so it will inject one too, and the handle’s full URL will then equal ‘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 will skip 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‘

SEE ALSO

curl_url(3), curl_url_cleanup(3), curl_url_get(3), curl_url_dup(3), curl_url_set(3), CURLOPT_URL(3),