Changeset View
Changeset View
Standalone View
Standalone View
head/share/man/man9/cnv.9
Property | Old Value | New Value |
---|---|---|
svn:eol-style | null | native \ No newline at end of property |
svn:keywords | null | FreeBSD=%H \ No newline at end of property |
svn:mime-type | null | text/plain \ No newline at end of property |
.\" | |||||
.\" Copyright (c) 2016 Adam Starak <starak.adam@gmail.com> | |||||
.\" All rights reserved. | |||||
.\" | |||||
.\" Redistribution and use in source and binary forms, with or without | |||||
.\" modification, are permitted provided that the following conditions | |||||
.\" are met: | |||||
.\" 1. Redistributions of source code must retain the above copyright | |||||
.\" notice, this list of conditions and the following disclaimer. | |||||
.\" 2. Redistributions in binary form must reproduce the above copyright | |||||
.\" notice, this list of conditions and the following disclaimer in the | |||||
.\" documentation and/or other materials provided with the distribution. | |||||
.\" | |||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | |||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | |||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |||||
.\" SUCH DAMAGE. | |||||
.\" | |||||
.\" $FreeBSD$ | |||||
.\" | |||||
.Dd July 26, 2016 | |||||
.Dt CNV 9 | |||||
.Os | |||||
.Sh NAME | |||||
.Nm cnvlist_get, | |||||
.Nm cnvlist_take, | |||||
.Nm cnvlist_free, | |||||
.Nd "API for managing name/value pairs by cookie." | |||||
.Sh LIBRARY | |||||
.Lb libnv | |||||
.Sh SYNOPSIS | |||||
.In sys/cnv.h | |||||
.Ft bool | |||||
.Fn cnvlist_get_bool "void *cookiep" | |||||
.Ft uint64_t | |||||
.Fn cnvlist_get_number "void *cookiep" | |||||
.Ft "const char *" | |||||
.Fn cnvlist_get_string "void *cookiep" | |||||
.Ft "const nvlist_t *" | |||||
.Fn cnvlist_get_nvlist "void *cookiep" | |||||
.Ft "const void *" | |||||
.Fn cnvlist_get_binary "void *cookiep" "size_t *sizep" | |||||
.Ft "const bool *" | |||||
.Fn cnvlist_get_bool_array "void *cookiep" "size_t *nitemsp" | |||||
.Ft "const uint64_t *" | |||||
.Fn cnvlist_get_number_array "void *cookiep" "size_t *nitemsp" | |||||
.Ft "const char * const *" | |||||
.Fn cnvlist_get_string_array "void *cookiep" "size_t *nitemsp" | |||||
.Ft "const nvlist_t * const *" | |||||
.Fn cnvlist_get_nvlist_array "void *cookiep" "size_t *nitemsp" | |||||
.Ft int | |||||
.Fn cnvlist_get_descriptor "void *cookiep" | |||||
.Ft "const int *" | |||||
.Fn cnvlist_get_descriptor_array "void *cookiep" "size_t *nitemsp" | |||||
.\" | |||||
.Ft bool | |||||
.Fn cnvlist_take_bool "void *cookiep" | |||||
.Ft uint64_t | |||||
.Fn cnvlist_take_number "void *cookiep" | |||||
.Ft "const char *" | |||||
.Fn cnvlist_take_string "void *cookiep" | |||||
.Ft "const nvlist_t *" | |||||
.Fn cnvlist_take_nvlist "void *cookiep" | |||||
.Ft "const void *" | |||||
.Fn cnvlist_take_binary "void *cookiep" "size_t *sizep" | |||||
.Ft "const bool *" | |||||
.Fn cnvlist_take_bool_array "void *cookiep" "size_t *nitemsp" | |||||
.Ft "const uint64_t *" | |||||
.Fn cnvlist_take_number_array "void *cookiep" "size_t *nitemsp" | |||||
.Ft "const char * const *" | |||||
.Fn cnvlist_take_string_array "void *cookiep" "size_t *nitemsp" | |||||
.Ft "const nvlist_t * const *" | |||||
.Fn cnvlist_take_nvlist_array "void *cookiep" "size_t *nitemsp" | |||||
.Ft int | |||||
.Fn cnvlist_take_descriptor "void *cookiep" | |||||
.Ft "const int *' | |||||
.Fn cnvlist_take_descriptor_array "void *cookiep" "size_t *nitemsp" | |||||
.\" | |||||
.Ft void | |||||
.Fn cnvlist_free_null "nvlist_t *nvl" "void *cookiep" | |||||
.Ft void | |||||
.Fn cnvlist_free_bool "nvlist_t *nvl" "void *cookiep" | |||||
.Ft void | |||||
.Fn cnvlist_free_number "nvlist_t *nvl" "void *cookiep" | |||||
.Ft void | |||||
.Fn cnvlist_free_string "nvlist_t *nvl" "void *cookiep" | |||||
.Ft void | |||||
.Fn cnvlist_free_nvlist "nvlist_t *nvl" "void *cookiep" | |||||
.Ft void | |||||
.Fn cnvlist_free_descriptor "nvlist_t *nvl" "void *cookiep" | |||||
.Ft void | |||||
.Fn cnvlist_free_binary "nvlist_t *nvl" "void *cookiep" | |||||
.Ft void | |||||
.Fn cnvlist_free_bool_array "nvlist_t *nvl" "void *cookiep" | |||||
.Ft void | |||||
.Fn cnvlist_free_number_array "nvlist_t *nvl" "void *cookiep" | |||||
.Ft void | |||||
.Fn cnvlist_free_string_array "nvlist_t *nvl" "void *cookiep" | |||||
.Ft void | |||||
.Fn cnvlist_free_nvlist_array "nvlist_t *nvl" "void *cookiep" | |||||
.Ft void | |||||
.Fn cnvlist_free_descriptor_array "nvlist_t *nvl" "void *cookiep" | |||||
.Sh DESCRIPTION | |||||
The | |||||
.Nm libnv | |||||
library permits easy management of name/value pairs and can send and receive | |||||
them over sockets. | |||||
For more information, also see | |||||
.Xr nv 9 . | |||||
.Pp | |||||
The concept of cookies is explained in | |||||
.Fn nvlist_next , | |||||
.Fn nvlist_get_parent , | |||||
and | |||||
.Fn nvlist_get_pararr | |||||
from | |||||
.Xr nv 9 . | |||||
.Pp | |||||
The | |||||
.Nm cnvlist_get | |||||
family of functions obtains the value associated with the given cookie. | |||||
Returned strings, nvlists, descriptors, binaries, or arrays must not be modified | |||||
by the user, since they still belong to the nvlist. | |||||
The nvlist must not be in an error state. | |||||
.Pp | |||||
The | |||||
.Nm cnvlist_take | |||||
family of functions returns the value associated with the given cookie and | |||||
removes the element from the nvlist. | |||||
When the value is a string, binary, or array value, the caller is responsible | |||||
for freeing the returned memory with | |||||
.Fn free 3 . | |||||
When the value is an nvlist, the caller is responsible for destroying the | |||||
returned nvlist with | |||||
.Fn nvlist_destroy . | |||||
When the value is a descriptor, the caller is responsible for closing the | |||||
returned descriptor with the | |||||
.Fn close 2 . | |||||
.Pp | |||||
The | |||||
.Nm cnvlist_free | |||||
family of functions removes an element of the supplied cookie and frees all | |||||
resources. | |||||
If an element of the given cookie has the wrong type or does not exist, the | |||||
program | |||||
is aborted. | |||||
.Sh EXAMPLE | |||||
The following example demonstrates how to deal with cnvlist API. | |||||
.Bd -literal | |||||
int type; | |||||
void *cookie, *scookie, *bcookie; | |||||
nvlist_t *nvl; | |||||
char *name; | |||||
nvl = nvlist_create(0); | |||||
nvlist_add_bool(nvl, "test", 1 == 2); | |||||
nvlist_add_string(nvl, "test2", "cnvlist"); | |||||
cookie = NULL; | |||||
while (nvlist_next(nvl, &type, &cookie) != NULL) { | |||||
switch (type) { | |||||
case NV_TYPE_BOOL: | |||||
printf("test: %d\\n", cnvlist_get_bool(cookie)); | |||||
bcookie = cookie; | |||||
break; | |||||
case NV_TYPE_STRING: | |||||
printf("test2: %s\\n", cnvlist_get_string(cookie)); | |||||
scookie = cookie; | |||||
break; | |||||
} | |||||
} | |||||
name = cnvlist_take_string(nvl, scookie); | |||||
cnvlist_free_bool(nvl, bcookie); | |||||
printf("test2: %s\\n", name); | |||||
free(name); | |||||
printf("nvlist_empty = %d\\n", nvlist_empty(nvl)); | |||||
nvlist_destroy(nvl); | |||||
return (0); | |||||
.Ed | |||||
.Sh SEE ALSO | |||||
.Xr nv 9 , | |||||
.Xr close 2 , | |||||
.Xr free 3 | |||||
.Sh AUTHORS | |||||
.An -nosplit | |||||
The | |||||
.Nm cnv | |||||
API was created during the Google Summer Of Code 2016 by |