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_PORT
58              Port cannot be URL encoded on set.
59
60       CURLUPART_PATH
61              If  a  path  is  set in the URL without a leading slash, a slash
62              will be inserted automatically when this URL is  read  from  the
63              handle.
64
65       CURLUPART_QUERY
66              The  query  part  will  also get spaces converted to pluses when
67              asked to URL encode on set with the CURLU_URLENCODE bit.
68
69              If used together with the CURLU_APPENDQUERY  bit,  the  provided
70              part  will be appended on the end of the existing query - and if
71              the previous part didn't end with an ampersand (&), an ampersand
72              will be inserted before the new appended part.
73
74              When  CURLU_APPENDQUERY  is  used together with CURLU_URLENCODE,
75              the first '=' symbol will not be URL encoded.
76
77              The question mark in the URL is not part  of  the  actual  query
78              contents.
79
80       CURLUPART_FRAGMENT
81              The hash sign in the URL is not part of the actual fragment con‐
82              tents.
83

FLAGS

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

RETURN VALUE

118       Returns a CURLUcode error value, which is CURLUE_OK (0)  if  everything
119       went fine.
120
121       If this function returns an error, no URL part is returned.
122

EXAMPLE

124         CURLUcode rc;
125         CURLU *url = curl_url();
126         rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
127         if(!rc) {
128           char *scheme;
129           /* change it to an FTP URL */
130           rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
131         }
132         curl_url_cleanup(url);
133

AVAILABILITY

135       Added in curl 7.62.0
136