xref: /curl/docs/libcurl/curl_url.md (revision e3fe0200) 
1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_url
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_CURLU (3)
9  - curl_url_cleanup (3)
10  - curl_url_dup (3)
11  - curl_url_get (3)
12  - curl_url_set (3)
13  - curl_url_strerror (3)
14Protocol:
15  - All
16---
17
18# NAME
19
20curl_url - returns a new URL handle
21
22# SYNOPSIS
23
24~~~c
25#include <curl/curl.h>
26
27CURLU *curl_url();
28~~~
29
30# DESCRIPTION
31
32This function allocates a URL object and returns a *CURLU* handle for it,
33to be used as input to all other URL API functions.
34
35This is a handle to a URL object that holds or can hold URL components for a
36single URL. When the object is first created, there is of course no components
37stored. They are then set in the object with the curl_url_set(3)
38function.
39
40# EXAMPLE
41
42~~~c
43int main(void)
44{
45  CURLUcode rc;
46  CURLU *url = curl_url();
47  rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
48  if(!rc) {
49    char *scheme;
50    rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0);
51    if(!rc) {
52      printf("the scheme is %s\n", scheme);
53      curl_free(scheme);
54    }
55    curl_url_cleanup(url);
56  }
57}
58~~~
59
60# AVAILABILITY
61
62Added in 7.62.0
63
64# RETURN VALUE
65
66Returns a **CURLU *** if successful, or NULL if out of memory.
67