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 null-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 null-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. If it is IDNA the string must then be encoded  as
55              your  locale  says  or  UTF-8  (when WinIDN is used). If it is a
56              bracketed IPv6 numeric address it may contain a zone id (or  you
57              can use CURLUPART_ZONEID).
58
59       CURLUPART_ZONEID
60              If  the host name is a numeric IPv6 address, this field can also
61              be set.
62
63       CURLUPART_PORT
64              Port cannot be URL encoded on set. The given port number is pro‐
65              vided  as  a string and the decimal number must be between 1 and
66              65535. Anything else will return an error.
67
68       CURLUPART_PATH
69              If a path is set in the URL without a  leading  slash,  a  slash
70              will  be  inserted  automatically when this URL is read from the
71              handle.
72
73       CURLUPART_QUERY
74              The query part will also get spaces  converted  to  pluses  when
75              asked to URL encode on set with the CURLU_URLENCODE bit.
76
77              If  used  together  with the CURLU_APPENDQUERY bit, the provided
78              part will be appended on the end of the existing query - and  if
79              the previous part didn't end with an ampersand (&), an ampersand
80              will be inserted before the new appended part.
81
82              When CURLU_APPENDQUERY is used  together  with  CURLU_URLENCODE,
83              the first '=' symbol will not be URL encoded.
84
85              The  question  mark  in  the URL is not part of the actual query
86              contents.
87
88       CURLUPART_FRAGMENT
89              The hash sign in the URL is not part of the actual fragment con‐
90              tents.
91

FLAGS

93       The flags argument is zero, one or more bits set in a bitmask.
94
95       CURLU_NON_SUPPORT_SCHEME
96              If set, allows curl_url_set(3) to set a non-supported scheme.
97
98       CURLU_URLENCODE
99              When  set, curl_url_set(3) URL encodes the part on entry, except
100              for scheme, port and URL.
101
102              When setting the path component with URL encoding  enabled,  the
103              slash character will be skipped.
104
105              The query part gets space-to-plus conversion before the URL con‐
106              version.
107
108              This URL encoding is charset unaware and will convert the  input
109              on a byte-by-byte manner.
110
111       CURLU_DEFAULT_SCHEME
112              If  set,  will  make  libcurl  allow the URL to be set without a
113              scheme and then sets that to the default  scheme:  HTTPS.  Over‐
114              rides the CURLU_GUESS_SCHEME option if both are set.
115
116       CURLU_GUESS_SCHEME
117              If  set,  will  make  libcurl  allow the URL to be set without a
118              scheme and it instead "guesses" which scheme that  was  intended
119              based  on  the  host  name.   If  the  outermost sub-domain name
120              matches DICT, FTP, IMAP, LDAP, POP3 or  SMTP  then  that  scheme
121              will  be  used,  otherwise  it  picks  HTTP.  Conflicts with the
122              CURLU_DEFAULT_SCHEME option which takes precedence if  both  are
123              set.
124
125       CURLU_NO_AUTHORITY
126              If  set,  skips  authority  checks.  The  RFC  allows individual
127              schemes to omit the host part (normally the only mandatory  part
128              of  the authority), but libcurl cannot know whether this is per‐
129              mitted for custom schemes. Specifying  the  flag  permits  empty
130              authority sections, similar to how file scheme is handled.
131
132

RETURN VALUE

134       Returns  a  CURLUcode error value, which is CURLUE_OK (0) if everything
135       went fine.
136
137       A URL string passed on to curl_url_set(3) for the  CURLUPART_URL  part,
138       must  be  shorter  than  8000000 bytes otherwise it returns CURLUE_MAL‐
139       FORMED_INPUT (added in 7.65.0).
140
141       If this function returns an error, no URL part is returned.
142

EXAMPLE

144         CURLUcode rc;
145         CURLU *url = curl_url();
146         rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
147         if(!rc) {
148           char *scheme;
149           /* change it to an FTP URL */
150           rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
151         }
152         curl_url_cleanup(url);
153

AVAILABILITY

155       Added in curl 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
156