---
version: tip
layout: manpage_v2
title: nng_url_parse(3)
---
<h1>nng_url_parse(3)</h1>
<div class="sect1">
<h2 id="_name">NAME</h2>
<div class="sectionbody">
<div class="paragraph">
<p>nng_url_parse - create URL structure from a string</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_synopsis">SYNOPSIS</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nng/nng.h&gt;</span>

<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_url_parse</span><span class="tok-p">(</span><span class="tok-n">nng_url</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">urlp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">str</span><span class="tok-p">);</span></code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_description">DESCRIPTION</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>nng_url_parse()</code> function parses the string <em>str</em> containing an
<a href="https://tools.ietf.org/html/rfc3986">RFC 3986</a> compliant URL, and creates
an
<a href="nng_url.5.html"><code>nng_url</code></a> structure containing the results.
A pointer to the resulting structure is stored in <em>urlp</em>.</p>
</div>
<div class="paragraph">
<p>The structure may disposed of when no longer needed by calling
<a href="nng_url_free.3.html"><code>nng_url_free()</code></a>.</p>
</div>
<div class="sect2">
<h3 id="_url_canonicalization">URL Canonicalization</h3>
<div class="paragraph">
<p>The <code>nng_url_parse()</code> function also canonicalizes the results, as
follows:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>The URL is parsed into the various components.</p>
</li>
<li>
<p>The <code>u_scheme</code>, <code>u_hostname</code>, <code>u_host</code>, and <code>u_port</code> members are
converted to lower case.</p>
</li>
<li>
<p>Percent-encoded values for
<a href="https://tools.ietf.org/html/rfc3986#section-2.3">unreserved characters</a>
converted to their unencoded forms.</p>
</li>
<li>
<p>Additionally URL percent-encoded values for characters in the path
and with numeric values larger than 127 (i.e. not ASCII) are decoded.</p>
</li>
<li>
<p>The resulting <code>u_path</code> 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 <code>NNG_EINVAL</code>.</p>
</li>
<li>
<p>Path segments consisting of <code>.</code> and <code>..</code> are resolved as per
<a href="https://tools.ietf.org/html/rfc3986#section-6.2.2.3">RFC 3986 6.2.2.3</a>.</p>
</li>
<li>
<p>Further, empty path segments are removed, meaning that duplicate
slash (<code>/</code>) separators are removed from the path.</p>
</li>
<li>
<p>If a port was not specified, but the scheme defines a default
port, then <code>u_port</code> will be filled in with the value of the default port.</p>
</li>
</ol>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Only the <code>u_userinfo</code>, <code>u_query</code>, and <code>u_fragment</code> members will ever be
     <code>NULL</code>.  The other members will be filled in with either default values
     or the empty string if they cannot be determined from <em>str</em>.
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_return_values">RETURN VALUES</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This function returns 0 on success, and non-zero otherwise.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_errors">ERRORS</h2>
<div class="sectionbody">
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
<code>NNG_ENOMEM</code>
</td>
<td class="hdlist2">
<p>Insufficient free memory exists to allocate a message.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_EINVAL</code>
</td>
<td class="hdlist2">
<p>An invalid URL was supplied.</p>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_see_also">SEE ALSO</h2>
<div class="sectionbody">
<div class="paragraph text-left">
<p><a href="nng_url_clone.3.html">nng_url_clone(3)</a>,
<a href="nng_url_free.3.html">nng_url_free(3)</a>,
<a href="nng_strerror.3.html">nng_strerror(3)</a>,
<a href="nng_url.5.html">nng_url(5)</a>,
<a href="nng.7.html">nng(7)</a></p>
</div>
</div>
</div>