diff options
Diffstat (limited to 'docs/libcurl/gnurl_url_set.3')
| -rw-r--r-- | docs/libcurl/gnurl_url_set.3 | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/docs/libcurl/gnurl_url_set.3 b/docs/libcurl/gnurl_url_set.3 new file mode 100644 index 000000000..cbeff1b2c --- /dev/null +++ b/docs/libcurl/gnurl_url_set.3 @@ -0,0 +1,135 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2019, 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 gnurl_url_set 3 "6 Aug 2018" "libcurl" "libgnurl Manual" +.SH NAME +curl_url_set - set a URL part +.SH SYNOPSIS +.B #include <gnurl/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_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 CURLU_URLENCODE bit. + +If used together with the \fICURLU_APPENDQUERY\fP bit, 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 +first '=' symbol 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. CURLUPART_ZONEID was added in 7.65.0. +.SH "SEE ALSO" +.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_get "(3), " +.BR curl_url_dup "(3), " |