Changeset View
Standalone View
share/man/man9/cnv.9
- This file was added.
.\" | |||||
.\" 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 , | |||||
wblock: This is an if/then sentence, which is halting when read. Swap it around and edit a bit… | |||||
.Fn nvlist_get_parent , | |||||
wblockUnsubmitted Done Inline ActionsNeeds an "and" .Fn nvlist_get_parent , and wblock: Needs an "and"
```.Fn nvlist_get_parent ,
and``` | |||||
wblockUnsubmitted Not Done Inline ActionsStill needs a new line with and. wblock: Still needs a new line with `and`. | |||||
.Fn nvlist_get_pararr | |||||
from | |||||
.Xr nv 9 . | |||||
.Pp | |||||
Done Inline ActionsNeeds an ending period: .Xr nv 9 . wblock: Needs an ending period:
```.Xr nv 9 .``` | |||||
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 | |||||
Done Inline Actions"allows to" is not something generally said. family of functions obtains the value of the supplied cookie. wblock: "allows to" is not something generally said.
```family of functions obtains the value of the… | |||||
by the user, since they still belong to the nvlist. | |||||
Done Inline ActionsThese appear to be copies of the dnvlist man page, so I would suggest waiting for that one and using that wording. wblock: These appear to be copies of the dnvlist man page, so I would suggest waiting for that one and… | |||||
Not Done Inline ActionsI replaced this sentence with the one you wrote for dnvlist. starak.adam_gmail.com: I replaced this sentence with the one you wrote for dnvlist. | |||||
Done Inline ActionsNeeds a serial comma after "binaries" to separate it from "arrays": Returned strings, nvlists, descriptors, binaries, or arrays must not be modified wblock: Needs a serial comma after "binaries" to separate it from "arrays":
```Returned strings… | |||||
The nvlist must not be in an error state. | |||||
.Pp | |||||
The | |||||
Done Inline Actions"in *an* error state." wblock: "in *an* error state." | |||||
.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 | |||||
Done Inline ActionsTypo: wblock: Typo:
s/rmove/remove/ | |||||
.Fn free 3 . | |||||
When the value is an nvlist, the caller is responsible for destroying the | |||||
returned nvlist with | |||||
.Fn nvlist_destroy . | |||||
Done Inline ActionsThe sentence ends on the previous line, so this line should be removed. wblock: The sentence ends on the previous line, so this line should be removed. | |||||
When the value is a descriptor, the caller is responsible for closing the | |||||
returned descriptor with the | |||||
wblockUnsubmitted Done Inline Actionss/with the/with/ --just "with close(2)." wblock: s/with the/with/ --just "with close(2)." | |||||
.Fn close 2 . | |||||
.Pp | |||||
Done Inline ActionsAs above, change from "nvlist_destroy function." to "nvlist_destroy.": .Fn nvlist_destroy . and delete the next line, function. wblock: As above, change from "nvlist_destroy function." to "nvlist_destroy.":
```.Fn nvlist_destroy . | |||||
The | |||||
.Nm cnvlist_free | |||||
Done Inline Actionss/with/with the/ wblock: s/with/with the/ | |||||
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 | |||||
Done Inline Actionsfamily of functions removes an element of the supplied cookie and frees all resources (This has been said in this or the other related man page, possibly more clearly. It might be better to copy that one.) wblock: ```family of functions removes an element of the supplied cookie and frees all resources```… | |||||
The following example demonstrates how to deal with cnvlist API. | |||||
wblockUnsubmitted Not Done Inline ActionsPlease avoid "the following", and just use "this". Also, add "the" to "the cnvlist API": This example demonstrates how to deal with the cnvlist API. wblock: Please avoid "the following", and just use "this". Also, add "the" to "the cnvlist API"… | |||||
.Bd -literal | |||||
Done Inline Actionss/If element/If an element/ wblock: s/If element/If an element/
s/has wrong/has the wrong/ | |||||
int type; | |||||
Done Inline Actionss/will be/is/ wblock: s/will be/is/ | |||||
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; | |||||
Done Inline Actionss/during/during the/ wblock: s/during/during the/ | |||||
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 , | |||||
wblockUnsubmitted Done Inline ActionsThese should be sorted by section number then name. So: .Xr close 2 , .Xr free 3 , .Xr nv 9 wblock: These should be sorted by section number then name. So:
```.Xr close 2 ,
.Xr free 3 ,
.Xr nv… | |||||
.Xr close 2 , | |||||
.Xr free 3 | |||||
.Sh AUTHORS | |||||
.An -nosplit | |||||
The | |||||
.Nm cnv | |||||
API was created during the Google Summer Of Code 2016 by | |||||
.An Adam Starak Aq starak.adam@gmail.com . |
This is an if/then sentence, which is halting when read. Swap it around and edit a bit: