---
name: "curl_url"
section: "3"
platform: "linux"
package: "curl"
version: "8.23.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/curl_url"
---

# curl\_url(3)

create a URL handle

## NAME

curl\_url - create a URL handle

## SYNOPSIS

```
#include <curl/curl.h>
CURLU *curl_url();
```

## DESCRIPTION

This function allocates a URL object and returns a *CURLU* handle for it, to be used as input to all other URL API functions.

This is a handle to a URL object that holds or can hold URL components for a single URL. When the object is first created, there is of course no components stored. They are then set in the object with the *[curl\_url\_set(3)](/curl_url_set/3.md)* function.

The object must be destroyed with a call to *[curl\_url\_cleanup(3)](/curl_url_cleanup/3.md)* when no longer needed.

## PROTOCOLS

This functionality affects all supported protocols

## EXAMPLE

```
int main(void)
{
  CURLUcode rc;
  CURLU *url = curl_url();
  rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
  if(!rc) {
    char *scheme;
    rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0);
    if(!rc) {
      printf("the scheme is %s\n", scheme);
      curl_free(scheme);
    }
    curl_url_cleanup(url);
  }
}
```

## AVAILABILITY

Added in curl 7.62.0

## RETURN VALUE

Returns a **CURLU** \* if successful, or NULL if out of memory.

## SEE ALSO

[**CURLOPT\_CURLU**(3)](/CURLOPT_CURLU/3.md), [**curl\_url\_cleanup**(3)](/curl_url_cleanup/3.md), [**curl\_url\_dup**(3)](/curl_url_dup/3.md), [**curl\_url\_get**(3)](/curl_url_get/3.md), [**curl\_url\_set**(3)](/curl_url_set/3.md), [**curl\_url\_strerror**(3)](/curl_url_strerror/3.md)