| 1 |
.\" ************************************************************************** |
| 2 |
.\" * _ _ ____ _ |
| 3 |
.\" * Project ___| | | | _ \| | |
| 4 |
.\" * / __| | | | |_) | | |
| 5 |
.\" * | (__| |_| | _ <| |___ |
| 6 |
.\" * \___|\___/|_| \_\_____| |
| 7 |
.\" * |
| 8 |
.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| 9 |
.\" * |
| 10 |
.\" * This software is licensed as described in the file COPYING, which |
| 11 |
.\" * you should have received as part of this distribution. The terms |
| 12 |
.\" * are also available at https://curl.haxx.se/docs/copyright.html. |
| 13 |
.\" * |
| 14 |
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell |
| 15 |
.\" * copies of the Software, and permit persons to whom the Software is |
| 16 |
.\" * furnished to do so, under the terms of the COPYING file. |
| 17 |
.\" * |
| 18 |
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY |
| 19 |
.\" * KIND, either express or implied. |
| 20 |
.\" * |
| 21 |
.\" ************************************************************************** |
| 22 |
.TH curl_url_set 3 "6 Aug 2018" "libcurl" "libcurl Manual" |
| 23 |
.SH NAME |
| 24 |
curl_url_set - set a URL part |
| 25 |
.SH SYNOPSIS |
| 26 |
.B #include <curl/curl.h> |
| 27 |
|
| 28 |
CURLUcode curl_url_set(CURLU *url, |
| 29 |
CURLUPart part, |
| 30 |
const char *content, |
| 31 |
unsigned int flags) |
| 32 |
.fi |
| 33 |
.SH DESCRIPTION |
| 34 |
Given the \fIurl\fP handle of an already parsed URL, this function lets the |
| 35 |
user set/update individual pieces of it. |
| 36 |
|
| 37 |
The \fIpart\fP argument should identify the particular URL part (see list |
| 38 |
below) to set or change, with \fIcontent\fP pointing to a zero terminated |
| 39 |
string with the new contents for that URL part. The contents should be in the |
| 40 |
form and encoding they'd use in a URL: URL encoded. |
| 41 |
|
| 42 |
Setting a part to a NULL pointer will effectively remove that part's contents |
| 43 |
from the CURLU handle. |
| 44 |
|
| 45 |
The \fIflags\fP argument is a bitmask with independent features. |
| 46 |
.SH PARTS |
| 47 |
.IP CURLUPART_URL |
| 48 |
Allows the full URL of the handle to be replaced. If the handle already is |
| 49 |
populated with a URL, the new URL can be relative to the previous. |
| 50 |
|
| 51 |
When successfully setting a new URL, relative or absolute, the handle contents |
| 52 |
will be replaced with the information of the newly set URL. |
| 53 |
|
| 54 |
Pass a pointer to a zero terminated string to the \fIurl\fP parameter. The |
| 55 |
string must point to a correctly formatted "RFC 3986+" URL or be a NULL |
| 56 |
pointer. |
| 57 |
.IP CURLUPART_SCHEME |
| 58 |
Scheme cannot be URL decoded on set. |
| 59 |
.IP CURLUPART_USER |
| 60 |
.IP CURLUPART_PASSWORD |
| 61 |
.IP CURLUPART_OPTIONS |
| 62 |
.IP CURLUPART_HOST |
| 63 |
The host name. If it is IDNA the string must then be encoded as your locale |
| 64 |
says or UTF-8 (when WinIDN is used). If it is a bracketed IPv6 numeric address |
| 65 |
it may contain a zone id (or you can use CURLUPART_ZONEID). |
| 66 |
.IP CURLUPART_ZONEID |
| 67 |
If the host name is a numeric IPv6 address, this field can also be set. |
| 68 |
.IP CURLUPART_PORT |
| 69 |
Port cannot be URL encoded on set. The given port number is provided as a |
| 70 |
string and the decimal number must be between 1 and 65535. Anything else will |
| 71 |
return an error. |
| 72 |
.IP CURLUPART_PATH |
| 73 |
If a path is set in the URL without a leading slash, a slash will be inserted |
| 74 |
automatically when this URL is read from the handle. |
| 75 |
.IP CURLUPART_QUERY |
| 76 |
The query part will also get spaces converted to pluses when asked to URL |
| 77 |
encode on set with the CURLU_URLENCODE bit. |
| 78 |
|
| 79 |
If used together with the \fICURLU_APPENDQUERY\fP bit, the provided part will |
| 80 |
be appended on the end of the existing query - and if the previous part didn't |
| 81 |
end with an ampersand (&), an ampersand will be inserted before the new |
| 82 |
appended part. |
| 83 |
|
| 84 |
When \fICURLU_APPENDQUERY\fP is used together with \fICURLU_URLENCODE\fP, the |
| 85 |
first '=' symbol will not be URL encoded. |
| 86 |
|
| 87 |
The question mark in the URL is not part of the actual query contents. |
| 88 |
.IP CURLUPART_FRAGMENT |
| 89 |
The hash sign in the URL is not part of the actual fragment contents. |
| 90 |
.SH FLAGS |
| 91 |
The flags argument is zero, one or more bits set in a bitmask. |
| 92 |
.IP CURLU_NON_SUPPORT_SCHEME |
| 93 |
If set, allows \fIcurl_url_set(3)\fP to set a non-supported scheme. |
| 94 |
.IP CURLU_URLENCODE |
| 95 |
When set, \fIcurl_url_set(3)\fP URL encodes the part on entry, except for |
| 96 |
scheme, port and URL. |
| 97 |
|
| 98 |
When setting the path component with URL encoding enabled, the slash character |
| 99 |
will be skipped. |
| 100 |
|
| 101 |
The query part gets space-to-plus conversion before the URL conversion. |
| 102 |
|
| 103 |
This URL encoding is charset unaware and will convert the input on a |
| 104 |
byte-by-byte manner. |
| 105 |
.IP CURLU_DEFAULT_SCHEME |
| 106 |
If set, will make libcurl allow the URL to be set without a scheme and then |
| 107 |
sets that to the default scheme: HTTPS. Overrides the \fICURLU_GUESS_SCHEME\fP |
| 108 |
option if both are set. |
| 109 |
.IP CURLU_GUESS_SCHEME |
| 110 |
If set, will make libcurl allow the URL to be set without a scheme and it |
| 111 |
instead "guesses" which scheme that was intended based on the host name. If |
| 112 |
the outermost sub-domain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then |
| 113 |
that scheme will be used, otherwise it picks HTTP. Conflicts with the |
| 114 |
\fICURLU_DEFAULT_SCHEME\fP option which takes precedence if both are set. |
| 115 |
.IP CURLU_NO_AUTHORITY |
| 116 |
If set, skips authority checks. The RFC allows individual schemes to omit the |
| 117 |
host part (normally the only mandatory part of the authority), but libcurl |
| 118 |
cannot know whether this is permitted for custom schemes. Specifying the flag |
| 119 |
permits empty authority sections, similar to how file scheme is handled. |
| 120 |
|
| 121 |
.SH RETURN VALUE |
| 122 |
Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went |
| 123 |
fine. |
| 124 |
|
| 125 |
A URL string passed on to \fIcurl_url_set(3)\fP for the \fBCURLUPART_URL\fP |
| 126 |
part, must be shorter than 8000000 bytes otherwise it returns |
| 127 |
\fBCURLUE_MALFORMED_INPUT\fP (added in 7.65.0). |
| 128 |
|
| 129 |
If this function returns an error, no URL part is returned. |
| 130 |
.SH EXAMPLE |
| 131 |
.nf |
| 132 |
CURLUcode rc; |
| 133 |
CURLU *url = curl_url(); |
| 134 |
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); |
| 135 |
if(!rc) { |
| 136 |
char *scheme; |
| 137 |
/* change it to an FTP URL */ |
| 138 |
rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0); |
| 139 |
} |
| 140 |
curl_url_cleanup(url); |
| 141 |
.fi |
| 142 |
.SH AVAILABILITY |
| 143 |
Added in curl 7.62.0. CURLUPART_ZONEID was added in 7.65.0. |
| 144 |
.SH "SEE ALSO" |
| 145 |
.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_get "(3), " |
| 146 |
.BR curl_url_dup "(3), " |