From: Daniel Stenberg Date: Tue, 22 Aug 2023 09:26:05 +0000 (+0200) Subject: curl_url*.3: update function descriptions X-Git-Tag: curl-8_3_0~125 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=8ef2992e113ef655b6c56442c22584d6cd7d641d;p=thirdparty%2Fcurl.git curl_url*.3: update function descriptions - expand and clarify several descriptions - avoid using future tense all over Closes #11708 --- diff --git a/docs/libcurl/curl_url.3 b/docs/libcurl/curl_url.3 index a7143b0b18..52ec37362c 100644 --- a/docs/libcurl/curl_url.3 +++ b/docs/libcurl/curl_url.3 @@ -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; diff --git a/docs/libcurl/curl_url_cleanup.3 b/docs/libcurl/curl_url_cleanup.3 index 2e32668e6d..f3c8dff822 100644 --- a/docs/libcurl/curl_url_cleanup.3 +++ b/docs/libcurl/curl_url_cleanup.3 @@ -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 diff --git a/docs/libcurl/curl_url_dup.3 b/docs/libcurl/curl_url_dup.3 index f04f6bba9f..57931cc8f5 100644 --- a/docs/libcurl/curl_url_dup.3 +++ b/docs/libcurl/curl_url_dup.3 @@ -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; diff --git a/docs/libcurl/curl_url_get.3 b/docs/libcurl/curl_url_get.3 index aca160392d..fb02152eee 100644 --- a/docs/libcurl/curl_url_get.3 +++ b/docs/libcurl/curl_url_get.3 @@ -29,56 +29,51 @@ curl_url_get - extract a part from a URL #include 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. diff --git a/docs/libcurl/curl_url_set.3 b/docs/libcurl/curl_url_set.3 index cffe745e82..bfc6bc6d63 100644 --- a/docs/libcurl/curl_url_set.3 +++ b/docs/libcurl/curl_url_set.3 @@ -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. + +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 @@ -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