path: root/man/tip/nng_pipe_get.3.html

---
version: tip
layout: manpage_v2
title: nng_pipe_get(3)
---
<h1>nng_pipe_get(3)</h1>
<div class="sect1">
<h2 id="_name">NAME</h2>
<div class="sectionbody">
<div class="paragraph">
<p>nng_pipe_get - get pipe option</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_pipe_get</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</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">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</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">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valszp</span><span class="tok-p">);</span>

<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get_bool</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</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">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">bvalp</span><span class="tok-p">);</span>

<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get_int</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</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">opt</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">ivalp</span><span class="tok-p">);</span>

<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get_ms</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</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">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">durp</span><span class="tok-p">);</span>

<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</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">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">ptr</span><span class="tok-p">);</span>

<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get_addr</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</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">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">sap</span><span class="tok-p">);</span>

<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get_string</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</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">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">strp</span><span class="tok-p">);</span>

<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get_size</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</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">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">zp</span><span class="tok-p">);</span>

<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</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">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u64p</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_pipe_get()</code> functions are used to retrieve option values for
the <a href="nng_pipe.5.html">pipe</a> <em>p</em>.
The actual options that may be retrieved in this way
vary, and many are documented in <a href="nng_options.5.html">nng_options(5)</a>.
Additionally some transport-specific options and protocol-specific options are
documented with the transports and protocols themselves.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
All options on a pipe are read-only values.
Modification of options may be done before the pipe is created using
<a href="nng_listener_set.3.html"><code>nng_listener_set()</code></a> or
<a href="nng_dialer_get.3.html"><code>nng_dialer_set()</code></a>.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Any option that is set on a dialer or listener will normally be retrievable
from pipes created by that dialer or listener.</p>
</div>
<div class="sect2">
<h3 id="_forms">Forms</h3>
<div class="paragraph">
<p>In all of these forms, the option <em>opt</em> is retrieved from the pipe <em>p</em>.</p>
</div>
<div class="paragraph">
<p>The details of the type, size, and semantics of the option will depend
on the actual option, and will be documented with the option itself.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>nng_pipe_get()</code></dt>
<dd>
<p>This is untyped, and can be used to retrieve the value of any option.
A pointer to a buffer to receive the value in <em>val</em>, and the size of the
buffer shall be stored at the location referenced by <em>valszp</em>.<br>
<br>
When the function returns, the actual size of the data copied (or that
would have been copied if sufficient space were present) is stored at
the location referenced by <em>valszp</em>.
If the caller&#8217;s buffer is not large enough to hold the entire object,
then the copy is truncated.
Therefore the caller should check for truncation by verifying that the
size returned in <em>valszp</em> does not exceed the original buffer size.<br>
<br>
It is acceptable to pass <code>NULL</code> for <em>val</em> if the value in <em>valszp</em> is zero.
This can be used to determine the size of the buffer needed to receive
the object.</p>
</dd>
</dl>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
It may be easier to use one of the typed forms of this function.
</td>
</tr>
</table>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>nng_pipe_get_bool()</code></dt>
<dd>
<p>This function is for options which take a Boolean (<code>bool</code>).
The value will be stored at <em>bvalp</em>.</p>
</dd>
<dt class="hdlist1"><code>nng_pipe_get_int()</code></dt>
<dd>
<p>This function is for options which take an integer (<code>int</code>).
The value will be stored at <em>ivalp</em>.</p>
</dd>
<dt class="hdlist1"><code>nng_pipe_get_ms()</code></dt>
<dd>
<p>This function is used to retrieve time durations
(<a href="nng_duration.5.html"><code>nng_duration</code></a>) in milliseconds, which are stored in
<em>durp</em>.</p>
</dd>
<dt class="hdlist1"><code>nng_pipe_get_ptr()</code></dt>
<dd>
<p>This function is used to retrieve a pointer, <em>ptr</em>, to structured data.
The data referenced by <em>ptr</em> is generally managed using other functions.
Note that this form is somewhat special in that the object is generally
not copied, but instead the <strong>pointer</strong> to the object is copied.</p>
</dd>
<dt class="hdlist1"><code>nng_pipe_get_size()</code></dt>
<dd>
<p>This function is used to retrieve a size into the pointer <em>zp</em>,
typically for buffer sizes, message maximum sizes, and similar options.</p>
</dd>
<dt class="hdlist1"><code>nng_pipe_get_addr()</code></dt>
<dd>
<p>This function is used to retrieve an <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a>
into <em>sap</em>.</p>
</dd>
<dt class="hdlist1"><code>nng_pipe_get_string()</code></dt>
<dd>
<p>This function is used to retrieve a string into <em>strp</em>.
This string is created from the source using <a href="nng_strdup.3.html"><code>nng_strdup()</code></a>
and consequently must be freed by the caller using
<a href="nng_strfree.3.html"><code>nng_strfree()</code></a> when it is no longer needed.</p>
</dd>
<dt class="hdlist1"><code>nng_pipe_get_uint64()</code></dt>
<dd>
<p>This function is used to retrieve a 64-bit unsigned value into the value
referenced by <em>u64p</em>.
This is typically used for options
related to identifiers, network numbers, and similar.</p>
</dd>
</dl>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_return_values">RETURN VALUES</h2>
<div class="sectionbody">
<div class="paragraph">
<p>These functions return 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_EBADTYPE</code>
</td>
<td class="hdlist2">
<p>Incorrect type for option.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ECLOSED</code>
</td>
<td class="hdlist2">
<p>Parameter <em>p</em> does not refer to an open pipe.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ENOTSUP</code>
</td>
<td class="hdlist2">
<p>The option <em>opt</em> is not supported.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ENOMEM</code>
</td>
<td class="hdlist2">
<p>Insufficient memory exists.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_EINVAL</code>
</td>
<td class="hdlist2">
<p>Size of destination <em>val</em> too small for object.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_EWRITEONLY</code>
</td>
<td class="hdlist2">
<p>The option <em>opt</em> is write-only.</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_dialer_set.3.html">nng_dialer_set(3)</a>
<a href="nng_socket_get.3.html">nng_socket_get(3)</a>,
<a href="nng_listener_set.3.html">nng_listener_set(3)</a>
<a href="nng_msg_get_pipe.3.html">nng_msg_get_pipe(3)</a>
<a href="nng_strdup.3.html">nng_strdup(3)</a>,
<a href="nng_strerror.3.html">nng_strerror(3)</a>,
<a href="nng_strfree.3.html">nng_strfree(3)</a>,
<a href="nng_duration.5.html">nng_duration(5)</a>,
<a href="nng_options.5.html">nng_options(5)</a>,
<a href="nng_pipe.5.html">nng_pipe(5)</a>,
<a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>,
<a href="nng.7.html">nng(7)</a></p>
</div>
</div>
</div>