Debian Codegraph @

deps/curl/docs/libcurl/curl_url_set.3

raw
1 .\" **************************************************************************
2 .\" * _ _ ____ _
3 .\" * Project ___| | | | _ \| |
4 .\" * / __| | | | |_) | |
5 .\" * | (__| |_| | _ <| |___
6 .\" * \___|\___/|_| \_\_____|
7 .\" *
8 .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al.
9 .\" *
10 .\" * This software is licensed as described in the file COPYING, which
11 .\" * you should have received as part of this distribution. The terms
12 .\" * are also available at https://curl.haxx.se/docs/copyright.html.
13 .\" *
14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
15 .\" * copies of the Software, and permit persons to whom the Software is
16 .\" * furnished to do so, under the terms of the COPYING file.
17 .\" *
18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
19 .\" * KIND, either express or implied.
20 .\" *
21 .\" **************************************************************************
22 .TH curl_url_set 3 "6 Aug 2018" "libcurl" "libcurl Manual"
23 .SH NAME
24 curl_url_set - set a URL part
25 .SH SYNOPSIS
26 .B #include <curl/curl.h>
27
28 CURLUcode curl_url_set(CURLU *url,
29 CURLUPart part,
30 const char *content,
31 unsigned int flags)
32 .fi
33 .SH DESCRIPTION
34 Given the \fIurl\fP handle of an already parsed URL, this function lets the
35 user set/update individual pieces of it.
36
37 The \fIpart\fP argument should identify the particular URL part (see list
38 below) to set or change, with \fIcontent\fP pointing to a zero terminated
39 string with the new contents for that URL part. The contents should be in the
40 form and encoding they'd use in a URL: URL encoded.
41
42 Setting a part to a NULL pointer will effectively remove that part's contents
43 from the CURLU handle.
44
45 The \fIflags\fP argument is a bitmask with independent features.
46 .SH PARTS
47 .IP CURLUPART_URL
48 Allows the full URL of the handle to be replaced. If the handle already is
49 populated with a URL, the new URL can be relative to the previous.
50
51 When successfully setting a new URL, relative or absolute, the handle contents
52 will be replaced with the information of the newly set URL.
53
54 Pass a pointer to a zero terminated string to the \fIurl\fP parameter. The
55 string must point to a correctly formatted "RFC 3986+" URL or be a NULL
56 pointer.
57 .IP CURLUPART_SCHEME
58 Scheme cannot be URL decoded on set.
59 .IP CURLUPART_USER
60 .IP CURLUPART_PASSWORD
61 .IP CURLUPART_OPTIONS
62 .IP CURLUPART_HOST
63 The host name. If it is IDNA the string must then be encoded as your locale
64 says or UTF-8 (when WinIDN is used). If it is a bracketed IPv6 numeric address
65 it may contain a zone id (or you can use CURLUPART_ZONEID).
66 .IP CURLUPART_ZONEID
67 If the host name is a numeric IPv6 address, this field can also be set.
68 .IP CURLUPART_PORT
69 Port cannot be URL encoded on set. The given port number is provided as a
70 string and the decimal number must be between 1 and 65535. Anything else will
71 return an error.
72 .IP CURLUPART_PATH
73 If a path is set in the URL without a leading slash, a slash will be inserted
74 automatically when this URL is read from the handle.
75 .IP CURLUPART_QUERY
76 The query part will also get spaces converted to pluses when asked to URL
77 encode on set with the CURLU_URLENCODE bit.
78
79 If used together with the \fICURLU_APPENDQUERY\fP bit, the provided part will
80 be appended on the end of the existing query - and if the previous part didn't
81 end with an ampersand (&), an ampersand will be inserted before the new
82 appended part.
83
84 When \fICURLU_APPENDQUERY\fP is used together with \fICURLU_URLENCODE\fP, the
85 first '=' symbol will not be URL encoded.
86
87 The question mark in the URL is not part of the actual query contents.
88 .IP CURLUPART_FRAGMENT
89 The hash sign in the URL is not part of the actual fragment contents.
90 .SH FLAGS
91 The flags argument is zero, one or more bits set in a bitmask.
92 .IP CURLU_NON_SUPPORT_SCHEME
93 If set, allows \fIcurl_url_set(3)\fP to set a non-supported scheme.
94 .IP CURLU_URLENCODE
95 When set, \fIcurl_url_set(3)\fP URL encodes the part on entry, except for
96 scheme, port and URL.
97
98 When setting the path component with URL encoding enabled, the slash character
99 will be skipped.
100
101 The query part gets space-to-plus conversion before the URL conversion.
102
103 This URL encoding is charset unaware and will convert the input on a
104 byte-by-byte manner.
105 .IP CURLU_DEFAULT_SCHEME
106 If set, will make libcurl allow the URL to be set without a scheme and then
107 sets that to the default scheme: HTTPS. Overrides the \fICURLU_GUESS_SCHEME\fP
108 option if both are set.
109 .IP CURLU_GUESS_SCHEME
110 If set, will make libcurl allow the URL to be set without a scheme and it
111 instead "guesses" which scheme that was intended based on the host name. If
112 the outermost sub-domain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then
113 that scheme will be used, otherwise it picks HTTP. Conflicts with the
114 \fICURLU_DEFAULT_SCHEME\fP option which takes precedence if both are set.
115 .IP CURLU_NO_AUTHORITY
116 If set, skips authority checks. The RFC allows individual schemes to omit the
117 host part (normally the only mandatory part of the authority), but libcurl
118 cannot know whether this is permitted for custom schemes. Specifying the flag
119 permits empty authority sections, similar to how file scheme is handled.
120
121 .SH RETURN VALUE
122 Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
123 fine.
124
125 A URL string passed on to \fIcurl_url_set(3)\fP for the \fBCURLUPART_URL\fP
126 part, must be shorter than 8000000 bytes otherwise it returns
127 \fBCURLUE_MALFORMED_INPUT\fP (added in 7.65.0).
128
129 If this function returns an error, no URL part is returned.
130 .SH EXAMPLE
131 .nf
132 CURLUcode rc;
133 CURLU *url = curl_url();
134 rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
135 if(!rc) {
136 char *scheme;
137 /* change it to an FTP URL */
138 rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
139 }
140 curl_url_cleanup(url);
141 .fi
142 .SH AVAILABILITY
143 Added in curl 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
144 .SH "SEE ALSO"
145 .BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_get "(3), "
146 .BR curl_url_dup "(3), "