212 lines
8.9 KiB
Groff
212 lines
8.9 KiB
Groff
|
.\" **************************************************************************
|
||
|
|
.\" * _ _ ____ _
|
||
|
|
.\" * 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
|
||
|
|
int main(void)
|
||
|
|
{
|
||
|
|
CURLUcode rc;
|
||
|
|
CURLU *url = curl_url();
|
||
|
|
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
|
||
|
|
if(!rc) {
|
||
|
|
/* 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)
|