---
name: "nng_url_parse"
section: "3"
platform: "linux"
package: "libnng-dev"
version: "1.10.1-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/nng_url_parse"
---

# nng\_url\_parse(3)

create URL structure from a string

## NAME

nng\_url\_parse - create URL structure from a string

## SYNOPSIS

```
#include <nng/nng.h>
int nng_url_parse(nng_url **urlp, const char *str);
```

## DESCRIPTION

The `nng_url_parse()` function parses the string *str* containing an *RFC 3986* \<https://tools.ietf.org/html/rfc3986\> compliant URL, and creates an `nng_url` structure containing the results. A pointer to the resulting structure is stored in *urlp*.

The structure may disposed of when no longer needed by calling `nng_url_free()`.

### URL Canonicalization

The `nng_url_parse()` function also canonicalizes the results, as follows:

 1\. The URL is parsed into the various components.

 2\. The `u_scheme`, `u_hostname`, `u_host`, and `u_port` members are converted to lower case.

 3\. Percent-encoded values for*unreserved characters* \<https://tools.ietf.org/html/rfc3986#section-2.3\> converted to their unencoded forms.

 4\. Additionally URL percent-encoded values for characters in the path and with numeric values larger than 127 (i.e. not ASCII) are decoded.

 5\. The resulting `u_path` is checked for invalid UTF-8 sequences, consisting of surrogate pairs, illegal byte sequences, or overlong encodings. If this check fails, then the entire URL is considered invalid, and the function returns `NNG_EINVAL`.

 6\. Path segments consisting of `.` and `..` are resolved as per *RFC 3986 6.2.2.3* \<https://tools.ietf.org/html/rfc3986#section-6.2.2.3\>.

 7\. Further, empty path segments are removed, meaning that duplicate slash (`/`) separators are removed from the path.

 8\. If a port was not specified, but the scheme defines a default port, then `u_port` will be filled in with the value of the default port.

**Tip**\

Only the `u_userinfo`, `u_query`, and `u_fragment` members will ever be `NULL`.  The other members will be filled in with either default values or the empty string if they cannot be determined from *str*.

## RETURN VALUES

This function returns 0 on success, and non-zero otherwise.

## ERRORS

`NNG_ENOMEM`

Insufficient free memory exists to allocate a message.

`NNG_EINVAL`

An invalid URL was supplied.

## SEE ALSO

[nng\_url\_clone(3)](/nng_url_clone/3.md), [nng\_url\_free(3)](/nng_url_free/3.md), [nng\_strerror(3)](/nng_strerror/3.md), [nng\_url(5)](/nng_url/5.md), [nng(7)](/nng/7.md)