aboutsummaryrefslogtreecommitdiff
path: root/docs/libcurl/curl_url_set.3
diff options
context:
space:
mode:
Diffstat (limited to 'docs/libcurl/curl_url_set.3')
-rw-r--r--docs/libcurl/curl_url_set.3120
1 files changed, 120 insertions, 0 deletions
diff --git a/docs/libcurl/curl_url_set.3 b/docs/libcurl/curl_url_set.3
new file mode 100644
index 000000000..75fc0d963
--- /dev/null
+++ b/docs/libcurl/curl_url_set.3
@@ -0,0 +1,120 @@
+.\" **************************************************************************
+.\" * _ _ ____ _
+.\" * 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 "6 Aug 2018" "libcurl" "libcurl Manual"
+.SH NAME
+curl_url_set - set a part from a URL
+.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 \fCURLU_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.
+.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.63.0
+.SH "SEE ALSO"
+.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_get "(3), "
+.BR curl_url_dup "(3), "