Changeset View
Standalone View
share/man/man9/dnv.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 DNV 9 | |||||
.Os | |||||
.Sh NAME | |||||
.Nm dnvlist_get, | |||||
.Nm dnvlist_take, | |||||
brueffer: If you add ".Nm dnv" above the line here, all ".Nm dnv" lines later on can be shortened to just… | |||||
Not Done Inline ActionsSorry, but I don't get the idea of using this ".Nm dnv". Can you explain it a little bit more? starak.adam_gmail.com: Sorry, but I don't get the idea of using this ".Nm dnv". Can you explain it a little bit more? | |||||
Not Done Inline ActionsSure! The first .Nm call (currently ".Nm dnvlist_get") sets the default value, so any later call of simply ".Nm" will produce dnvlist_get. Most API manpages define the name of the API ("dnv" here) as default value, so they only have to call .Nm when they refer to the API. brueffer: Sure! The first .Nm call (currently ".Nm dnvlist_get") sets the default value, so any later… | |||||
.Nd "API for getting name/value pairs. Nonexistent pairs do not raise an error." | |||||
.Sh LIBRARY | |||||
Not Done Inline ActionsMaybe we should go with something like Or. oshogbo: Maybe we should go with something like
library for name/value pair with default values.
Or. | |||||
.Lb libnv | |||||
Done Inline ActionsPlease do not use contractions: https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style-guidelines.html This sentence is based on a couple of "not"s, which makes it a bit confusing. Can we state it differently to make it clearer and avoid the pause in the middle? Something like "API for name/value pairs. Nonexistent pairs do not raise an error." wblock: Please do not use contractions: https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp… | |||||
.Sh SYNOPSIS | |||||
.In sys/dnv.h | |||||
.Ft bool | |||||
.Fn dnvlist_get_bool "const nvlist_t *nvl" "const char *name" "bool defval" | |||||
.Ft uint64_t | |||||
.Fn dnvlist_get_number "const nvlist_t *nvl" "const char *name" "uint64_t defval" | |||||
.Ft char * | |||||
.Fn dnvlist_get_string "const nvlist_t *nvl" "const char *name" "const char *defval" | |||||
.Ft nvlist_t * | |||||
.Fn dnvlist_get_nvlist "const nvlist_t *nvl" "const char *name" "nvlist_t *defval" | |||||
.Ft int | |||||
.Fn dnvlist_get_descriptor "const nvlist_t *nvl" "const char *name" "int defval" | |||||
.Ft void * | |||||
.Fn dnvlist_get_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep" "void *defval" "size_t defsize" | |||||
.Ft bool | |||||
.Fn dnvlist_take_bool "const nvlist_t *nvl" "const char *name" "bool defval" | |||||
.Ft uint64_t | |||||
.Fn dnvlist_take_number "const nvlist_t *nvl" "const char *name" "uint64_t defval" | |||||
.Ft char * | |||||
.Fn dnvlist_take_string "const nvlist_t *nvl" "const char *name" "const char *defval" | |||||
.Ft nvlist_t * | |||||
.Fn dnvlist_take_nvlist "const nvlist_t *nvl" "const char *name" "nvlist_t *defval" | |||||
.Ft int | |||||
.Fn dnvlist_take_descriptor "const nvlist_t *nvl" "const char *name" "int defval" | |||||
.Ft void * | |||||
.Fn dnvlist_take_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep" "void *defval" "size_t defsize" | |||||
.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 | |||||
Done Inline Actionslibrary permits easy management of name/value pairs and can send and receive wblock: library permits easy management of name/value pairs and can send and receive | |||||
.Xr nv 9 . | |||||
Done Inline ActionsPlease start a new sentence on a new line. Also: For more information, also see .Xr nv 9 . wblock: Please start a new sentence on a new line. Also:
```For more information, also see
.Xr nv 9 . | |||||
.Pp | |||||
The | |||||
.Nm dnvlist_get | |||||
family of functions returns the value associated with the specified name. | |||||
If an element of the specified name does not exist, the function returns the | |||||
Done Inline Actionss/family/family of/ Please start new sentences on new lines. s/the element/an element/ wblock: s/family/family of/
s/returns/returns the/
Please start new sentences on new lines.
s/the… | |||||
value provided in | |||||
Done Inline Actionss/of/of the/ wblock: s/of/of the/
s/return value/return the value/ | |||||
Done Inline Actionss/will return/returns/ wblock: s/will return/returns/ | |||||
.Fa defval . | |||||
Done Inline Actionss/of string/of a string/ wblock: s/of string/of a string/
s/returned/the returned/ | |||||
Returned strings, nvlists, descriptors, binaries, or arrays must not be modified | |||||
Not Done Inline ActionsWhat does "should not be modified" mean? Is the user not supposed to modify it, or is this saying that the function will not modify it? "Should" is generally a recommendation to the reader, and that is probably not what was meant here. wblock: What does "should not be modified" mean? Is the user not supposed to modify it, or is this… | |||||
Not Done Inline ActionsUser cannot modify it, because it still belongs to the nvlist (structure which stores those pairs) and any modification may cause an undefined behavior. starak.adam_gmail.com: User cannot modify it, because it still belongs to the nvlist (structure which stores those… | |||||
Done Inline ActionsNeeds a serial comma after "binaries": wblock: Needs a serial comma after "binaries":
s/binaries/binaries,/ | |||||
by the user. | |||||
Not Done Inline ActionsSorry, I don't understand this sentence either. wblock: Sorry, I don't understand this sentence either. | |||||
Not Done Inline ActionsNvlist structure has its own error flag. If you want to use one of those functions, the flag must be equal to 0. Otherwise the program will be aborted. starak.adam_gmail.com: Nvlist structure has its own error flag. If you want to use one of those functions, the flag… | |||||
Done Inline ActionsAs an instruction, it should probably be more emphatic (ignoring wrapping): Returned strings, nvlists, descriptors, binaries or arrays must not be modified by the user. They still belong to the nvlist. wblock: As an instruction, it should probably be more emphatic (ignoring wrapping):
```Returned strings… | |||||
They still belong to the nvlist. | |||||
Not Done Inline ActionsStill not clear on this. Maybe "The nvlist error flag must be 0, or attempts to use any of these functions will cause the program to abort."? wblock: Still not clear on this. Maybe "The nvlist error flag must be 0, or attempts to use any of… | |||||
Not Done Inline ActionsI'll quote 2 functions from nv(9), which use this flag. Maybe it'll clean up the situation. The nvlist_error() function returns any error value that the nvlist accumulated. If the given nvlist is NULL the ENOMEM error will be returned. The nvlist_set_error() function sets an nvlist to be in the error state. Subsequent calls to nvlist_error() will return the given error value. This function cannot be used to clear the error state from an nvlist. This function does nothing if the nvlist is already in the error state. So, if you want to use get or take functions, nvlist_error() should return 0. Otherwise the program will be aborted, because the nvlist in is error state. "The nvlist must not be in error state. Otherwise, attempts to use any of these functions will cause the program to abort." starak.adam_gmail.com: I'll quote 2 functions from nv(9), which use this flag. Maybe it'll clean up the situation. | |||||
Done Inline ActionsAh, that helps. How about: If the nvlist is in an error state, attempts to use any of these functions will cause the program to abort. wblock: Ah, that helps. How about:
```If the nvlist is in an error state, attempts to use any of these… | |||||
If the nvlist is in an error state, attempts to use any of these functions will | |||||
cause the program to abort. | |||||
.Pp | |||||
Done Inline Actionss/family/family of/ wblock: s/family/family of/
s/returns value/returns the value/ | |||||
The | |||||
Done Inline ActionsPlease start new sentences on new lines. "given name" is confusing here. wblock: Please start new sentences on new lines.
"given name" is confusing here.
Please do not use… | |||||
Done Inline Actionss/remove/removes/ I still think "given name" is confusing. "specified" is a little better than "given". wblock: s/remove/removes/
I still think "given name" is confusing. "specified" is a little better… | |||||
.Nm dnvlist_take | |||||
Not Done Inline ActionsWhen the value is a string, binary, or array value, the caller is There might be a better way to show this list of what to do depending on returned values, like a table. wblock: When the value is a string, binary, or array value, the caller is
responsible for freeing… | |||||
Not Done Inline ActionsThat's a great idea, but I don't know how to make a table. :( starak.adam_gmail.com: That's a great idea, but I don't know how to make a table. :( | |||||
family of functions returns the value associated with the specified name and | |||||
removes the element from the nvlist. | |||||
If an element of the supplied name does not exist, the value provided in | |||||
.Nm defval | |||||
Done Inline ActionsWhen the value is an nvlist, the caller is responsible for destroying the returned nvlist with wblock: When the value is an nvlist, the caller is responsible for destroying the returned nvlist with
. | |||||
is returned. | |||||
When the value is a string, binary, or array value, the caller is | |||||
responsible for freeing returned memory with | |||||
.Fn free 3 . | |||||
Done Inline ActionsWhen the value is a descriptor, the caller is responsible for closing the returned descriptor with wblock: When the value is a descriptor, the caller is responsible for closing the returned descriptor… | |||||
When the value is an nvlist, the caller is responsible for destroying the | |||||
Done Inline ActionsJust .Fn free 3 . and delete the "function." line. wblock: Just
```.Fn free 3 .```
and delete the "function." line. | |||||
returned nvlist with | |||||
.Fn nvlist_destroy . | |||||
When the value is a descriptor, the caller is responsible for closing the | |||||
returned descriptor with | |||||
Done Inline ActionsThese values should be sorted by section, so: wblock: These values should be sorted by section, so:
.Xr close 2 ,
.Xr free 3 ,
.Xr nv 9 | |||||
Done Inline ActionsAs above, just .Fn nvlist_destroy . and delete the "function." line. wblock: As above, just
```.Fn nvlist_destroy .```
and delete the "function." line. | |||||
.Fn close 2 . | |||||
.Sh SEE ALSO | |||||
.Xr close 2 , | |||||
Done Inline ActionsAs above, just .Fn close 2 . and delete the "system call." line. wblock: As above, just
```.Fn close 2 .```
and delete the "system call." line. | |||||
.Xr free 3 , | |||||
.Xr nv 9 | |||||
.Sh HISTORY | |||||
Done Inline ActionsWrong commas after sorting, this one should move one line up. brueffer: Wrong commas after sorting, this one should move one line up. | |||||
The | |||||
.Nm dnv | |||||
API appeared in | |||||
.Fx 11.0 . | |||||
.Sh AUTHORS | |||||
.An -nosplit | |||||
The | |||||
.Nm dnv | |||||
API was implemented by | |||||
.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net | |||||
under sponsorship from the FreeBSD Foundation. | |||||
This manual page was written by | |||||
.An Adam Starak Aq Mt starak.adam@gmail.com |
If you add ".Nm dnv" above the line here, all ".Nm dnv" lines later on can be shortened to just ".Nm".