curl_url_set(3)

1curl_url_set(3)                 libcurl Manual                 curl_url_set(3)
2
3
4

NAME

6       curl_url_set - set a URL part
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       CURLUcode curl_url_set(CURLU *url,
12                              CURLUPart part,
13                              const char *content,
14                              unsigned int flags)
15

DESCRIPTION

17       Given  the  url handle of an already parsed URL, this function lets the
18       user set/update individual pieces of it.
19
20       The part argument should identify the particular  URL  part  (see  list
21       below)  to  set  or  change, with content pointing to a zero terminated
22       string with the new contents for that URL part. The contents should  be
23       in the form and encoding they'd use in a URL: URL encoded.
24
25       Setting  a  part  to a NULL pointer will effectively remove that part's
26       contents from the CURLU handle.
27
28       The flags argument is a bitmask with independent features.
29

PARTS

31       CURLUPART_URL
32              Allows the full URL of the handle to be replaced. If the  handle
33              already  is populated with a URL, the new URL can be relative to
34              the previous.
35
36              When successfully setting a new URL, relative or  absolute,  the
37              handle  contents  will  be  replaced with the information of the
38              newly set URL.
39
40              Pass a pointer to a zero terminated string to the url parameter.
41              The  string  must point to a correctly formatted "RFC 3986+" URL
42              or be a NULL pointer.
43
44       CURLUPART_SCHEME
45              Scheme cannot be URL decoded on set.
46
47       CURLUPART_USER
48
49       CURLUPART_PASSWORD
50
51       CURLUPART_OPTIONS
52
53       CURLUPART_HOST
54              The host name can use IDNA. The string must then be  encoded  as
55              your locale says or UTF-8 (when winidn is used).
56
57       CURLUPART_ZONEID
58              If  the host name is a numeric IPv6 address, this field can also
59              be set.
60
61       CURLUPART_PORT
62              Port cannot be URL encoded on set. The given port number is pro‐
63              vided  as  a string and the decimal number must be between 1 and
64              65535. Anything else will return an error.
65
66       CURLUPART_PATH
67              If a path is set in the URL without a  leading  slash,  a  slash
68              will  be  inserted  automatically when this URL is read from the
69              handle.
70
71       CURLUPART_QUERY
72              The query part will also get spaces  converted  to  pluses  when
73              asked to URL encode on set with the CURLU_URLENCODE bit.
74
75              If  used  together  with the CURLU_APPENDQUERY bit, the provided
76              part will be appended on the end of the existing query - and  if
77              the previous part didn't end with an ampersand (&), an ampersand
78              will be inserted before the new appended part.
79
80              When CURLU_APPENDQUERY is used  together  with  CURLU_URLENCODE,
81              the first '=' symbol will not be URL encoded.
82
83              The  question  mark  in  the URL is not part of the actual query
84              contents.
85
86       CURLUPART_FRAGMENT
87              The hash sign in the URL is not part of the actual fragment con‐
88              tents.
89

FLAGS

91       The flags argument is zero, one or more bits set in a bitmask.
92
93       CURLU_NON_SUPPORT_SCHEME
94              If set, allows curl_url_set(3) to set a non-supported scheme.
95
96       CURLU_URLENCODE
97              When  set, curl_url_set(3) URL encodes the part on entry, except
98              for scheme, port and URL.
99
100              When setting the path component with URL encoding  enabled,  the
101              slash character will be skipped.
102
103              The query part gets space-to-plus conversion before the URL con‐
104              version.
105
106              This URL encoding is charset unaware and will convert the  input
107              on a byte-by-byte manner.
108
109       CURLU_DEFAULT_SCHEME
110              If  set,  will  make  libcurl  allow the URL to be set without a
111              scheme and then sets that to the default  scheme:  HTTPS.  Over‐
112              rides the CURLU_GUESS_SCHEME option if both are set.
113
114       CURLU_GUESS_SCHEME
115              If  set,  will  make  libcurl  allow the URL to be set without a
116              scheme and it instead "guesses" which scheme that  was  intended
117              based  on  the  host  name.   If  the  outermost sub-domain name
118              matches DICT, FTP, IMAP, LDAP, POP3 or  SMTP  then  that  scheme
119              will  be  used,  otherwise  it  picks  HTTP.  Conflicts with the
120              CURLU_DEFAULT_SCHEME option which takes precedence if  both  are
121              set.
122

RETURN VALUE

124       Returns  a  CURLUcode error value, which is CURLUE_OK (0) if everything
125       went fine.
126
127       If this function returns an error, no URL part is returned.
128

EXAMPLE

130         CURLUcode rc;
131         CURLU *url = curl_url();
132         rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
133         if(!rc) {
134           char *scheme;
135           /* change it to an FTP URL */
136           rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
137         }
138         curl_url_cleanup(url);
139

AVAILABILITY

141       Added in curl 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
142