Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
See header file and man pages for API. All documented API details work and are tested in the 1560 test case. Closes #2842
- Loading branch information
Showing
24 changed files
with
2,600 additions
and
340 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,101 @@ | ||
.\" ************************************************************************** | ||
.\" * _ _ ____ _ | ||
.\" * Project ___| | | | _ \| | | ||
.\" * / __| | | | |_) | | | ||
.\" * | (__| |_| | _ <| |___ | ||
.\" * \___|\___/|_| \_\_____| | ||
.\" * | ||
.\" * Copyright (C) 1998 - 2018, 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.haxx.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. | ||
.\" * | ||
.\" ************************************************************************** | ||
.TH curl_url 3 "6 Aug 2018" "libcurl" "libcurl Manual" | ||
.SH NAME | ||
curl_url - parse a URL and create a CURLURL handle | ||
.SH SYNOPSIS | ||
.B #include <curl/curl.h> | ||
|
||
.nf | ||
CURLUcode curl_url(const char *url, | ||
CURLURL **urlhandle, | ||
unsigned int flags) | ||
.fi | ||
.SH DESCRIPTION | ||
Pass a pointer to a zero terminated string to the \fIurl\fP parameter. The | ||
string must point to a correctly formatted "RFC 3986+" URL or be a NULL | ||
pointer. | ||
|
||
Pass a pointer to \fICURLURL *\fP handle in the second parameter and set the | ||
desired feature bits in the \fIflags\fP bitmask. | ||
|
||
This function will then allocate and make the \fIurlhandle\fP argument point | ||
to a fresh handle holding the details of the parsed URL. If a NULL pointer was | ||
passed instead of URL, the details of the URL can be subsequently filled in | ||
with calls to the \fIcurl_url_set(3)\fP function. | ||
|
||
Extract individual parts from the parsed URL with the \fIcurl_url_get(3)\fP | ||
function. | ||
|
||
The returned handle must be cleaned up with \fIcurl_url_cleanup(3)\fP when the | ||
application is done with it. | ||
.SH FLAGS | ||
The flags argument is zero, one or more bits set in a bitmask. | ||
.IP CURLURL_VERIFY_ONLY | ||
With this bit set, \fIcurl_url(3)\fP doesn't create nor return any handle in | ||
the second argument, it will only syntax-check the given URL and return | ||
OK/fail depending on that. | ||
.IP CURLURL_DEFAULT_SCHEME | ||
If set, \fIcurl_url(3)\fP allows the "URL" to be specified without a scheme | ||
part and it will instead behave as if the default scheme was used. The default | ||
scheme is "https". Without this bit set, a URL without the scheme part will be | ||
considered a syntax error. | ||
.IP CURLURL_NON_SUPPORT_SCHEME | ||
If set, \fIcurl_url(3)\fP allows URL schemes that matches syntactically even | ||
if they are not supported by this instance of libcurl. If not set, URLs with a | ||
non-support scheme will get \fICURLURLE_UNSUPPORTED_SCHEME\fP returned. | ||
.IP CURLURL_PATH_AS_IS | ||
If set, it prevents \fIcurl_url(3)\fP from merging and normalizing sequences | ||
of "../" and "./" in the path part, as it will otherwise do. | ||
.SH RETURN VALUE | ||
Returns a CURLUcode error value, which is CURLURLE_OK (0) if everything went | ||
fine. | ||
|
||
If this function returns an error, no CURLURL handle is returned. | ||
.SH "URL SYNTAX" | ||
This function understands and parses URLs exactly like libcurl does internally | ||
when told to transfer a URL. | ||
|
||
It mostly follows the RFC 3986 specification, with some minor alternations | ||
where adjustments have been made to better understand URLs that popular | ||
browsers accept. | ||
|
||
By default, this function only accepts URLs with schemes that have built-in | ||
support in libcurl, unless \fBCURLURL_NON_SUPPORT_SCHEME\fP is used. | ||
.SH EXAMPLE | ||
.nf | ||
CURLUcode rc; | ||
CURLURL *url; | ||
rc = curl_url("https://example.com", &url, 0); | ||
if(!rc) { | ||
char *scheme; | ||
rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0); | ||
if(!rc) { | ||
printf("the scheme is %s\n", scheme); | ||
curl_free(scheme); | ||
} | ||
curl_url_cleanup(url); | ||
} | ||
.fi | ||
.SH "SEE ALSO" | ||
.BR curl_url_cleanup "(3), " curl_url_get "(3), " curl_url_set "(3), " | ||
.BR curl_url_dup "(3), " |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,46 @@ | ||
.\" ************************************************************************** | ||
.\" * _ _ ____ _ | ||
.\" * Project ___| | | | _ \| | | ||
.\" * / __| | | | |_) | | | ||
.\" * | (__| |_| | _ <| |___ | ||
.\" * \___|\___/|_| \_\_____| | ||
.\" * | ||
.\" * Copyright (C) 1998 - 2018, 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.haxx.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. | ||
.\" * | ||
.\" ************************************************************************** | ||
.TH curl_url_cleanup 3 "6 Aug 2018" "libcurl" "libcurl Manual" | ||
.SH NAME | ||
curl_url_cleanup - free a CURLURL handle | ||
.SH SYNOPSIS | ||
.B #include <curl/curl.h> | ||
|
||
void curl_url_cleanup(CURLURL *handle); | ||
.fi | ||
.SH DESCRIPTION | ||
Frees all the resources associated with the given CURLURL handle! | ||
.SH RETURN VALUE | ||
none | ||
.SH EXAMPLE | ||
.nf | ||
CURLUcode rc; | ||
CURLURL *url; | ||
CURLURL *url2; | ||
rc = curl_url("https://example.com", &url, 0); | ||
if(!rc) { | ||
curl_url_cleanup(url); | ||
} | ||
.fi | ||
.SH "SEE ALSO" | ||
.BR curl_url_dup "(3), " curl_url "(3), " curl_url_set "(3), " | ||
.BR curl_url_get "(3), " |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,49 @@ | ||
.\" ************************************************************************** | ||
.\" * _ _ ____ _ | ||
.\" * Project ___| | | | _ \| | | ||
.\" * / __| | | | |_) | | | ||
.\" * | (__| |_| | _ <| |___ | ||
.\" * \___|\___/|_| \_\_____| | ||
.\" * | ||
.\" * Copyright (C) 1998 - 2018, 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.haxx.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. | ||
.\" * | ||
.\" ************************************************************************** | ||
.TH curl_url_dup 3 "6 Aug 2018" "libcurl" "libcurl Manual" | ||
.SH NAME | ||
curl_url_dup - duplicate a CURLURL handle | ||
.SH SYNOPSIS | ||
.B #include <curl/curl.h> | ||
|
||
CURLURL *curl_url_dup(CURLURL *inhandle); | ||
.fi | ||
.SH DESCRIPTION | ||
Duplicates a given CURLURL handle and all its contents and returns a new | ||
handle. The new handle also needs to be freed with \fIcurl_url_cleanup(3)\fP. | ||
.SH RETURN VALUE | ||
Returns a new handle or NULL if out of memory. | ||
.SH EXAMPLE | ||
.nf | ||
CURLUcode rc; | ||
CURLURL *url; | ||
CURLURL *url2; | ||
rc = curl_url("https://example.com", &url, 0); | ||
if(!rc) { | ||
url2 = curl_url_dup(url); /* clone it! */ | ||
curl_url_cleanup(url); | ||
curl_url_cleanup(url2); | ||
} | ||
.fi | ||
.SH "SEE ALSO" | ||
.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_set "(3), " | ||
.BR curl_url_get "(3), " |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,108 @@ | ||
.\" ************************************************************************** | ||
.\" * _ _ ____ _ | ||
.\" * Project ___| | | | _ \| | | ||
.\" * / __| | | | |_) | | | ||
.\" * | (__| |_| | _ <| |___ | ||
.\" * \___|\___/|_| \_\_____| | ||
.\" * | ||
.\" * Copyright (C) 1998 - 2018, 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.haxx.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. | ||
.\" * | ||
.\" ************************************************************************** | ||
.TH curl_url_get 3 "6 Aug 2018" "libcurl" "libcurl Manual" | ||
.SH NAME | ||
curl_url_get - extract a part from a URL | ||
.SH SYNOPSIS | ||
.B #include <curl/curl.h> | ||
|
||
.nf | ||
CURLUcode curl_url_get(CURLURL *url, | ||
CURLUPart what, | ||
char **part, | ||
unsigned int flags) | ||
.fi | ||
.SH DESCRIPTION | ||
Given the \fIurl\fP handle of an already parsed URL, this function lets the | ||
user extract individual pieces from it. | ||
|
||
The \fIwhat\fP argument should be the particular part to extract (see list | ||
below) and \fIpart\fP points to a 'char *' to get updated to point to a newly | ||
allocated string with the contents. | ||
|
||
The \fIflags\fP argument is a bitmask with individual features. | ||
|
||
The returned part pointer must be freed with \fIcurl_free(3)\fP after use. | ||
.SH FLAGS | ||
The flags argument is zero, one or more bits set in a bitmask. | ||
.IP CURLURL_DEFAULT_PORT | ||
If the handle has no port stored, this option will make \fIcurl_url_get(3)\fP | ||
return the default port for the used scheme. | ||
.IP CURLURL_DEFAULT_SCHEME | ||
If the handle has no scheme stored, this option will make | ||
\fIcurl_url_get(3)\fP return the default scheme instead of error. | ||
.IP CURLURL_NO_DEFAULT_PORT | ||
Instructs \fIcurl_url_get(3)\fP to not return a port number if it matches the | ||
default port for the scheme. | ||
.IP CURLURL_URLDECODE | ||
Asks \fPcurl_url_get(3)\fP to URL decode the contents before returning it. It | ||
will not attempt to decode the scheme, the port number or the full URL. | ||
|
||
The query component will also get plus-to-space convertion as a bonus when | ||
this bit is set. | ||
|
||
Note that this URL decoding is charset unaware and you will get a zero | ||
terminated string back with data that could be intended for a particular | ||
encoding. | ||
|
||
If there's any byte values lower than 32 in the decoded string, the get | ||
operation will return an error instead. | ||
.SH PARTS | ||
.IP CURLUPART_URL | ||
When asked to return the full URL, \fIcurl_url_get(3)\fP will return a | ||
normalized and possibly cleaned up version of what was previously parsed. | ||
.IP CURLUPART_SCHEME | ||
Scheme cannot be URL decoded on get. | ||
.IP CURLUPART_USER | ||
.IP CURLUPART_PASSWORD | ||
.IP CURLUPART_OPTIONS | ||
.IP CURLUPART_HOST | ||
.IP CURLUPART_PORT | ||
Port cannot be URL decoded on get. | ||
.IP CURLUPART_PATH | ||
.IP CURLUPART_QUERY | ||
The query part will also get pluses converted to space when asked to URL | ||
decode on get with the CURLURL_URLDECODE bit. | ||
.IP CURLUPART_FRAGMENT | ||
.SH RETURN VALUE | ||
Returns a CURLUcode error value, which is CURLURLE_OK (0) if everything went | ||
fine. | ||
|
||
If this function returns an error, no URL part is returned. | ||
.SH EXAMPLE | ||
.nf | ||
CURLUcode rc; | ||
CURLURL *url; | ||
rc = curl_url("https://example.com", &url, 0); | ||
if(!rc) { | ||
char *scheme; | ||
rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0); | ||
if(!rc) { | ||
printf("the scheme is %s\n", scheme); | ||
curl_free(scheme); | ||
} | ||
curl_url_cleanup(url); | ||
} | ||
.fi | ||
.SH "SEE ALSO" | ||
.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_set "(3), " | ||
.BR curl_url_dup "(3), " |
Oops, something went wrong.