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 June 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 | |||||
In order to understand the idea of cookie, please read | |||||
wblock: This is an if/then sentence, which is halting when read. Swap it around and edit a bit… | |||||
.Fn nvlist_next , | |||||
.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 | |||||
wblockUnsubmitted Done Inline ActionsNeeds an ending period: .Xr nv 9 . wblock: Needs an ending period:
```.Xr nv 9 .``` | |||||
.Pp | |||||
The | |||||
.Nm cnvlist_get | |||||
family of functions allows to obtain the value of the supplied cookie. | |||||
wblockUnsubmitted 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… | |||||
In case of string, nvlist, descriptor, binary or any array, returned resource | |||||
wblockUnsubmitted 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… | |||||
starak.adam_gmail.comAuthorUnsubmitted 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. | |||||
should not be modified - it still belongs to the nvlist. | |||||
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 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 | |||||
rmove the element from the nvlist. | |||||
When the value is a string, binary, or array value, the caller is responsible | |||||
for freeing returned memory with | |||||
Done Inline ActionsTypo: wblock: Typo:
s/rmove/remove/ | |||||
.Fn free 3 . | |||||
function. | |||||
When the value is an nvlist, the caller is responsible for destroying the | |||||
returned nvlist with | |||||
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. | |||||
.Fn nvlist_destroy | |||||
function. | |||||
When the value is a descriptor, the caller is responsible for closing the | |||||
Done Inline Actionss/with the/with/ --just "with close(2)." wblock: s/with the/with/ --just "with close(2)." | |||||
returned descriptor with | |||||
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 . | |||||
.Fn close 2 | |||||
system call. | |||||
Done Inline Actionss/with/with the/ wblock: s/with/with the/ | |||||
.Pp | |||||
The | |||||
.Nm cnvlist_free | |||||
family of functions removes element of the given cookie and free all resources | |||||
associated with it. | |||||
If element of the given cookie has wrong type or does not exist, the program | |||||
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```… | |||||
will be aborted. | |||||
.Sh SEE ALSO | |||||
Done Inline Actionss/If element/If an element/ wblock: s/If element/If an element/
s/has wrong/has the wrong/ | |||||
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"… | |||||
.Xr nv 9 , | |||||
Done Inline Actionss/will be/is/ wblock: s/will be/is/ | |||||
.Xr close 2 , | |||||
.Xr free 3 | |||||
.Sh AUTHORS | |||||
.An -nosplit | |||||
The | |||||
.Nm cnv | |||||
API was created during Google Summer Of Code 2016 by | |||||
wblockUnsubmitted 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: