diff options
author | Elliott Hughes <enh@google.com> | 2018-12-12 14:22:48 -0800 |
---|---|---|
committer | Tao Bao <tbao@google.com> | 2018-12-12 17:16:20 -0800 |
commit | a93fb051349a5907b547a8f41c23a4b45bc82c0e (patch) | |
tree | 15ffc0718b7d289dc407c0d3851234b7f71286b0 /docs/libcurl/curl_url_set.3 | |
parent | 849332cb73701636b19b97f3d82e8e9fa0d51a30 (diff) | |
download | external_curl-a93fb051349a5907b547a8f41c23a4b45bc82c0e.tar.gz external_curl-a93fb051349a5907b547a8f41c23a4b45bc82c0e.tar.bz2 external_curl-a93fb051349a5907b547a8f41c23a4b45bc82c0e.zip |
Update to curl 7.62.0 - October 31 2018.
Bug: N/A
Test: builds, boots, `vendor/google/tools/fake-ota on streaming` works
Change-Id: If5e3aa0ced1b9d13cc4f2217f381ab9df8d16dcc
Diffstat (limited to 'docs/libcurl/curl_url_set.3')
-rw-r--r-- | docs/libcurl/curl_url_set.3 | 131 |
1 files changed, 131 insertions, 0 deletions
diff --git a/docs/libcurl/curl_url_set.3 b/docs/libcurl/curl_url_set.3 new file mode 100644 index 00000000..36addaa4 --- /dev/null +++ b/docs/libcurl/curl_url_set.3 @@ -0,0 +1,131 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2018, 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.haxx.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. +.\" * +.\" ************************************************************************** +.TH curl_url_set 3 "October 08, 2018" "libcurl 7.62.0" "libcurl Manual" + +.SH NAME +curl_url_set - set a URL part +.SH SYNOPSIS +.B #include <curl/curl.h> + +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 zero 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. + +Setting a part to a NULL pointer will effectively remove that part's contents +from the CURLU handle. + +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 zero 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. +.IP CURLUPART_USER +.IP CURLUPART_PASSWORD +.IP CURLUPART_OPTIONS +.IP CURLUPART_HOST +The host name can use IDNA. The string must then be encoded as your locale +says or UTF-8 (when winidn is used). +.IP CURLUPART_PORT +Port cannot be URL encoded on set. +.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 CURLU_URLENCODE bit. + +If used in with \fICURLU_APPENDQUERY\fP, the provided part will be appended on +the end of the existing query - and if the previous part didn't end with an +ampersand (&), an ampersand will be inserted before the new appended part. + +When \fICURLU_APPENDQUERY\fP is used together with \fICURLU_URLENCODE\fP, +the '=' symbols will not be URL encoded. + +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_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. +.SH RETURN VALUE +Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went +fine. + +If this function returns an error, no URL part is returned. +.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 curl 7.62.0 +.SH "SEE ALSO" +.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_get "(3), " +.BR curl_url_dup "(3), " |