1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
<table class="head">
<tr>
<td class="head-ltitle">DNV(9)</td>
<td class="head-vol">Kernel Developer's Manual</td>
<td class="head-rtitle">DNV(9)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">dnvlist_get</code>,
<code class="Nm">dnvlist_take</code> — <span class="Nd">API for
getting name/value pairs with a default value</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="LIBRARY"><a class="permalink" href="#LIBRARY">LIBRARY</a></h1>
<p class="Pp"><span class="Lb">Name/value pairs library (libnv, -lnv)</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">sys/dnv.h</a>></code></p>
<p class="Pp"><var class="Ft">bool</var>
<br/>
<code class="Fn">dnvlist_get_bool</code>(<var class="Fa" style="white-space: nowrap;">const
nvlist_t *nvl</var>, <var class="Fa" style="white-space: nowrap;">const char
*name</var>, <var class="Fa" style="white-space: nowrap;">bool
defval</var>);</p>
<p class="Pp"><var class="Ft">uint64_t</var>
<br/>
<code class="Fn">dnvlist_get_number</code>(<var class="Fa" style="white-space: nowrap;">const
nvlist_t *nvl</var>, <var class="Fa" style="white-space: nowrap;">const char
*name</var>, <var class="Fa" style="white-space: nowrap;">uint64_t
defval</var>);</p>
<p class="Pp"><var class="Ft">char *</var>
<br/>
<code class="Fn">dnvlist_get_string</code>(<var class="Fa" style="white-space: nowrap;">const
nvlist_t *nvl</var>, <var class="Fa" style="white-space: nowrap;">const char
*name</var>, <var class="Fa" style="white-space: nowrap;">const char
*defval</var>);</p>
<p class="Pp"><var class="Ft">nvlist_t *</var>
<br/>
<code class="Fn">dnvlist_get_nvlist</code>(<var class="Fa" style="white-space: nowrap;">const
nvlist_t *nvl</var>, <var class="Fa" style="white-space: nowrap;">const char
*name</var>, <var class="Fa" style="white-space: nowrap;">nvlist_t
*defval</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">dnvlist_get_descriptor</code>(<var class="Fa" style="white-space: nowrap;">const
nvlist_t *nvl</var>, <var class="Fa" style="white-space: nowrap;">const char
*name</var>, <var class="Fa" style="white-space: nowrap;">int
defval</var>);</p>
<p class="Pp"><var class="Ft">void *</var>
<br/>
<code class="Fn">dnvlist_get_binary</code>(<var class="Fa" style="white-space: nowrap;">const
nvlist_t *nvl</var>, <var class="Fa" style="white-space: nowrap;">const char
*name</var>, <var class="Fa" style="white-space: nowrap;">size_t
*sizep</var>, <var class="Fa" style="white-space: nowrap;">void
*defval</var>, <var class="Fa" style="white-space: nowrap;">size_t
defsize</var>);</p>
<p class="Pp"><var class="Ft">bool</var>
<br/>
<code class="Fn">dnvlist_take_bool</code>(<var class="Fa" style="white-space: nowrap;">const
nvlist_t *nvl</var>, <var class="Fa" style="white-space: nowrap;">const char
*name</var>, <var class="Fa" style="white-space: nowrap;">bool
defval</var>);</p>
<p class="Pp"><var class="Ft">uint64_t</var>
<br/>
<code class="Fn">dnvlist_take_number</code>(<var class="Fa" style="white-space: nowrap;">const
nvlist_t *nvl</var>, <var class="Fa" style="white-space: nowrap;">const char
*name</var>, <var class="Fa" style="white-space: nowrap;">uint64_t
defval</var>);</p>
<p class="Pp"><var class="Ft">char *</var>
<br/>
<code class="Fn">dnvlist_take_string</code>(<var class="Fa" style="white-space: nowrap;">const
nvlist_t *nvl</var>, <var class="Fa" style="white-space: nowrap;">const char
*name</var>, <var class="Fa" style="white-space: nowrap;">const char
*defval</var>);</p>
<p class="Pp"><var class="Ft">nvlist_t *</var>
<br/>
<code class="Fn">dnvlist_take_nvlist</code>(<var class="Fa" style="white-space: nowrap;">const
nvlist_t *nvl</var>, <var class="Fa" style="white-space: nowrap;">const char
*name</var>, <var class="Fa" style="white-space: nowrap;">nvlist_t
*defval</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">dnvlist_take_descriptor</code>(<var class="Fa" style="white-space: nowrap;">const
nvlist_t *nvl</var>, <var class="Fa" style="white-space: nowrap;">const char
*name</var>, <var class="Fa" style="white-space: nowrap;">int
defval</var>);</p>
<p class="Pp"><var class="Ft">void *</var>
<br/>
<code class="Fn">dnvlist_take_binary</code>(<var class="Fa" style="white-space: nowrap;">const
nvlist_t *nvl</var>, <var class="Fa" style="white-space: nowrap;">const char
*name</var>, <var class="Fa" style="white-space: nowrap;">size_t
*sizep</var>, <var class="Fa" style="white-space: nowrap;">void
*defval</var>, <var class="Fa" style="white-space: nowrap;">size_t
defsize</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">libnv</code> library permits easy management
of name/value pairs and can send and receive them over sockets. For more
information, see <a class="Xr">nv(9)</a>.</p>
<p class="Pp">The <code class="Nm">dnvlist_get</code> functions return the value
associated with <var class="Fa">name</var>. If an element named
<var class="Fa">name</var> does not exist, the function returns the value
provided in <var class="Fa">defval</var>. Returned strings, nvlists,
descriptors, binaries, or arrays must not be modified by the user since they
still belong to the nvlist. If the nvlist is in an error state, attempts to
use any of these functions will cause the program to abort.</p>
<p class="Pp" id="free">The <code class="Nm">dnvlist_take</code> functions
return the value associated with <var class="Fa">name</var> and removes the
associated element from <var class="Fa">nvl</var>. If an element named
<var class="Fa">name</var> does not exist, the value provided in
<code class="Nm">defval</code> is returned. When the value is a string,
binary, or array value, the caller is responsible for freeing returned
memory with
<a class="permalink" href="#free"><code class="Fn">free</code></a>(<var class="Fa">3</var>).
When the value is an nvlist, the caller is responsible for destroying the
returned nvlist with
<a class="permalink" href="#nvlist_destroy"><code class="Fn" id="nvlist_destroy">nvlist_destroy</code></a>().
When the value is a descriptor, the caller is responsible for closing the
returned descriptor with
<a class="permalink" href="#close"><code class="Fn" id="close">close</code></a>(<var class="Fa">2</var>).</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">close(2)</a>, <a class="Xr">free(3)</a>,
<a class="Xr">nv(9)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">dnv</code> API appeared in
<span class="Ux">FreeBSD 11.0</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">The <code class="Nm">dnv</code> API was implemented by
<span class="An">Pawel Jakub Dawidek</span>
<<a class="Mt" href="mailto:pawel@dawidek.net">pawel@dawidek.net</a>>
under sponsorship from the FreeBSD Foundation. This manual page was written
by <span class="An">Adam Starak</span>
<<a class="Mt" href="mailto:starak.adam@gmail.com">starak.adam@gmail.com</a>></p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">January 3, 2025</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
