.\" ************************************************************************** .\" * _ _ ____ _ .\" * Project ___| | | | _ \| | .\" * / __| | | | |_) | | .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * .\" * Copyright (C) Daniel Stenberg, , 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 "January 02, 2023" "libcurl 7.88.1" "libcurl Manual" .SH NAME curl_url_set - set a URL part .SH SYNOPSIS .nf #include CURLUcode curl_url_set(CURLU *url, CURLUPart part, const char *content, 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 \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. The application does not have to keep \fIcontent\fP around after a successful call. Setting a part to a NULL pointer will effectively remove 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 schemes it does not recognize. 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 will be replaced with the information 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. .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 .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). .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. .IP CURLUPART_PATH If a path is set in the URL without a leading slash, a slash will be inserted automatically when this URL is read from the handle. .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. 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 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. When \fICURLU_APPENDQUERY\fP is used together with \fICURLU_URLENCODE\fP, the first '=' symbol will not be 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 will 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. .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. .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 \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 makes libcurl skip the normalization of the path. That is the procedure where curl 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 \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 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. A URL string passed on to \fIcurl_url_set(3)\fP for the \fBCURLUPART_URL\fP part, must be shorter than 8000000 bytes otherwise it returns \fBCURLUE_MALFORMED_INPUT\fP (added in 7.65.0). If this function returns an error, no URL part is set. .SH "SEE ALSO" .BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_get "(3), " .BR curl_url_dup "(3), " curl_url_strerror "(3), " CURLOPT_CURLU "(3)"