nng_url_parse(3)

# nng_url_parse(3) Manual Page

## 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 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 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.

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.

| 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_free(3), nng_strerror(3), nng_url(5), nng(7)