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 25, 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 , | |||||
.Fn nvlist_get_pararr | |||||
Done Inline ActionsNeeds an "and" .Fn nvlist_get_parent , and wblock: Needs an "and"
```.Fn nvlist_get_parent ,
and``` | |||||
Not Done Inline ActionsStill needs a new line with and. wblock: Still needs a new line with `and`. | |||||
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 of the supplied 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… | |||||
wblockUnsubmitted 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… | |||||
by the user. | |||||
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. | |||||
They still belong to the nvlist. | |||||
The nvlist must not be in error state. | |||||
wblockUnsubmitted Done Inline Actions"in *an* error state." wblock: "in *an* error state." | |||||
.Pp | |||||
The | |||||
.Nm cnvlist_take | |||||
family of functions returns the value associated with the given cookie and | |||||
rmove the element from the nvlist. | |||||
wblockUnsubmitted Done Inline ActionsTypo: wblock: Typo:
s/rmove/remove/ | |||||
When the value is a string, binary, or array value, the caller is responsible | |||||
for freeing returned memory with | |||||
.Fn free 3 . | |||||
function. | |||||
wblockUnsubmitted 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 an nvlist, the caller is responsible for destroying the | |||||
returned nvlist with | |||||
.Fn nvlist_destroy | |||||
function. | |||||
wblockUnsubmitted 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 . | |||||
Done Inline Actionss/with the/with/ --just "with close(2)." wblock: s/with the/with/ --just "with close(2)." | |||||
When the value is a descriptor, the caller is responsible for closing the | |||||
returned descriptor with | |||||
wblockUnsubmitted Done Inline Actionss/with/with the/ wblock: s/with/with the/ | |||||
.Fn close 2 | |||||
system call. | |||||
.Pp | |||||
The | |||||
.Nm cnvlist_free | |||||
family of functions removes element of the given cookie and free all resources | |||||
wblockUnsubmitted 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```… | |||||
associated with it. | |||||
If element of the given cookie has wrong type or does not exist, the program | |||||
wblockUnsubmitted Done Inline Actionss/If element/If an element/ wblock: s/If element/If an element/
s/has wrong/has the wrong/ | |||||
will be aborted. | |||||
wblockUnsubmitted Done Inline Actionss/will be/is/ wblock: s/will be/is/ | |||||
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"… | |||||
.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 | |||||
Done Inline Actionss/during/during the/ wblock: s/during/during the/ | |||||
.An Adam Starak Aq starak.adam@gmail.com | |||||
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… |
This is an if/then sentence, which is halting when read. Swap it around and edit a bit: