path: root/man/tip/nng_opts_parse.3supp.html

---
version: tip
layout: manpage_v2
title: nng_opts_parse(3supp)
---
<h1>nng_opts_parse(3supp)</h1>
<div class="sect1">
<h2 id="_name">NAME</h2>
<div class="sectionbody">
<div class="paragraph">
<p>nng_opts_parse - parse command line options</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-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nng/supplemental/util/options.h&gt;</span>

<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_optspec</span><span class="tok-w"> </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">o_name</span><span class="tok-p">;</span><span class="tok-w">  </span><span class="tok-c1">// Long style name (may be NULL for short only)</span>
<span class="tok-w">    </span><span class="tok-kt">int</span><span class="tok-w">         </span><span class="tok-n">o_short</span><span class="tok-p">;</span><span class="tok-w"> </span><span class="tok-c1">// Short option (no clustering!)</span>
<span class="tok-w">    </span><span class="tok-kt">int</span><span class="tok-w">         </span><span class="tok-n">o_val</span><span class="tok-p">;</span><span class="tok-w">   </span><span class="tok-c1">// Value stored on a good parse (&gt;0)</span>
<span class="tok-w">    </span><span class="tok-kt">bool</span><span class="tok-w">        </span><span class="tok-n">o_arg</span><span class="tok-p">;</span><span class="tok-w">   </span><span class="tok-c1">// Option takes an argument if true</span>
<span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-n">nng_optspec</span><span class="tok-p">;</span>

<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_opts_parse</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">argc</span><span class="tok-p">,</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-k">const</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">argv</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-n">nng_optspec</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">spec</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</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">arg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">idx</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_opts_parse()</code> is function is a supplemental function intended to
facilitate parsing command line arguments.
This function exists largely to stand in for <code>getopt()</code> from POSIX
systems, but it is available everywhere that <em>NNG</em> is, and it includes
some capabilities missing from <code>getopt()</code>.</p>
</div>
<div class="paragraph">
<p>The function parses arguments from <code>main()</code> (using <em>argc</em> and <em>argv</em>),
starting at the index referenced by <em>idx</em>.
(New invocations typically set the value pointed to by <em>idx</em> to 1.)</p>
</div>
<div class="paragraph">
<p>Options are parsed as specified by <em>spec</em> (see <a href="#_option_specification">Option Specification</a>.)
The value of the parsed option will be stored at the address indicated by
<em>val</em>, and the value of <em>idx</em> will be incremented to reflect the next
option to parse.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
For using this to parse command-line like strings that do not include
the command name itself, set the value referenced by <em>idx</em> to zero
instead of one.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>If the option had an argument, a pointer to that is returned at the address
referenced by <em>arg</em>.</p>
</div>
<div class="paragraph">
<p>This function should be called repeatedly, until it returns either -1
(indicating the end of options is reached) or a non-zero error code is
returned.</p>
</div>
<div class="sect2">
<h3 id="_option_specification">Option Specification</h3>
<div class="paragraph">
<p>The calling program must first create an array of <code>nng_optspec</code> structures
describing the options to be supported.
This structure has the following members:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>o_name</code></dt>
<dd>
<p>The long style name for the option, such as "verbose".
This will be parsed on the command line when it is prefixed with two dashes.
It may be <code>NULL</code> if only a short option is to be supported.</p>
</dd>
<dt class="hdlist1"><code>o_short</code></dt>
<dd>
<p>This is a single letter (at present only ASCII letters are supported).
These options appear as just a single letter, and are prefixed with a single dash on the command line.
The use of a slash in lieu of the dash is <em>not</em> supported, in order to avoid confusion with path name arguments.
This value may be set to 0 if no short option is needed.</p>
</dd>
<dt class="hdlist1"><code>o_val</code></dt>
<dd>
<p>This is a numeric value that is unique to this option.
This value is assigned by the application program, and must be non-zero
for a valid option.
If this is zero, then it indicates the end of the specifications, and the
rest of this structure is ignored.
The value will be returned to the caller in <em>val</em> by <code>nng_opts_parse()</code> when
this option is parsed from the command line.</p>
</dd>
<dt class="hdlist1"><code>o_arg</code></dt>
<dd>
<p>This value should be set to <code>true</code> if the option should take an argument.</p>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="_long_options">Long Options</h3>
<div class="paragraph">
<p>Long options are parsed from the <em>argv</em> array, and are indicated when
the element being scanned starts with two dashes.
For example, the "verbose" option would be specified as <code>--verbose</code> on
the command line.
If a long option takes an argument, it can either immediately follow
the option as the next element in <em>argv</em>, or it can be appended to
the option, separated from the option by an equals sign (<code>=</code>) or a
colon (<code>:</code>).</p>
</div>
</div>
<div class="sect2">
<h3 id="_short_options">Short Options</h3>
<div class="paragraph">
<p>Short options appear by themselves in an <em>argv</em> element, prefixed by a
dash (<code>-</code>).
If the short option takes an argument, it can either be appended in the
same element of <em>argv</em>, or may appear in the next <em>argv</em> element.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Option clustering, where multiple options can be crammed together in
a single <em>argv</em> element, is not supported by this function (yet).
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_prefix_matching">Prefix Matching</h3>
<div class="paragraph">
<p>When using long options, the parser will match if it is equal to a prefix
of the <code>o_name</code> member of a option specification, provided that it do so
unambiguously (meaning it must not match any other option specification.)</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_example">EXAMPLE</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The following program fragment demonstrates this function.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-w">    </span><span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-p">{</span><span class="tok-w"> </span><span class="tok-n">OPT_LOGFILE</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">OPT_VERBOSE</span><span class="tok-w"> </span><span class="tok-p">};</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">logfile</span><span class="tok-p">;</span><span class="tok-w"> </span><span class="tok-c1">// options to be set</span>
<span class="tok-w">    </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-n">verbose</span><span class="tok-p">;</span>

<span class="tok-w">    </span><span class="tok-k">static</span><span class="tok-w"> </span><span class="tok-n">nng_optspec</span><span class="tok-w"> </span><span class="tok-n">specs</span><span class="tok-p">[]</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-p">{</span>
<span class="tok-w">        </span><span class="tok-p">{</span>
<span class="tok-w">            </span><span class="tok-p">.</span><span class="tok-n">o_name</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s">&quot;logfile&quot;</span><span class="tok-p">,</span>
<span class="tok-w">            </span><span class="tok-p">.</span><span class="tok-n">o_short</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-sc">&#39;D&#39;</span><span class="tok-p">,</span>
<span class="tok-w">            </span><span class="tok-p">.</span><span class="tok-n">o_val</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">OPT_LOGFILE</span><span class="tok-p">,</span>
<span class="tok-w">            </span><span class="tok-p">.</span><span class="tok-n">o_arg</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-nb">true</span><span class="tok-p">,</span>
<span class="tok-w">        </span><span class="tok-p">},</span><span class="tok-w"> </span><span class="tok-p">{</span>
<span class="tok-w">            </span><span class="tok-p">.</span><span class="tok-n">o_name</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s">&quot;verbose&quot;</span><span class="tok-p">,</span>
<span class="tok-w">            </span><span class="tok-p">.</span><span class="tok-n">o_short</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-sc">&#39;V&#39;</span><span class="tok-p">,</span>
<span class="tok-w">            </span><span class="tok-p">.</span><span class="tok-n">o_val</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">OPT_VERBOSE</span><span class="tok-p">,</span>
<span class="tok-w">            </span><span class="tok-p">.</span><span class="tok-n">o_arg</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-nb">false</span><span class="tok-p">,</span>
<span class="tok-w">        </span><span class="tok-p">},</span><span class="tok-w"> </span><span class="tok-p">{</span>
<span class="tok-w">            </span><span class="tok-p">.</span><span class="tok-n">o_val</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">0</span><span class="tok-p">;</span><span class="tok-w"> </span><span class="tok-c1">// Terminate array</span>
<span class="tok-w">        </span><span class="tok-p">}</span>
<span class="tok-w">    </span><span class="tok-p">};</span>

<span class="tok-w">    </span><span class="tok-k">for</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">idx</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">1</span><span class="tok-p">;;)</span><span class="tok-w"> </span><span class="tok-p">{</span>
<span class="tok-w">        </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">rv</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">opt</span><span class="tok-p">;</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">arg</span><span class="tok-p">;</span>
<span class="tok-w">        </span><span class="tok-n">rv</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">nng_opts_parse</span><span class="tok-p">(</span><span class="tok-n">argc</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">argv</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">specs</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-o">&amp;</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-o">&amp;</span><span class="tok-n">arg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-o">&amp;</span><span class="tok-n">idx</span><span class="tok-p">);</span>
<span class="tok-w">        </span><span class="tok-k">if</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-n">rv</span><span class="tok-w"> </span><span class="tok-o">!=</span><span class="tok-w"> </span><span class="tok-mi">0</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-p">{</span>
<span class="tok-w">            </span><span class="tok-k">break</span><span class="tok-p">;</span>
<span class="tok-w">        </span><span class="tok-p">}</span>
<span class="tok-w">        </span><span class="tok-k">switch</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-n">opt</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-p">{</span>
<span class="tok-w">        </span><span class="tok-k">case</span><span class="tok-w"> </span><span class="tok-no">OPT_LOGFILE</span><span class="tok-p">:</span>
<span class="tok-w">            </span><span class="tok-n">logfile</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">arg</span><span class="tok-p">;</span>
<span class="tok-w">            </span><span class="tok-k">break</span><span class="tok-p">;</span>
<span class="tok-w">        </span><span class="tok-k">case</span><span class="tok-w"> </span><span class="tok-no">OPT_VERBOSE</span><span class="tok-p">:</span>
<span class="tok-w">            </span><span class="tok-n">verbose</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-nb">true</span><span class="tok-p">;</span>
<span class="tok-w">            </span><span class="tok-k">break</span><span class="tok-p">;</span>
<span class="tok-w">        </span><span class="tok-p">}</span>
<span class="tok-w">    </span><span class="tok-p">}</span>
<span class="tok-w">    </span><span class="tok-k">if</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-n">rv</span><span class="tok-w"> </span><span class="tok-o">!=</span><span class="tok-w"> </span><span class="tok-mi">-1</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-p">{</span>
<span class="tok-w">        </span><span class="tok-n">printf</span><span class="tok-p">(</span><span class="tok-s">&quot;Options error: %s</span><span class="tok-se">\n</span><span class="tok-s">&quot;</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_strerror</span><span class="tok-p">(</span><span class="tok-n">rv</span><span class="tok-p">));</span>
<span class="tok-w">        </span><span class="tok-n">exit</span><span class="tok-p">(</span><span class="tok-mi">1</span><span class="tok-p">);</span>
<span class="tok-w">    </span><span class="tok-p">}</span></code></pre>
</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 if an option parsed correctly, -1 if
no more options are available to be parsed, or an error number 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_EAMBIGUOUS</code>
</td>
<td class="hdlist2">
<p>Parsed option matches more than one specification.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ENOARG</code>
</td>
<td class="hdlist2">
<p>Option requires an argument, but one is not present.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_EINVAL</code>
</td>
<td class="hdlist2">
<p>An invalid (unknown) argument is present.</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_strerror.3.html">nng_strerror(3)</a>,
<a href="nng.7.html">nng(7)</a></p>
</div>
</div>
</div>