diff options
Diffstat (limited to 'docs/libcurl/curl_url_set.3')
| -rw-r--r-- | docs/libcurl/curl_url_set.3 | 209 |
1 files changed, 0 insertions, 209 deletions
diff --git a/docs/libcurl/curl_url_set.3 b/docs/libcurl/curl_url_set.3 deleted file mode 100644 index 912694f7b..000000000 --- a/docs/libcurl/curl_url_set.3 +++ /dev/null @@ -1,209 +0,0 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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) |