#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
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.
.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
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.
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.
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.
+
+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.
-The application does not have to keep \fIcontent\fP around after a successful
-call.
+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 will effectively remove that part's contents
-from the \fICURLU\fP handle.
+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
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
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.
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
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
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
projects / thirdparty / curl.git / commitdiff
