nv.9 (286642) | nv.9 (286796) |
---|---|
1.\" 2.\" Copyright (c) 2013 The FreeBSD Foundation | 1.\" 2.\" Copyright (c) 2013 The FreeBSD Foundation |
3.\" Copyright (c) 2013-2015 Mariusz Zaborski <oshogbo@FreeBSD.org> |
|
3.\" All rights reserved. 4.\" 5.\" This documentation was written by Pawel Jakub Dawidek under sponsorship 6.\" the FreeBSD Foundation. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: --- 10 unchanged lines hidden (view full) --- 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" | 4.\" All rights reserved. 5.\" 6.\" This documentation was written by Pawel Jakub Dawidek under sponsorship 7.\" the FreeBSD Foundation. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: --- 10 unchanged lines hidden (view full) --- 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" |
29.\" $FreeBSD: head/share/man/man9/nv.9 286642 2015-08-11 17:41:32Z oshogbo $ | 30.\" $FreeBSD: head/share/man/man9/nv.9 286796 2015-08-15 06:34:49Z oshogbo $ |
30.\" | 31.\" |
31.Dd Aug 11, 2015 | 32.Dd August 15, 2015 |
32.Dt NV 9 33.Os 34.Sh NAME 35.Nm nvlist_create , 36.Nm nvlist_destroy , 37.Nm nvlist_error , 38.Nm nvlist_set_error , 39.Nm nvlist_empty , --- 4 unchanged lines hidden (view full) --- 44.Nm nvlist_dump , 45.Nm nvlist_fdump , 46.Nm nvlist_size , 47.Nm nvlist_pack , 48.Nm nvlist_unpack , 49.Nm nvlist_send , 50.Nm nvlist_recv , 51.Nm nvlist_xfer , | 33.Dt NV 9 34.Os 35.Sh NAME 36.Nm nvlist_create , 37.Nm nvlist_destroy , 38.Nm nvlist_error , 39.Nm nvlist_set_error , 40.Nm nvlist_empty , --- 4 unchanged lines hidden (view full) --- 45.Nm nvlist_dump , 46.Nm nvlist_fdump , 47.Nm nvlist_size , 48.Nm nvlist_pack , 49.Nm nvlist_unpack , 50.Nm nvlist_send , 51.Nm nvlist_recv , 52.Nm nvlist_xfer , |
53.Nm nvlist_in_array , |
|
52.Nm nvlist_next , 53.Nm nvlist_add , 54.Nm nvlist_move , 55.Nm nvlist_get , 56.Nm nvlist_take 57.Nd "library for name/value pairs" 58.Sh LIBRARY 59.Lb libnv --- 6 unchanged lines hidden (view full) --- 66.Ft int 67.Fn nvlist_error "const nvlist_t *nvl" 68.Ft void 69.Fn nvlist_set_error "nvlist_t *nvl" "int error" 70.Ft bool 71.Fn nvlist_empty "const nvlist_t *nvl" 72.Ft int 73.Fn nvlist_flags "const nvlist_t *nvl" | 54.Nm nvlist_next , 55.Nm nvlist_add , 56.Nm nvlist_move , 57.Nm nvlist_get , 58.Nm nvlist_take 59.Nd "library for name/value pairs" 60.Sh LIBRARY 61.Lb libnv --- 6 unchanged lines hidden (view full) --- 68.Ft int 69.Fn nvlist_error "const nvlist_t *nvl" 70.Ft void 71.Fn nvlist_set_error "nvlist_t *nvl" "int error" 72.Ft bool 73.Fn nvlist_empty "const nvlist_t *nvl" 74.Ft int 75.Fn nvlist_flags "const nvlist_t *nvl" |
76.Ft bool 77.Fn nvlist_in_array "const nvlist_t *nvl" |
|
74.\" 75.Ft "nvlist_t *" 76.Fn nvlist_clone "const nvlist_t *nvl" 77.\" 78.Ft void 79.Fn nvlist_dump "const nvlist_t *nvl" "int fd" 80.Ft void 81.Fn nvlist_fdump "const nvlist_t *nvl" "FILE *fp" --- 28 unchanged lines hidden (view full) --- 110.Ft bool 111.Fn nvlist_exists_string "const nvlist_t *nvl" "const char *name" 112.Ft bool 113.Fn nvlist_exists_nvlist "const nvlist_t *nvl" "const char *name" 114.Ft bool 115.Fn nvlist_exists_descriptor "const nvlist_t *nvl" "const char *name" 116.Ft bool 117.Fn nvlist_exists_binary "const nvlist_t *nvl" "const char *name" | 78.\" 79.Ft "nvlist_t *" 80.Fn nvlist_clone "const nvlist_t *nvl" 81.\" 82.Ft void 83.Fn nvlist_dump "const nvlist_t *nvl" "int fd" 84.Ft void 85.Fn nvlist_fdump "const nvlist_t *nvl" "FILE *fp" --- 28 unchanged lines hidden (view full) --- 114.Ft bool 115.Fn nvlist_exists_string "const nvlist_t *nvl" "const char *name" 116.Ft bool 117.Fn nvlist_exists_nvlist "const nvlist_t *nvl" "const char *name" 118.Ft bool 119.Fn nvlist_exists_descriptor "const nvlist_t *nvl" "const char *name" 120.Ft bool 121.Fn nvlist_exists_binary "const nvlist_t *nvl" "const char *name" |
122.Ft bool 123.Fn nvlist_exists_bool_array "const nvlist_t *nvl" "const char *name" 124.Ft bool 125.Fn nvlist_exists_number_array "const nvlist_t *nvl" "const char *name" 126.Ft bool 127.Fn nvlist_exists_string_array "const nvlist_t *nvl" "const char *name" 128.Ft bool 129.Fn nvlist_exists_nvlist_array "const nvlist_t *nvl" "const char *name" 130.Ft bool 131.Fn nvlist_exists_descriptor_array "const nvlist_t *nvl" "const char *name" |
|
118.\" 119.Ft void 120.Fn nvlist_add_null "nvlist_t *nvl" "const char *name" 121.Ft void 122.Fn nvlist_add_bool "nvlist_t *nvl" "const char *name" "bool value" 123.Ft void 124.Fn nvlist_add_number "nvlist_t *nvl" "const char *name" "uint64_t value" 125.Ft void 126.Fn nvlist_add_string "nvlist_t *nvl" "const char *name" "const char *value" 127.Ft void 128.Fn nvlist_add_stringf "nvlist_t *nvl" "const char *name" "const char *valuefmt" "..." 129.Ft void 130.Fn nvlist_add_stringv "nvlist_t *nvl" "const char *name" "const char *valuefmt" "va_list valueap" 131.Ft void 132.Fn nvlist_add_nvlist "nvlist_t *nvl" "const char *name" "const nvlist_t *value" 133.Ft void 134.Fn nvlist_add_descriptor "nvlist_t *nvl" "const char *name" "int value" 135.Ft void 136.Fn nvlist_add_binary "nvlist_t *nvl" "const char *name" "const void *value" "size_t size" | 132.\" 133.Ft void 134.Fn nvlist_add_null "nvlist_t *nvl" "const char *name" 135.Ft void 136.Fn nvlist_add_bool "nvlist_t *nvl" "const char *name" "bool value" 137.Ft void 138.Fn nvlist_add_number "nvlist_t *nvl" "const char *name" "uint64_t value" 139.Ft void 140.Fn nvlist_add_string "nvlist_t *nvl" "const char *name" "const char *value" 141.Ft void 142.Fn nvlist_add_stringf "nvlist_t *nvl" "const char *name" "const char *valuefmt" "..." 143.Ft void 144.Fn nvlist_add_stringv "nvlist_t *nvl" "const char *name" "const char *valuefmt" "va_list valueap" 145.Ft void 146.Fn nvlist_add_nvlist "nvlist_t *nvl" "const char *name" "const nvlist_t *value" 147.Ft void 148.Fn nvlist_add_descriptor "nvlist_t *nvl" "const char *name" "int value" 149.Ft void 150.Fn nvlist_add_binary "nvlist_t *nvl" "const char *name" "const void *value" "size_t size" |
151.Ft void 152.Fn nvlist_add_bool_array "nvlist_t *nvl" "const char *name" "const bool *value" "size_t nitems" 153. 154.Ft void 155.Fn nvlist_add_number_array "nvlist_t *nvl" "const char *name" "const uint64_t *value" "size_t nitems" 156. 157.Ft void 158.Fn nvlist_add_string_array "nvlist_t *nvl" "const char *name" "const char * const * value" "size_t nitems" 159. 160.Ft void 161.Fn nvlist_add_nvlist_array "nvlist_t *nvl" "const char *name" "const nvlist_t * const * value" "size_t nitems" 162. 163.Ft void 164.Fn nvlist_add_descriptor_array "nvlist_t *nvl" "const char *name" "const int *value" "size_t nitems" |
|
137.\" 138.Ft void 139.Fn nvlist_move_string "nvlist_t *nvl" "const char *name" "char *value" 140.Ft void 141.Fn nvlist_move_nvlist "nvlist_t *nvl" "const char *name" "nvlist_t *value" 142.Ft void 143.Fn nvlist_move_descriptor "nvlist_t *nvl" "const char *name" "int value" 144.Ft void 145.Fn nvlist_move_binary "nvlist_t *nvl" "const char *name" "void *value" "size_t size" | 165.\" 166.Ft void 167.Fn nvlist_move_string "nvlist_t *nvl" "const char *name" "char *value" 168.Ft void 169.Fn nvlist_move_nvlist "nvlist_t *nvl" "const char *name" "nvlist_t *value" 170.Ft void 171.Fn nvlist_move_descriptor "nvlist_t *nvl" "const char *name" "int value" 172.Ft void 173.Fn nvlist_move_binary "nvlist_t *nvl" "const char *name" "void *value" "size_t size" |
174.Ft void 175.Fn nvlist_move_bool_array "nvlist_t *nvl" "const char *name" "bool *value" "size_t nitems" 176. 177.Ft void 178.Fn nvlist_move_number_array "nvlist_t *nvl" "const char *name" "uint64_t *value" "size_t nitems" 179. 180.Ft void 181.Fn nvlist_move_string_array "nvlist_t *nvl" "const char *name" "char **value" "size_t nitems" 182. 183.Ft void 184.Fn nvlist_move_nvlist_array "nvlist_t *nvl" "const char *name" "nvlist_t **value" "size_t nitems" 185. 186.Ft void 187.Fn nvlist_move_descriptor_array "nvlist_t *nvl" "const char *name" "int *value" "size_t nitems" |
|
146.\" 147.Ft bool 148.Fn nvlist_get_bool "const nvlist_t *nvl" "const char *name" 149.Ft uint64_t 150.Fn nvlist_get_number "const nvlist_t *nvl" "const char *name" 151.Ft "const char *" 152.Fn nvlist_get_string "const nvlist_t *nvl" "const char *name" 153.Ft "const nvlist_t *" 154.Fn nvlist_get_nvlist "const nvlist_t *nvl" "const char *name" 155.Ft int 156.Fn nvlist_get_descriptor "const nvlist_t *nvl" "const char *name" 157.Ft "const void *" 158.Fn nvlist_get_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep" | 188.\" 189.Ft bool 190.Fn nvlist_get_bool "const nvlist_t *nvl" "const char *name" 191.Ft uint64_t 192.Fn nvlist_get_number "const nvlist_t *nvl" "const char *name" 193.Ft "const char *" 194.Fn nvlist_get_string "const nvlist_t *nvl" "const char *name" 195.Ft "const nvlist_t *" 196.Fn nvlist_get_nvlist "const nvlist_t *nvl" "const char *name" 197.Ft int 198.Fn nvlist_get_descriptor "const nvlist_t *nvl" "const char *name" 199.Ft "const void *" 200.Fn nvlist_get_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep" |
201.Ft "const bool *" 202.Fn nvlist_get_bool_array "const nvlist_t *nvl" "const char *name" "size_t *nitems" 203.Ft "const uint64_t *" 204.Fn nvlist_get_number "const nvlist_t *nvl" "const char *name" "size_t *nitems" 205.Ft "const char * const *" 206.Fn nvlist_get_string "const nvlist_t *nvl" "const char *name" "size_t *nitems" 207.Ft "const nvlist_t * const *" 208.Fn nvlist_get_nvlist "const nvlist_t *nvl" "const char *name" "size_t *nitems" 209.Ft "const int *" 210.Fn nvlist_get_descriptor_array "const nvlist_t *nvl" "const char *name" "size_t *nitems" |
|
159.Ft "const nvlist_t *" 160.Fn nvlist_get_parent "const nvlist_t *nvl" "void **cookiep" | 211.Ft "const nvlist_t *" 212.Fn nvlist_get_parent "const nvlist_t *nvl" "void **cookiep" |
213.Ft "const nvlist_t *" 214.Fn nvlist_get_array_next "const nvlist_t *nvl" 215.Ft "const nvlist_t *" 216.Fn nvlist_get_pararr "const nvlist_t *nvl" "void **cookiep" |
|
161.\" 162.Ft bool 163.Fn nvlist_take_bool "nvlist_t *nvl" "const char *name" 164.Ft uint64_t 165.Fn nvlist_take_number "nvlist_t *nvl" "const char *name" 166.Ft "char *" 167.Fn nvlist_take_string "nvlist_t *nvl" "const char *name" 168.Ft "nvlist_t *" 169.Fn nvlist_take_nvlist "nvlist_t *nvl" "const char *name" 170.Ft int 171.Fn nvlist_take_descriptor "nvlist_t *nvl" "const char *name" 172.Ft "void *" 173.Fn nvlist_take_binary "nvlist_t *nvl" "const char *name" "size_t *sizep" | 217.\" 218.Ft bool 219.Fn nvlist_take_bool "nvlist_t *nvl" "const char *name" 220.Ft uint64_t 221.Fn nvlist_take_number "nvlist_t *nvl" "const char *name" 222.Ft "char *" 223.Fn nvlist_take_string "nvlist_t *nvl" "const char *name" 224.Ft "nvlist_t *" 225.Fn nvlist_take_nvlist "nvlist_t *nvl" "const char *name" 226.Ft int 227.Fn nvlist_take_descriptor "nvlist_t *nvl" "const char *name" 228.Ft "void *" 229.Fn nvlist_take_binary "nvlist_t *nvl" "const char *name" "size_t *sizep" |
230.Ft "bool *" 231.Fn nvlist_take_bool_array "nvlist_t *nvl" "const char *name" "size_t *nitems" 232.Ft "uint64_t **" 233.Fn nvlist_take_number "nvlist_t *nvl" "const char *name" "size_t *nitems" 234.Ft "char **" 235.Fn nvlist_take_string "nvlist_t *nvl" "const char *name" "size_t *nitems" 236.Ft "nvlist_t **" 237.Fn nvlist_take_nvlist "nvlist_t *nvl" "const char *name" "size_t *nitems" 238.Ft "int *" 239.Fn nvlist_take_descriptor "nvlist_t *nvl" "const char *name" "size_t *nitems" |
|
174.\" 175.Ft void 176.Fn nvlist_free "nvlist_t *nvl" "const char *name" 177.Ft void 178.Fn nvlist_free_type "nvlist_t *nvl" "const char *name" "int type" 179.\" 180.Ft void 181.Fn nvlist_free_null "nvlist_t *nvl" "const char *name" --- 4 unchanged lines hidden (view full) --- 186.Ft void 187.Fn nvlist_free_string "nvlist_t *nvl" "const char *name" 188.Ft void 189.Fn nvlist_free_nvlist "nvlist_t *nvl" "const char *name" 190.Ft void 191.Fn nvlist_free_descriptor "nvlist_t *nvl" "const char *name" 192.Ft void 193.Fn nvlist_free_binary "nvlist_t *nvl" "const char *name" | 240.\" 241.Ft void 242.Fn nvlist_free "nvlist_t *nvl" "const char *name" 243.Ft void 244.Fn nvlist_free_type "nvlist_t *nvl" "const char *name" "int type" 245.\" 246.Ft void 247.Fn nvlist_free_null "nvlist_t *nvl" "const char *name" --- 4 unchanged lines hidden (view full) --- 252.Ft void 253.Fn nvlist_free_string "nvlist_t *nvl" "const char *name" 254.Ft void 255.Fn nvlist_free_nvlist "nvlist_t *nvl" "const char *name" 256.Ft void 257.Fn nvlist_free_descriptor "nvlist_t *nvl" "const char *name" 258.Ft void 259.Fn nvlist_free_binary "nvlist_t *nvl" "const char *name" |
260.Ft void 261.Fn nvlist_free_bool_array "nvlist_t *nvl" "const char *name" 262.Ft void 263.Fn nvlist_free_number_array "nvlist_t *nvl" "const char *name" 264.Ft void 265.Fn nvlist_free_string_array "nvlist_t *nvl" "const char *name" 266.Ft void 267.Fn nvlist_free_nvlist_array "nvlist_t *nvl" "const char *name" 268.Ft void 269.Fn nvlist_free_descriptor_array "nvlist_t *nvl" "const char *name" |
|
194.Sh DESCRIPTION 195The 196.Nm libnv 197library allows to easily manage name value pairs as well as send and receive 198them over sockets. 199A group (list) of name value pairs is called an 200.Nm nvlist . 201The API supports the following data types: --- 14 unchanged lines hidden (view full) --- 216The value is a nested nvlist. 217.It Sy descriptor ( NV_TYPE_DESCRIPTOR ) 218The value is a file descriptor. 219Note that file descriptors can be sent only over 220.Xr unix 4 221domain sockets. 222.It Sy binary ( NV_TYPE_BINARY ) 223The value is a binary buffer. | 270.Sh DESCRIPTION 271The 272.Nm libnv 273library allows to easily manage name value pairs as well as send and receive 274them over sockets. 275A group (list) of name value pairs is called an 276.Nm nvlist . 277The API supports the following data types: --- 14 unchanged lines hidden (view full) --- 292The value is a nested nvlist. 293.It Sy descriptor ( NV_TYPE_DESCRIPTOR ) 294The value is a file descriptor. 295Note that file descriptors can be sent only over 296.Xr unix 4 297domain sockets. 298.It Sy binary ( NV_TYPE_BINARY ) 299The value is a binary buffer. |
300.It Sy bool array ( NV_TYPE_BOOL_ARRAY ) 301The value is an array of boolean values. 302.It Sy number array ( NV_TYPE_NUMBER_ARRAY ) 303The value is an array of numbers, each stored as 304.Vt uint64_t . 305.It Sy string array ( NV_TYPE_STRING_ARRAY ) 306The value is an array of C strings. 307.It Sy nvlist array ( NV_TYPE_NVLIST_ARRAY ) 308The value is an array of nvlists. 309When an nvlist is added to an array, it becomes part of the primary nvlist. 310Traversing these arrays can be done using the 311.Fn nvlist_get_array_next 312and 313.Fn nvlist_get_pararr 314functions. 315.It Sy descriptor array ( NV_TYPE_DESCRIPTOR_ARRAY ) 316The value is an array of files descriptors. |
|
224.El 225.Pp 226The 227.Fn nvlist_create 228function allocates memory and initializes an nvlist. 229.Pp 230The following flag can be provided: 231.Pp --- 43 unchanged lines hidden (view full) --- 275.Pp 276The 277.Fn nvlist_flags 278function returns flags used to create the nvlist with the 279.Fn nvlist_create 280function. 281.Pp 282The | 317.El 318.Pp 319The 320.Fn nvlist_create 321function allocates memory and initializes an nvlist. 322.Pp 323The following flag can be provided: 324.Pp --- 43 unchanged lines hidden (view full) --- 368.Pp 369The 370.Fn nvlist_flags 371function returns flags used to create the nvlist with the 372.Fn nvlist_create 373function. 374.Pp 375The |
376.Fn nvlist_in_array 377function returns 378.Dv true 379if 380.Fa nvl 381is part of an array that is a member of another nvlist. 382.Pp 383The |
|
283.Fn nvlist_clone 284functions clones the given nvlist. 285The clone shares no resources with its origin. 286This also means that all file descriptors that are part of the nvlist will be 287duplicated with the 288.Xr dup 2 289system call before placing them in the clone. 290.Pp --- 150 unchanged lines hidden (view full) --- 441.Pp 442The 443.Fn nvlist_exists_null , 444.Fn nvlist_exists_bool , 445.Fn nvlist_exists_number , 446.Fn nvlist_exists_string , 447.Fn nvlist_exists_nvlist , 448.Fn nvlist_exists_descriptor , | 384.Fn nvlist_clone 385functions clones the given nvlist. 386The clone shares no resources with its origin. 387This also means that all file descriptors that are part of the nvlist will be 388duplicated with the 389.Xr dup 2 390system call before placing them in the clone. 391.Pp --- 150 unchanged lines hidden (view full) --- 542.Pp 543The 544.Fn nvlist_exists_null , 545.Fn nvlist_exists_bool , 546.Fn nvlist_exists_number , 547.Fn nvlist_exists_string , 548.Fn nvlist_exists_nvlist , 549.Fn nvlist_exists_descriptor , |
449.Fn nvlist_exists_binary | 550.Fn nvlist_exists_binary , 551.Fn nvlist_exists_bool_array , 552.Fn nvlist_exists_number_array , 553.Fn nvlist_exists_string_array , 554.Fn nvlist_exists_nvlist_array , 555.Fn nvlist_exists_descriptor_array |
450functions return 451.Dv true 452if element of the given name and the given type determined by the function name 453exists or 454.Dv false 455otherwise. 456The nvlist must not be in error state. 457.Pp 458The 459.Fn nvlist_add_null , 460.Fn nvlist_add_bool , 461.Fn nvlist_add_number , 462.Fn nvlist_add_string , 463.Fn nvlist_add_stringf , 464.Fn nvlist_add_stringv , 465.Fn nvlist_add_nvlist , 466.Fn nvlist_add_descriptor , | 556functions return 557.Dv true 558if element of the given name and the given type determined by the function name 559exists or 560.Dv false 561otherwise. 562The nvlist must not be in error state. 563.Pp 564The 565.Fn nvlist_add_null , 566.Fn nvlist_add_bool , 567.Fn nvlist_add_number , 568.Fn nvlist_add_string , 569.Fn nvlist_add_stringf , 570.Fn nvlist_add_stringv , 571.Fn nvlist_add_nvlist , 572.Fn nvlist_add_descriptor , |
467.Fn nvlist_add_binary | 573.Fn nvlist_add_binary , 574.Fn nvlist_add_bool_array , 575.Fn nvlist_add_number_array , 576.Fn nvlist_add_string_array , 577.Fn nvlist_add_nvlist_array , 578.Fn nvlist_add_descriptor_array |
468functions add element to the given nvlist. 469When adding string or binary buffor the functions will allocate memory 470and copy the data over. 471When adding nvlist, the nvlist will be cloned and clone will be added. 472When adding descriptor, the descriptor will be duplicated using the 473.Xr dup 2 474system call and the new descriptor will be added. | 579functions add element to the given nvlist. 580When adding string or binary buffor the functions will allocate memory 581and copy the data over. 582When adding nvlist, the nvlist will be cloned and clone will be added. 583When adding descriptor, the descriptor will be duplicated using the 584.Xr dup 2 585system call and the new descriptor will be added. |
586The array functions will fail if there are any 587.Dv NULL 588elements in the array, or if the array pointer is 589.Dv NULL . |
|
475If an error occurs while adding new element, internal error is set which can be 476examined using the 477.Fn nvlist_error 478function. 479.Pp 480The 481.Fn nvlist_move_string , 482.Fn nvlist_move_nvlist , 483.Fn nvlist_move_descriptor , | 590If an error occurs while adding new element, internal error is set which can be 591examined using the 592.Fn nvlist_error 593function. 594.Pp 595The 596.Fn nvlist_move_string , 597.Fn nvlist_move_nvlist , 598.Fn nvlist_move_descriptor , |
484.Fn nvlist_move_binary | 599.Fn nvlist_move_binary , 600.Fn nvlist_move_bool_array , 601.Fn nvlist_move_number_array , 602.Fn nvlist_move_string_array , 603.Fn nvlist_move_nvlist_array , 604.Fn nvlist_move_descriptor_array |
485functions add new element to the given nvlist, but unlike 486.Fn nvlist_add_<type> 487functions they will consume the given resource. | 605functions add new element to the given nvlist, but unlike 606.Fn nvlist_add_<type> 607functions they will consume the given resource. |
608In the case of strings, descriptors, or nvlists every elements must be 609unique, or it could cause a double free. 610The array functions will fail if there are any 611.Dv NULL 612elements, or if the array pointer is 613.Dv NULL . |
|
488If an error occurs while adding new element, the resource is destroyed and 489internal error is set which can be examined using the 490.Fn nvlist_error 491function. 492.Pp 493The 494.Fn nvlist_get_bool , 495.Fn nvlist_get_number , 496.Fn nvlist_get_string , 497.Fn nvlist_get_nvlist , 498.Fn nvlist_get_descriptor , | 614If an error occurs while adding new element, the resource is destroyed and 615internal error is set which can be examined using the 616.Fn nvlist_error 617function. 618.Pp 619The 620.Fn nvlist_get_bool , 621.Fn nvlist_get_number , 622.Fn nvlist_get_string , 623.Fn nvlist_get_nvlist , 624.Fn nvlist_get_descriptor , |
499.Fn nvlist_get_binary 500functions allow to obtain value of the given name. 501In case of string, nvlist, descriptor or binary, returned resource should 502not be modified - it still belongs to the nvlist. 503If element of the given name does not exist, the program will be aborted. 504To avoid that the caller should check for existence before trying to obtain 505the value or use | 625.Fn nvlist_get_binary , 626.Fn nvlist_get_bool_array , 627.Fn nvlist_get_number_array , 628.Fn nvlist_get_string_array , 629.Fn nvlist_get_nvlist_array , 630.Fn nvlist_get_descriptor_array 631functions return the value that corresponds to the given key name. 632In the case of strings, nvlists, descriptors, binary, or arrays, the returned 633resource should not be modified - they still belong to the nvlist. 634If an element of the given name does not exist, the program will be aborted. 635To avoid this, the caller should check for the existence of the name before 636trying to obtain the value, or use the |
506.Xr dnvlist 3 | 637.Xr dnvlist 3 |
507extension, which allows to provide default value for a missing element. | 638extension, which can provide a default value in the case of a missing element. |
508The nvlist must not be in error state. 509.Pp 510The 511.Fn nvlist_get_parent | 639The nvlist must not be in error state. 640.Pp 641The 642.Fn nvlist_get_parent |
512function allows to obtain the parent nvlist from the nested nvlist. | 643function returns the parent nvlist of the nested nvlist. |
513.Pp 514The | 644.Pp 645The |
646.Fn nvlist_get_array_next 647function returns the next element from the array or 648.Dv NULL 649if the nvlist is not in array or it is the last element. 650Note that 651.Fn nvlist_get_array_next 652only works if you added the nvlist array using the 653.Fn nvlist_move_nvlist_array 654or 655.Fn nvlist_add_nvlist_array 656functions. 657.Pp 658The 659.Fn nvlist_get_pararr 660function returns the next element in the array, or if not available 661the parent of the nested nvlist. 662.Pp 663The |
|
515.Fn nvlist_take_bool , 516.Fn nvlist_take_number , 517.Fn nvlist_take_string , 518.Fn nvlist_take_nvlist , 519.Fn nvlist_take_descriptor , | 664.Fn nvlist_take_bool , 665.Fn nvlist_take_number , 666.Fn nvlist_take_string , 667.Fn nvlist_take_nvlist , 668.Fn nvlist_take_descriptor , |
520.Fn nvlist_take_binary | 669.Fn nvlist_take_binary , 670.Fn nvlist_take_bool_array , 671.Fn nvlist_take_number_array , 672.Fn nvlist_take_string_array , 673.Fn nvlist_take_nvlist_array , 674.Fn nvlist_take_descriptor_array |
521functions return value associated with the given name and remove the element 522from the nvlist. 523In case of string and binary values, the caller is responsible for free returned 524memory using the 525.Xr free 3 526function. 527In case of nvlist, the caller is responsible for destroying returned nvlist 528using the 529.Fn nvlist_destroy 530function. 531In case of descriptor, the caller is responsible for closing returned descriptor 532using the 533.Fn close 2 534system call. | 675functions return value associated with the given name and remove the element 676from the nvlist. 677In case of string and binary values, the caller is responsible for free returned 678memory using the 679.Xr free 3 680function. 681In case of nvlist, the caller is responsible for destroying returned nvlist 682using the 683.Fn nvlist_destroy 684function. 685In case of descriptor, the caller is responsible for closing returned descriptor 686using the 687.Fn close 2 688system call. |
535If element of the given name does not exist, the program will be aborted. 536To avoid that the caller should check for existence before trying to obtain 537the value or use | 689If an element of the given name does not exist, the program will be aborted. 690To avoid that the caller should check for the existence of the given name 691before trying to obtain the value, or use the |
538.Xr dnvlist 3 | 692.Xr dnvlist 3 |
539extension, which allows to provide default value for a missing element. | 693extension, which can provide a default value in the case of a missing element. 694In the case of an array of strings or binary values, the caller is responsible 695for freeing every element of the array using the 696.Xr free 3 697function. 698In the case of an array of nvlists, the caller is responsible for destroying 699every element of array using the 700.Fn nvlist_destroy 701function. 702In the case of descriptors, the caller is responsible for closing every 703element of array using the 704.Fn close 2 705system call. 706In every case involving an array, the caller must also free the pointer to 707the array using the 708.Xr free 3 709function. |
540The nvlist must not be in error state. 541.Pp 542The 543.Fn nvlist_free 544function removes element of the given name from the nvlist (besides of its type) 545and frees all resources associated with it. 546If element of the given name does not exist, the program will be aborted. 547The nvlist must not be in error state. --- 8 unchanged lines hidden (view full) --- 556.Pp 557The 558.Fn nvlist_free_null , 559.Fn nvlist_free_bool , 560.Fn nvlist_free_number , 561.Fn nvlist_free_string , 562.Fn nvlist_free_nvlist , 563.Fn nvlist_free_descriptor , | 710The nvlist must not be in error state. 711.Pp 712The 713.Fn nvlist_free 714function removes element of the given name from the nvlist (besides of its type) 715and frees all resources associated with it. 716If element of the given name does not exist, the program will be aborted. 717The nvlist must not be in error state. --- 8 unchanged lines hidden (view full) --- 726.Pp 727The 728.Fn nvlist_free_null , 729.Fn nvlist_free_bool , 730.Fn nvlist_free_number , 731.Fn nvlist_free_string , 732.Fn nvlist_free_nvlist , 733.Fn nvlist_free_descriptor , |
564.Fn nvlist_free_binary | 734.Fn nvlist_free_binary , 735.Fn nvlist_free_bool_array , 736.Fn nvlist_free_number_array , 737.Fn nvlist_free_string_array , 738.Fn nvlist_free_nvlist_array , 739.Fn nvlist_free_descriptor_array |
565functions remove element of the given name and the given type determined by the 566function name from the nvlist and free all resources associated with it. 567If element of the given name and the given type does not exist, the program 568will be aborted. 569The nvlist must not be in error state. 570.Sh EXAMPLES 571The following example demonstrates how to prepare an nvlist and send it over 572.Xr unix 4 --- 101 unchanged lines hidden (view full) --- 674 while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { 675 if (type == NV_TYPE_NVLIST) { 676 nvl = nvlist_get_nvlist(nvl, name); 677 cookie = NULL; 678 } 679 } 680} while ((nvl = nvlist_get_parent(nvl, &cookie)) != NULL); 681.Ed | 740functions remove element of the given name and the given type determined by the 741function name from the nvlist and free all resources associated with it. 742If element of the given name and the given type does not exist, the program 743will be aborted. 744The nvlist must not be in error state. 745.Sh EXAMPLES 746The following example demonstrates how to prepare an nvlist and send it over 747.Xr unix 4 --- 101 unchanged lines hidden (view full) --- 849 while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { 850 if (type == NV_TYPE_NVLIST) { 851 nvl = nvlist_get_nvlist(nvl, name); 852 cookie = NULL; 853 } 854 } 855} while ((nvl = nvlist_get_parent(nvl, &cookie)) != NULL); 856.Ed |
857.Pp 858Iterating over every nested nvlist and every nvlist element: 859.Bd -literal 860nvlist_t *nvl; 861const nvlist_t * const *array; 862const char *name; 863void *cookie; 864int type; 865 866nvl = nvlist_recv(sock, 0); 867if (nvl == null) 868 err(1, "nvlist_recv() failed"); 869 870cookie = null; 871do { 872 while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { 873 if (type == NV_TYPE_NVLIST) { 874 nvl = nvlist_get_nvlist(nvl, name); 875 cookie = NULL; 876 } else if (type == NV_TYPE_NVLIST_ARRAY) { 877 nvl = nvlist_get_nvlist_array(nvl, name, NULL)[0]; 878 cookie = NULL; 879 } 880 } 881} while ((nvl = nvlist_get_pararr(nvl, &cookie)) != NULL); 882.Ed 883.Pp 884Or alternatively: 885.Bd -literal 886nvlist_t *nvl, *tmp; 887const nvlist_t * const *array; 888const char *name; 889void *cookie; 890int type; 891 892nvl = nvlist_recv(sock, 0); 893if (nvl == null) 894 err(1, "nvlist_recv() failed"); 895 896cooke = NULL; 897tmp = nvl; 898do { 899 do { 900 nvl = tmp; 901 while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { 902 if (type == NV_TYPE_NVLIST) { 903 nvl = nvlist_get_nvlist(nvl, 904 name); 905 cookie = NULL; 906 } else if (type == NV_TYPE_NVLIST_ARRAY) { 907 nvl = nvlist_get_nvlist_array(nvl, name, 908 NULL)[0]; 909 cookie = NULL; 910 } 911 } 912 cookie = NULL; 913 } while ((tmp = nvlist_get_array_next(nvl)) != NULL); 914} while ((tmp = nvlist_get_parent(nvl, &cookie)) != NULL); 915.Ed |
|
682.Sh SEE ALSO 683.Xr close 2 , 684.Xr dup 2 , 685.Xr open 2 , 686.Xr err 3 , 687.Xr free 3 , 688.Xr printf 3 , 689.Xr unix 4 --- 12 unchanged lines hidden --- | 916.Sh SEE ALSO 917.Xr close 2 , 918.Xr dup 2 , 919.Xr open 2 , 920.Xr err 3 , 921.Xr free 3 , 922.Xr printf 3 , 923.Xr unix 4 --- 12 unchanged lines hidden --- |