curl_url_get(3)

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

NAME

6       curl_url_get - extract a part from a URL
7

SYNOPSIS

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

DESCRIPTION

17       Given  the  url handle of an already parsed URL, this function lets the
18       user extract individual pieces from it.
19
20       The what argument should be the particular part to  extract  (see  list
21       below) and part points to a 'char *' to get updated to point to a newly
22       allocated string with the contents.
23
24       The flags argument is a bitmask with individual features.
25
26       The returned part pointer must be freed with curl_free(3) after use.
27

FLAGS

29       The flags argument is zero, one or more bits set in a bitmask.
30
31       CURLU_DEFAULT_PORT
32              If the  handle  has  no  port  stored,  this  option  will  make
33              curl_url_get(3) return the default port for the used scheme.
34
35       CURLU_DEFAULT_SCHEME
36              If  the  handle  has  no  scheme  stored,  this option will make
37              curl_url_get(3) return the default scheme instead of error.
38
39       CURLU_NO_DEFAULT_PORT
40              Instructs curl_url_get(3) to not return  a  port  number  if  it
41              matches the default port for the scheme.
42
43       CURLU_URLDECODE
44              Asks curl_url_get(3) to URL decode the contents before returning
45              it. It will not attempt to decode the scheme, the port number or
46              the full URL.  ´ The query component will also get plus-to-space
47              conversion as a bonus when this bit is set.
48
49              Note that this URL decoding is charset unaware and you will  get
50              a  zero  terminated string back with data that could be intended
51              for a particular encoding.
52
53              If there's any byte values lower than 32 in the decoded  string,
54              the get operation will return an error instead.
55
56       CURLU_URLENCODE
57              If  set, will make curl_url_get(3) URL encode the host name part
58              when a full URL is retrieved. If not set (default), libcurl  re‐
59              turns  the  URL with the host name "raw" to support IDN names to
60              appear as-is. IDN host names are typically using non-ASCII bytes
61              that otherwise will be percent-encoded.
62
63              Note  that  even when not asking for URL encoding, the '%' (byte
64              37) will be URL encoded to  make  sure  the  host  name  remains
65              valid.
66

PARTS

68       CURLUPART_URL
69              When asked to return the full URL, curl_url_get(3) will return a
70              normalized and possibly cleaned up version of  what  was  previ‐
71              ously parsed.
72
73       CURLUPART_SCHEME
74              Scheme cannot be URL decoded on get.
75
76       CURLUPART_USER
77
78       CURLUPART_PASSWORD
79
80       CURLUPART_OPTIONS
81
82       CURLUPART_HOST
83              The host name. If it is an IPv6 numeric address, the zoneid will
84              not  be  part  of  it  but  is  provided  separately  in  CURLU‐
85              PART_ZONEID. IPv6 numerical addresses are returned within brack‐
86              ets ([]).
87
88       CURLUPART_ZONEID
89              If the host name is a numeric IPv6  address,  this  field  might
90              also be set.
91
92       CURLUPART_PORT
93              Port cannot be URL decoded on get.
94
95       CURLUPART_PATH
96              part will be '/' even if no path is supplied in the URL.
97
98       CURLUPART_QUERY
99              The  initial  question  mark  that  denotes the beginning of the
100              query part is a delimiter only.  It is not  part  of  the  query
101              contents.
102
103
104              A  not-present  query will lead part to be set to NULL.  A zero-
105              length query will lead part to be set to a zero-length string.
106
107              The query part will also get  pluses  converted  to  space  when
108              asked to URL decode on get with the CURLU_URLDECODE bit.
109
110       CURLUPART_FRAGMENT
111

EXAMPLE

113         CURLUcode rc;
114         CURLU *url = curl_url();
115         rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
116         if(!rc) {
117           char *scheme;
118           rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0);
119           if(!rc) {
120             printf("the scheme is %s\n", scheme);
121             curl_free(scheme);
122           }
123           curl_url_cleanup(url);
124         }
125

AVAILABILITY

127       Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
128

RETURN VALUE

130       Returns  a  CURLUcode error value, which is CURLUE_OK (0) if everything
131       went fine. See the libcurl-errors(3) man page for the  full  list  with
132       descriptions.
133
134       If this function returns an error, no URL part is returned.
135