curl_url*.3: update function descriptions
- expand and clarify several descriptions - avoid using future tense all over Closes #11708
This commit is contained in:
Daniel Stenberg
parent
c996e02afe
commit
8ef2992e11
@ -31,8 +31,13 @@ curl_url - returns a new URL handle
|
||||
CURLU *curl_url();
|
||||
.fi
|
||||
.SH DESCRIPTION
|
||||
This function will allocates and returns a pointer to a fresh \fICURLU\fP
|
||||
handle, to be used for further use of the URL API.
|
||||
This function allocates a URL object and returns a \fICURLU\fP handle for it,
|
||||
to be used as input to all other URL API functions.
|
||||
|
||||
This is a handle to a URL object that holds or can hold URL components for a
|
||||
single URL. When the object is first created, there is of course no components
|
||||
stored. They are then set in the object with the \fIcurl_url_set(3)\fP
|
||||
function.
|
||||
.SH EXAMPLE
|
||||
.nf
|
||||
CURLUcode rc;
|
||||
|
||||
@ -33,7 +33,7 @@ void curl_url_cleanup(CURLU *handle);
|
||||
.SH DESCRIPTION
|
||||
Frees all the resources associated with the given \fICURLU\fP handle!
|
||||
|
||||
Passing in a NULL pointer in \fIhandle\fP will make this function return
|
||||
Passing in a NULL pointer in \fIhandle\fP makes this function return
|
||||
immediately with no action.
|
||||
.SH EXAMPLE
|
||||
.nf
|
||||
|
||||
@ -31,9 +31,9 @@ curl_url_dup - duplicate a URL handle
|
||||
CURLU *curl_url_dup(CURLU *inhandle);
|
||||
.fi
|
||||
.SH DESCRIPTION
|
||||
Duplicates a given \fICURLU\fP \fIinhandle\fP and all its contents and returns
|
||||
a pointer to a new \fICURLU\fP handle. The new handle also needs to be freed
|
||||
with \fIcurl_url_cleanup(3)\fP.
|
||||
Duplicates the URL object the input \fICURLU\fP \fIinhandle\fP identifies and
|
||||
returns a pointer to the copy as a new \fICURLU\fP handle. The new handle also
|
||||
needs to be freed with \fIcurl_url_cleanup(3)\fP.
|
||||
.SH EXAMPLE
|
||||
.nf
|
||||
CURLUcode rc;
|
||||
|
||||
@ -29,56 +29,51 @@ curl_url_get - extract a part from a URL
|
||||
#include <curl/curl.h>
|
||||
|
||||
CURLUcode curl_url_get(CURLU *url,
|
||||
CURLUPart what,
|
||||
char **part,
|
||||
CURLUPart part,
|
||||
char **content,
|
||||
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.
|
||||
Given a \fIurl\fP handle of a URL object, this function extracts an individual
|
||||
piece or the full URL 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
|
||||
The \fIpart\fP argument specifies which part to extract (see list below) and
|
||||
\fIcontent\fP points to a 'char *' to get updated to point to a newly
|
||||
allocated string with the contents.
|
||||
|
||||
The URL API has no particular maximum length for URL fiends. In the real
|
||||
world, excessively long field in URLs will cause problems even if this API
|
||||
accepts them. This function can return very large ones.
|
||||
|
||||
The \fIflags\fP argument is a bitmask with individual features.
|
||||
|
||||
The returned part pointer must be freed with \fIcurl_free(3)\fP after use.
|
||||
The returned content 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 CURLU_DEFAULT_PORT
|
||||
If the handle has no port stored, this option will make \fIcurl_url_get(3)\fP
|
||||
If the handle has no port stored, this option makes \fIcurl_url_get(3)\fP
|
||||
return the default port for the used scheme.
|
||||
.IP CURLU_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.
|
||||
If the handle has no scheme stored, this option makes \fIcurl_url_get(3)\fP
|
||||
return the default scheme instead of error.
|
||||
.IP CURLU_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 CURLU_URLDECODE
|
||||
Asks \fIcurl_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.
|
||||
does not decode the scheme, the port number or the full URL.
|
||||
|
||||
The query component will also get plus-to-space conversion as a bonus when
|
||||
this bit is set.
|
||||
The query component also gets plus-to-space conversion 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.
|
||||
Note that this URL decoding is charset unaware and you 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.
|
||||
If there are byte values lower than 32 in the decoded string, the get
|
||||
operation returns an error instead.
|
||||
.IP CURLU_URLENCODE
|
||||
If set, will make \fIcurl_url_get(3)\fP URL encode the host name part when a
|
||||
full URL is retrieved. If not set (default), libcurl returns the URL with the
|
||||
host name "raw" to support IDN names to appear as-is. IDN host names are
|
||||
typically using non-ASCII bytes that otherwise will be percent-encoded.
|
||||
If set, \fIcurl_url_get(3)\fP URL encodes the host name part when a full URL
|
||||
is retrieved. If not set (default), libcurl returns the URL with the host name
|
||||
"raw" to support IDN names to appear as-is. IDN host names are typically using
|
||||
non-ASCII bytes that otherwise gets percent-encoded.
|
||||
|
||||
Note that even when not asking for URL encoding, the '%' (byte 37) will be URL
|
||||
Note that even when not asking for URL encoding, the '%' (byte 37) is URL
|
||||
encoded to make sure the host name remains valid.
|
||||
.IP CURLU_PUNYCODE
|
||||
If set and \fICURLU_URLENCODE\fP is not set, and asked to retrieve the
|
||||
@ -86,7 +81,7 @@ If set and \fICURLU_URLENCODE\fP is not set, and asked to retrieve the
|
||||
name in its punycode version if it contains any non-ASCII octets (and is an
|
||||
IDN name).
|
||||
|
||||
If libcurl is built without IDN capabilities, using this bit will make
|
||||
If libcurl is built without IDN capabilities, using this bit makes
|
||||
\fIcurl_url_get(3)\fP return \fICURLUE_LACKS_IDN\fP if the host name contains
|
||||
anything outside the ASCII range.
|
||||
|
||||
@ -94,18 +89,19 @@ anything outside the ASCII range.
|
||||
.IP CURLU_PUNY2IDN
|
||||
If set and asked to retrieve the \fBCURLUPART_HOST\fP or \fBCURLUPART_URL\fP
|
||||
parts, libcurl returns the host name in its IDN (International Domain Name)
|
||||
UTF-8 version if it otherwise is a punycode version. If the punycode cannot be
|
||||
converted to IDN correct, libcurl returns \fICURLUE_BAD_HOSTNAME\fP.
|
||||
UTF-8 version if it otherwise is a punycode version. If the punycode name
|
||||
cannot be converted to IDN correctly, libcurl returns
|
||||
\fICURLUE_BAD_HOSTNAME\fP.
|
||||
|
||||
If libcurl is built without IDN capabilities, using this bit will make
|
||||
If libcurl is built without IDN capabilities, using this bit makes
|
||||
\fIcurl_url_get(3)\fP return \fICURLUE_LACKS_IDN\fP if the host name is using
|
||||
punycode.
|
||||
|
||||
(Added in curl 8.3.0)
|
||||
.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.
|
||||
When asked to return the full URL, \fIcurl_url_get(3)\fP returns a normalized
|
||||
and possibly cleaned up version using all available URL parts.
|
||||
|
||||
We advise using the \fICURLU_PUNYCODE\fP option to get the URL as "normalized"
|
||||
as possible since IDN allows host names to be written in many different ways
|
||||
@ -120,9 +116,9 @@ userinfo part. It is only recognized/used when parsing URLs for the following
|
||||
schemes: pop3, smtp and imap. The URL API still allows users to set and get
|
||||
this field independently of scheme when not parsing full URLs.
|
||||
.IP CURLUPART_HOST
|
||||
The host name. If it is an IPv6 numeric address, the zone id will not be part
|
||||
of it but is provided separately in \fICURLUPART_ZONEID\fP. IPv6 numerical
|
||||
addresses are returned within brackets ([]).
|
||||
The host name. If it is an IPv6 numeric address, the zone id is not part of it
|
||||
but is provided separately in \fICURLUPART_ZONEID\fP. IPv6 numerical addresses
|
||||
are returned within brackets ([]).
|
||||
|
||||
IPv6 names are normalized when set, which should make them as short as
|
||||
possible while maintaining correct syntax.
|
||||
@ -133,17 +129,17 @@ A port cannot be URL decoded on get. This number is returned in a string just
|
||||
like all other parts. That string is guaranteed to hold a valid port number in
|
||||
ASCII using base 10.
|
||||
.IP CURLUPART_PATH
|
||||
The \fIpart\fP will be '/' even if no path is supplied in the URL. A URL path
|
||||
always starts with a slash.
|
||||
The \fIpart\fP is always at least a slash ('/') even if no path was supplied
|
||||
in the URL. A URL path always starts with a slash.
|
||||
.IP CURLUPART_QUERY
|
||||
The initial question mark that denotes the beginning of the query part is a
|
||||
delimiter only. It is not part of the query contents.
|
||||
|
||||
A not-present query will lead \fIpart\fP to be set to NULL.
|
||||
A zero-length query will lead \fIpart\fP to be set to a zero-length string.
|
||||
A not-present query returns \fIpart\fP set to NULL.
|
||||
A zero-length query returns \fIpart\fP as a zero-length string.
|
||||
|
||||
The query part will also get pluses converted to space when asked to URL
|
||||
decode on get with the CURLU_URLDECODE bit.
|
||||
The query part gets pluses converted to space when asked to URL decode on get
|
||||
with the CURLU_URLDECODE bit.
|
||||
.IP CURLUPART_FRAGMENT
|
||||
The initial hash sign that denotes the beginning of the fragment is a
|
||||
delimiter only. It is not part of the fragment contents.
|
||||
|
||||
@ -34,29 +34,36 @@ CURLUcode curl_url_set(CURLU *url,
|
||||
unsigned int flags)
|
||||
.fi
|
||||
.SH DESCRIPTION
|
||||
Given the \fIurl\fP handle of an already parsed URL, this function lets the
|
||||
user set/update individual pieces of it.
|
||||
The \fIurl\fP handle to work on, passed in as the first argument, must be a
|
||||
handle previously created by \fIcurl_url(3)\fP or \fIcurl_url_dup(3)\fP.
|
||||
|
||||
This function sets or updates individual URL components, or parts, held by the
|
||||
URL object the handle identifies.
|
||||
|
||||
The \fIpart\fP argument should identify the particular URL part (see list
|
||||
below) to set or change, with \fIcontent\fP pointing to a null-terminated
|
||||
string with the new contents for that URL part. The contents should be in the
|
||||
form and encoding they'd use in a URL: URL encoded.
|
||||
form and encoding they would use in a URL: URL encoded.
|
||||
|
||||
The application does not have to keep \fIcontent\fP around after a successful
|
||||
call.
|
||||
When setting part in the URL object that was previously already set, it
|
||||
replaces the data that was previously stored for that part with the new
|
||||
\fIcontent\fP.
|
||||
|
||||
Setting a part to a NULL pointer will effectively remove that part's contents
|
||||
from the \fICURLU\fP handle.
|
||||
The caller does not have to keep \fIcontent\fP around after a successful call
|
||||
as this function copies the content.
|
||||
|
||||
Setting a part to a NULL pointer removes that part's contents from the
|
||||
\fICURLU\fP handle.
|
||||
|
||||
By default, this API only accepts URLs using schemes for protocols that are
|
||||
supported built-in. To make libcurl parse URLs generically even for schemes it
|
||||
does not know about, the \fBCURLU_NON_SUPPORT_SCHEME\fP flags bit must be
|
||||
set. Otherwise, this function returns \fICURLUE_UNSUPPORTED_SCHEME\fP on URL
|
||||
set. Otherwise, this function returns \fICURLUE_UNSUPPORTED_SCHEME\fP for URL
|
||||
schemes it does not recognize.
|
||||
|
||||
This function call has no particular maximum length for any provided input
|
||||
string. In the real world, excessively long field in URLs will cause problems
|
||||
even if this API accepts them.
|
||||
This function has an 8 MB maximum length limit for all provided input strings.
|
||||
In the real world, excessively long fields in URLs cause problems even if this
|
||||
API accepts them.
|
||||
|
||||
When setting or updating contents of individual URL parts, this API might
|
||||
accept data that would not be otherwise possible to set in the string when it
|
||||
@ -70,7 +77,7 @@ Allows the full URL of the handle to be replaced. If the handle already is
|
||||
populated with a URL, the new URL can be relative to the previous.
|
||||
|
||||
When successfully setting a new URL, relative or absolute, the handle contents
|
||||
will be replaced with the information of the newly set URL.
|
||||
is replaced with the components of the newly set URL.
|
||||
|
||||
Pass a pointer to a null-terminated string to the \fIurl\fP parameter. The
|
||||
string must point to a correctly formatted "RFC 3986+" URL or be a NULL
|
||||
@ -89,23 +96,24 @@ userinfo part. It is only recognized/used when parsing URLs for the following
|
||||
schemes: pop3, smtp and imap. This function however allows users to
|
||||
independently set this field at will.
|
||||
.IP CURLUPART_HOST
|
||||
The host name. If it is IDNA the string must then be encoded as your locale
|
||||
says or UTF-8 (when WinIDN is used). If it is a bracketed IPv6 numeric address
|
||||
it may contain a zone id (or you can use CURLUPART_ZONEID).
|
||||
The host name. If it is International Domain Name (IDN) the string must then
|
||||
be encoded as your locale says or UTF-8 (when WinIDN is used). If it is a
|
||||
bracketed IPv6 numeric address it may contain a zone id (or you can use
|
||||
\fICURLUPART_ZONEID\fP).
|
||||
|
||||
Unless \fICURLU_NO_AUTHORITY\fP is set, a blank host name is not allowed to set.
|
||||
.IP CURLUPART_ZONEID
|
||||
If the host name is a numeric IPv6 address, this field can also be set.
|
||||
.IP CURLUPART_PORT
|
||||
Port cannot be URL encoded on set. The given port number is provided as a
|
||||
string and the decimal number must be between 1 and 65535. Anything else will
|
||||
return an error.
|
||||
The port number cannot be URL encoded on set. The given port number is
|
||||
provided as a string and the decimal number in it must be between 0 and
|
||||
65535. Anything else returns an error.
|
||||
.IP CURLUPART_PATH
|
||||
If a path is set in the URL without a leading slash, a slash will be prepended
|
||||
If a path is set in the URL without a leading slash, a slash is prepended
|
||||
automatically.
|
||||
.IP CURLUPART_QUERY
|
||||
The query part will also get spaces converted to pluses when asked to URL
|
||||
encode on set with the \fICURLU_URLENCODE\fP bit.
|
||||
The query part gets spaces converted to pluses when asked to URL encode on set
|
||||
with the \fICURLU_URLENCODE\fP bit.
|
||||
|
||||
If used together with the \fICURLU_APPENDQUERY\fP bit, the provided part is
|
||||
appended on the end of the existing query.
|
||||
@ -117,12 +125,12 @@ The hash sign in the URL is not part of the actual fragment contents.
|
||||
The flags argument is zero, one or more bits set in a bitmask.
|
||||
.IP CURLU_APPENDQUERY
|
||||
Can be used when setting the \fICURLUPART_QUERY\fP component. The provided new
|
||||
part will then instead be appended at the end of the existing query - and if
|
||||
the previous part did not end with an ampersand (&), an ampersand gets
|
||||
inserted before the new appended part.
|
||||
part is then appended at the end of the existing query - and if the previous
|
||||
part did not end with an ampersand (&), an ampersand gets inserted before the
|
||||
new appended part.
|
||||
|
||||
When \fICURLU_APPENDQUERY\fP is used together with \fICURLU_URLENCODE\fP, the
|
||||
first '=' symbol will not be URL encoded.
|
||||
first '=' symbol is not URL encoded.
|
||||
.IP CURLU_NON_SUPPORT_SCHEME
|
||||
If set, allows \fIcurl_url_set(3)\fP to set a non-supported scheme.
|
||||
.IP CURLU_URLENCODE
|
||||
@ -130,21 +138,21 @@ When set, \fIcurl_url_set(3)\fP URL encodes the part on entry, except for
|
||||
scheme, port and URL.
|
||||
|
||||
When setting the path component with URL encoding enabled, the slash character
|
||||
will be skipped.
|
||||
is be skipped.
|
||||
|
||||
The query part gets space-to-plus conversion before the URL conversion.
|
||||
|
||||
This URL encoding is charset unaware and will convert the input on a
|
||||
byte-by-byte manner.
|
||||
This URL encoding is charset unaware and converts the input in a byte-by-byte
|
||||
manner.
|
||||
.IP CURLU_DEFAULT_SCHEME
|
||||
If set, will make libcurl allow the URL to be set without a scheme and then
|
||||
sets that to the default scheme: HTTPS. Overrides the \fICURLU_GUESS_SCHEME\fP
|
||||
option if both are set.
|
||||
If set, allows the URL to be set without a scheme and then sets that to the
|
||||
default scheme: HTTPS. Overrides the \fICURLU_GUESS_SCHEME\fP option if both
|
||||
are set.
|
||||
.IP CURLU_GUESS_SCHEME
|
||||
If set, will make libcurl allow the URL to be set without a scheme and it
|
||||
instead "guesses" which scheme that was intended based on the host name. If
|
||||
the outermost sub-domain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then
|
||||
that scheme will be used, otherwise it picks HTTP. Conflicts with the
|
||||
If set, allows the URL to be set without a scheme and it instead "guesses"
|
||||
which scheme that was intended based on the host name. If the outermost
|
||||
sub-domain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that scheme
|
||||
is used, otherwise it picks HTTP. Conflicts with the
|
||||
\fICURLU_DEFAULT_SCHEME\fP option which takes precedence if both are set.
|
||||
.IP CURLU_NO_AUTHORITY
|
||||
If set, skips authority checks. The RFC allows individual schemes to omit the
|
||||
@ -152,22 +160,22 @@ host part (normally the only mandatory part of the authority), but libcurl
|
||||
cannot know whether this is permitted for custom schemes. Specifying the flag
|
||||
permits empty authority sections, similar to how file scheme is handled.
|
||||
.IP CURLU_PATH_AS_IS
|
||||
When set for \fBCURLUPART_URL\fP, this makes libcurl skip the normalization of
|
||||
the path. That is the procedure where curl otherwise removes sequences of
|
||||
When set for \fBCURLUPART_URL\fP, this skips the normalization of the
|
||||
path. That is the procedure where libcurl otherwise removes sequences of
|
||||
dot-slash and dot-dot etc. The same option used for transfers is called
|
||||
\fICURLOPT_PATH_AS_IS(3)\fP.
|
||||
.IP CURLU_ALLOW_SPACE
|
||||
If set, the URL parser allows space (ASCII 32) where possible. The URL
|
||||
syntax does normally not allow spaces anywhere, but they should be encoded as
|
||||
%20 or '+'. When spaces are allowed, they are still not allowed in the scheme.
|
||||
When space is used and allowed in a URL, it will be stored as-is unless
|
||||
\fICURLU_URLENCODE\fP is also set, which then makes libcurl URL-encode the
|
||||
space before stored. This affects how the URL will be constructed when
|
||||
If set, the URL parser allows space (ASCII 32) where possible. The URL syntax
|
||||
does normally not allow spaces anywhere, but they should be encoded as %20
|
||||
or '+'. When spaces are allowed, they are still not allowed in the scheme.
|
||||
When space is used and allowed in a URL, it is stored as-is unless
|
||||
\fICURLU_URLENCODE\fP is also set, which then makes libcurl URL encode the
|
||||
space before stored. This affects how the URL is constructed when
|
||||
\fIcurl_url_get(3)\fP is subsequently used to extract the full URL or
|
||||
individual parts. (Added in 7.78.0)
|
||||
.IP CURLU_DISALLOW_USER
|
||||
If set, the URL parser will not accept embedded credentials for the
|
||||
\fBCURLUPART_URL\fP, and will instead return \fBCURLUE_USER_NOT_ALLOWED\fP for
|
||||
If set, the URL parser does not accept embedded credentials for the
|
||||
\fBCURLUPART_URL\fP, and instead returns \fBCURLUE_USER_NOT_ALLOWED\fP for
|
||||
such URLs.
|
||||
.SH EXAMPLE
|
||||
.nf
|
||||
|
||||
Loading…
Reference in New Issue
Block a user