xref: /freebsd/share/man/man9/cnv.9 (revision 9768746b)
1.\"
2.\" Copyright (c) 2016 Adam Starak <starak.adam@gmail.com>
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.Dd June 18, 2018
29.Dt CNV 9
30.Os
31.Sh NAME
32.Nm cnvlist_get ,
33.Nm cnvlist_take ,
34.Nm cnvlist_free
35.Nd "API for managing name/value pairs by cookie."
36.Sh LIBRARY
37.Lb libnv
38.Sh SYNOPSIS
39.In sys/cnv.h
40.Ft const char *
41.Fn cnvlist_name "const void *cookie"
42.Ft int
43.Fn cnvlist_type "const void *cookie"
44.\"
45.Ft bool
46.Fn cnvlist_get_bool "const void *cookie"
47.Ft uint64_t
48.Fn cnvlist_get_number "const void *cookie"
49.Ft "const char *"
50.Fn cnvlist_get_string "const void *cookie"
51.Ft "const nvlist_t *"
52.Fn cnvlist_get_nvlist "const void *cookie"
53.Ft "const void *"
54.Fn cnvlist_get_binary "const void *cookie" "size_t *sizep"
55.Ft "const bool *"
56.Fn cnvlist_get_bool_array "const void *cookie" "size_t *nitemsp"
57.Ft "const uint64_t *"
58.Fn cnvlist_get_number_array "const void *cookie" "size_t *nitemsp"
59.Ft "const char * const *"
60.Fn cnvlist_get_string_array "const void *cookie" "size_t *nitemsp"
61.Ft "const nvlist_t * const *"
62.Fn cnvlist_get_nvlist_array "const void *cookie" "size_t *nitemsp"
63.Ft int
64.Fn cnvlist_get_descriptor "const void *cookie"
65.Ft "const int *"
66.Fn cnvlist_get_descriptor_array "const void *cookie" "size_t *nitemsp"
67.\"
68.Ft bool
69.Fn cnvlist_take_bool "void *cookie"
70.Ft uint64_t
71.Fn cnvlist_take_number "void *cookie"
72.Ft "const char *"
73.Fn cnvlist_take_string "void *cookie"
74.Ft "const nvlist_t *"
75.Fn cnvlist_take_nvlist "void *cookie"
76.Ft "const void *"
77.Fn cnvlist_take_binary "void *cookie" "size_t *sizep"
78.Ft "const bool *"
79.Fn cnvlist_take_bool_array "void *cookie" "size_t *nitemsp"
80.Ft "const uint64_t *"
81.Fn cnvlist_take_number_array "void *cookie" "size_t *nitemsp"
82.Ft "const char * const *"
83.Fn cnvlist_take_string_array "void *cookie" "size_t *nitemsp"
84.Ft "const nvlist_t * const *"
85.Fn cnvlist_take_nvlist_array "void *cookie" "size_t *nitemsp"
86.Ft int
87.Fn cnvlist_take_descriptor "void *cookie"
88.Ft "const int *"
89.Fn cnvlist_take_descriptor_array "void *cookie" "size_t *nitemsp"
90.\"
91.Ft void
92.Fn cnvlist_free_null "void *cookie"
93.Ft void
94.Fn cnvlist_free_bool "void *cookie"
95.Ft void
96.Fn cnvlist_free_number "void *cookie"
97.Ft void
98.Fn cnvlist_free_string "void *cookie"
99.Ft void
100.Fn cnvlist_free_nvlist "void *cookie"
101.Ft void
102.Fn cnvlist_free_descriptor "void *cookie"
103.Ft void
104.Fn cnvlist_free_binary "void *cookie"
105.Ft void
106.Fn cnvlist_free_bool_array "void *cookie"
107.Ft void
108.Fn cnvlist_free_number_array "void *cookie"
109.Ft void
110.Fn cnvlist_free_string_array "void *cookie"
111.Ft void
112.Fn cnvlist_free_nvlist_array "void *cookie"
113.Ft void
114.Fn cnvlist_free_descriptor_array "void *cookie"
115.Sh DESCRIPTION
116The
117.Nm libnv
118library permits easy management of name/value pairs and can send and receive
119them over sockets.
120For more information, also see
121.Xr nv 9 .
122.Pp
123The concept of cookies is explained in
124.Fn nvlist_next ,
125.Fn nvlist_get_parent ,
126and
127.Fn nvlist_get_pararr
128from
129.Xr nv 9 .
130.Pp
131The
132.Fn cnvlist_name
133function returns the name of an element associated with the given cookie.
134.Pp
135The
136.Fn cnvlist_type
137function returns the type of an element associated with the given cookie.
138Types which can be returned are described in
139.Xr nv 9 .
140.Pp
141The
142.Nm cnvlist_get
143family of functions obtains the value associated with the given cookie.
144Returned strings, nvlists, descriptors, binaries, or arrays must not be modified
145by the user, since they still belong to the nvlist.
146The nvlist must not be in an error state.
147.Pp
148The
149.Nm cnvlist_take
150family of functions returns the value associated with the given cookie and
151removes the element from the nvlist.
152When the value is a string, binary, or array value, the caller is responsible
153for freeing the returned memory with
154.Fn free 3 .
155When the value is an nvlist, the caller is responsible for destroying the
156returned nvlist with
157.Fn nvlist_destroy .
158When the value is a descriptor, the caller is responsible for closing the
159returned descriptor with the
160.Fn close 2 .
161.Pp
162The
163.Nm cnvlist_free
164family of functions removes an element of the supplied cookie and frees all
165resources.
166If an element of the given cookie has the wrong type or does not exist, the
167program
168is aborted.
169.Sh EXAMPLES
170The following example demonstrates how to deal with cnvlist API.
171.Bd -literal
172int type;
173void *cookie, *scookie, *bcookie;
174nvlist_t *nvl;
175char *name;
176
177nvl = nvlist_create(0);
178nvlist_add_bool(nvl, "test", 1 == 2);
179nvlist_add_string(nvl, "test2", "cnvlist");
180cookie = NULL;
181
182while (nvlist_next(nvl, &type, &cookie) != NULL) {
183        switch (type) {
184        case NV_TYPE_BOOL:
185                printf("test: %d\\n", cnvlist_get_bool(cookie));
186                bcookie = cookie;
187                break;
188        case NV_TYPE_STRING:
189                printf("test2: %s\\n", cnvlist_get_string(cookie));
190                scookie = cookie;
191                break;
192        }
193}
194
195name = cnvlist_take_string(scookie);
196cnvlist_free_bool(bcookie);
197
198printf("test2: %s\\n", name);
199free(name);
200
201printf("nvlist_empty = %d\\n", nvlist_empty(nvl));
202nvlist_destroy(nvl);
203
204return (0);
205.Ed
206.Sh SEE ALSO
207.Xr close 2 ,
208.Xr free 3 ,
209.Xr nv 9
210.Sh AUTHORS
211The
212.Nm cnv
213API was created during the Google Summer Of Code 2016 by
214.An Adam Starak .
215