| .\" ************************************************************************** |
| .\" * _ _ ____ _ |
| .\" * Project ___| | | | _ \| | |
| .\" * / __| | | | |_) | | |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| .\" * Copyright (C) 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.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. |
| .\" * |
| .\" * SPDX-License-Identifier: curl |
| .\" * |
| .\" ************************************************************************** |
| .TH curl_url_set 3 "6 Aug 2018" "libcurl" "libcurl" |
| .SH NAME |
| curl_url_set - set a URL part |
| .SH SYNOPSIS |
| .nf |
| #include <curl/curl.h> |
| |
| CURLUcode curl_url_set(CURLU *url, |
| CURLUPart part, |
| const char *content, |
| unsigned int flags); |
| .fi |
| .SH DESCRIPTION |
| 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 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 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 for URL |
| schemes it does not recognize. |
| |
| 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 |
| gets populated as a result of a full URL parse. Beware. If done so, extracting |
| a full URL later on from such components might render an invalid URL. |
| |
| The \fIflags\fP argument is a bitmask with independent features. |
| .SH PARTS |
| .IP CURLUPART_URL |
| 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 |
| 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 |
| pointer. |
| |
| Unless \fICURLU_NO_AUTHORITY\fP is set, a blank host name is not allowed in |
| the URL. |
| .IP CURLUPART_SCHEME |
| Scheme cannot be URL decoded on set. libcurl only accepts setting schemes up |
| to 40 bytes long. |
| .IP CURLUPART_USER |
| .IP CURLUPART_PASSWORD |
| .IP CURLUPART_OPTIONS |
| The options field is an optional field that might follow the password in the |
| 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. |
| .IP CURLUPART_HOST |
| 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 |
| 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 is prepended |
| automatically. |
| .IP CURLUPART_QUERY |
| 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 question mark in the URL is not part of the actual query contents. |
| .IP CURLUPART_FRAGMENT |
| The hash sign in the URL is not part of the actual fragment contents. |
| .SH FLAGS |
| 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 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 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 |
| 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 |
| is be skipped. |
| |
| The query part gets space-to-plus conversion before the URL conversion. |
| |
| This URL encoding is charset unaware and converts the input in a byte-by-byte |
| manner. |
| .IP CURLU_DEFAULT_SCHEME |
| 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, 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 |
| subdomain 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 |
| 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 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 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 does not accept embedded credentials for the |
| \fBCURLUPART_URL\fP, and instead returns \fBCURLUE_USER_NOT_ALLOWED\fP for |
| such URLs. |
| .SH EXAMPLE |
| .nf |
| CURLUcode rc; |
| CURLU *url = curl_url(); |
| rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); |
| if(!rc) { |
| char *scheme; |
| /* change it to an FTP URL */ |
| rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0); |
| } |
| curl_url_cleanup(url); |
| .fi |
| .SH AVAILABILITY |
| Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0. |
| .SH RETURN VALUE |
| Returns a \fICURLUcode\fP error value, which is CURLUE_OK (0) if everything |
| went fine. See the \fIlibcurl-errors(3)\fP man page for the full list with |
| descriptions. |
| |
| The input string passed to \fIcurl_url_set(3)\fP must be shorter than eight |
| million bytes. Otherwise this function returns \fBCURLUE_MALFORMED_INPUT\fP. |
| |
| If this function returns an error, no URL part is set. |
| .SH "SEE ALSO" |
| .BR curl_url (3), |
| .BR curl_url_cleanup (3), |
| .BR curl_url_dup (3), |
| .BR curl_url_get (3), |
| .BR curl_url_strerror (3), |
| .BR CURLOPT_CURLU (3) |