NVLIST_ALLOC(3NVPAIR) Name-value Pair Library Functions NVLIST_ALLOC(3NVPAIR) NNAAMMEE nvlist_alloc, nvlist_free, nvlist_size, nvlist_pack, nvlist_unpack, nvlist_dup, nvlist_merge, nvlist_xalloc, nvlist_xpack, nvlist_xunpack, nvlist_xdup, nvlist_lookup_nv_alloc, nv_alloc_init, nv_alloc_reset, nv_alloc_fini - manage a name-value pair list SSYYNNOOPPSSIISS cccc [ _f_l_a_g... ] _f_i_l_e... --llnnvvppaaiirr [ _l_i_b_r_a_r_y... ] #include iinntt nnvvlliisstt__aalllloocc(nnvvlliisstt__tt ****_n_v_l_p, uuiinntt__tt _n_v_f_l_a_g, iinntt _f_l_a_g); iinntt nnvvlliisstt__xxaalllloocc(nnvvlliisstt__tt ****_n_v_l_p, uuiinntt__tt _n_v_f_l_a_g, nnvv__aalllloocc__tt ** _n_v_a); vvooiidd nnvvlliisstt__ffrreeee(nnvvlliisstt__tt **_n_v_l); iinntt nnvvlliisstt__ssiizzee(nnvvlliisstt__tt **_n_v_l, ssiizzee__tt **_s_i_z_e, iinntt _e_n_c_o_d_i_n_g); iinntt nnvvlliisstt__ppaacckk(nnvvlliisstt__tt **_n_v_l, cchhaarr ****_b_u_f_p, ssiizzee__tt **_b_u_f_l_e_n, iinntt _e_n_c_o_d_i_n_g, iinntt _f_l_a_g); iinntt nnvvlliisstt__xxppaacckk(nnvvlliisstt__tt **_n_v_l, cchhaarr ****_b_u_f_p, ssiizzee__tt **_b_u_f_l_e_n, iinntt _e_n_c_o_d_i_n_g, nnvv__aalllloocc__tt ** _n_v_a); iinntt nnvvlliisstt__uunnppaacckk(cchhaarr **_b_u_f, ssiizzee__tt _b_u_f_l_e_n, nnvvlliisstt__tt ****_n_v_l_p, iinntt _f_l_a_g); iinntt nnvvlliisstt__xxuunnppaacckk(cchhaarr **_b_u_f, ssiizzee__tt _b_u_f_l_e_n, nnvvlliisstt__tt ****_n_v_l_p, nnvv__aalllloocc__tt ** _n_v_a); iinntt nnvvlliisstt__dduupp(nnvvlliisstt__tt **_n_v_l, nnvvlliisstt__tt ****_n_v_l_p, iinntt _f_l_a_g); iinntt nnvvlliisstt__xxdduupp(nnvvlliisstt__tt **_n_v_l, nnvvlliisstt__tt ****_n_v_l_p, nnvv__aalllloocc__tt ** _n_v_a); iinntt nnvvlliisstt__mmeerrggee(nnvvlliisstt__tt **_d_s_t, nnvvlliisstt__tt **_n_v_l, iinntt _f_l_a_g); nnvv__aalllloocc__tt ** nnvvlliisstt__llooookkuupp__nnvv__aalllloocc(nnvvlliisstt__tt **_n_v_l); iinntt nnvv__aalllloocc__iinniitt(nnvv__aalllloocc__tt **_n_v_a, ccoonnsstt nnvv__aalllloocc__ooppss__tt **_n_v_o, //** _a_r_g_s */ ...); vvooiidd nnvv__aalllloocc__rreesseett(nnvv__aalllloocc__tt **_n_v_a); vvooiidd nnvv__aalllloocc__ffiinnii(nnvv__aalllloocc__tt **_n_v_a); PPAARRAAMMEETTEERRSS _n_v_l_p Address of a pointer to nnvvlliisstt__tt. _n_v_f_l_a_g Specify bit fields defining nnvvlliisstt properties: NNVV__UUNNIIQQUUEE__NNAAMMEE The nnvvppaaiirr names are unique. NNVV__UUNNIIQQUUEE__NNAAMMEE__TTYYPPEE Name-data type combination is unique. _f_l_a_g Specify 0. Reserved for future use. _n_v_l The nnvvlliisstt__tt to be processed. _d_s_t The destination nnvvlliisstt__tt. _s_i_z_e Pointer to buffer to contain the encoded size. _b_u_f_p Address of buffer to pack nnvvlliisstt into. Must be 8-byte aligned. If _N_U_L_L, library will allocate memory. _b_u_f Buffer containing packed nnvvlliisstt. _b_u_f_l_e_n Size of buffer _b_u_f_p or _b_u_f points to. _e_n_c_o_d_i_n_g Encoding method for packing. _n_v_o Pluggable allocator operations pointer (nnvv__aalllloocc__ooppss__tt). _n_v_a A pointer to an nnvv__aalllloocc__tt structure to be used for the specified nnvvlliisstt__tt. DDEESSCCRRIIPPTTIIOONN LLiisstt MMaanniippuullaattiioonn The nnvvlliisstt__aalllloocc(()) function allocates a new name-value pair list and updates _n_v_l_p to point to the handle. The _n_v_f_l_a_g argument specifies nnvvlliisstt properties to remain persistent across packing, unpacking, and duplication. If NNVV__UUNNIIQQUUEE__NNAAMMEE was specified for _n_v_f_l_a_g, existing nvpairs with matching names are removed before the new nvpair is added. If NNVV__UUNNIIQQUUEE__NNAAMMEE__TTYYPPEE was specified for _n_v_f_l_a_g, existing nvpairs with matching names and data types are removed before the new nvpair is added. See nnvvlliisstt__aadddd__bbyyttee(3NVPAIR) for more information. The nnvvlliisstt__xxaalllloocc(()) function is identical to nnvvlliisstt__aalllloocc(()) except that nnvvlliisstt__xxaalllloocc(()) can use a different allocator, as described in the Pluggable Allocators section. The nnvvlliisstt__ffrreeee(()) function frees a name-value pair list. If _n_v_l is a null pointer, no action occurs. The nnvvlliisstt__ssiizzee(()) function returns the minimum size of a contiguous buffer large enough to pack _n_v_l. The _e_n_c_o_d_i_n_g parameter specifies the method of encoding when packing _n_v_l. Supported encoding methods are: NNVV__EENNCCOODDEE__NNAATTIIVVEE Straight bbccooppyy(()) as described in bbccooppyy(3C). NNVV__EENNCCOODDEE__XXDDRR Use XDR encoding, suitable for sending to another host. The nnvvlliisstt__ppaacckk(()) function packs _n_v_l into contiguous memory starting at *_b_u_f_p. The _e_n_c_o_d_i_n_g parameter specifies the method of encoding (see above). o If *_b_u_f_p is not _N_U_L_L, *_b_u_f_p is expected to be a caller- allocated buffer of size *_b_u_f_l_e_n. o If *_b_u_f_p is _N_U_L_L, the library will allocate memory and update *_b_u_f_p to point to the memory and update *_b_u_f_l_e_n to contain the size of the allocated memory. The nnvvlliisstt__xxppaacckk(()) function is identical to nnvvlliisstt__ppaacckk(()) except that nnvvlliisstt__xxppaacckk(()) can use a different allocator. The nnvvlliisstt__uunnppaacckk(()) function takes a buffer with a packed nnvvlliisstt__tt and unpacks it into a searchable nnvvlliisstt__tt. The library allocates memory for nnvvlliisstt__tt. The caller is responsible for freeing the memory by calling nnvvlliisstt__ffrreeee(()). The nnvvlliisstt__xxuunnppaacckk(()) function is identical to nnvvlliisstt__uunnppaacckk(()) except that nnvvlliisstt__xxuunnppaacckk(()) can use a different allocator. The nnvvlliisstt__dduupp(()) function makes a copy of _n_v_l and updates _n_v_l_p to point to the copy. The nnvvlliisstt__xxdduupp(()) function is identical to nnvvlliisstt__dduupp(()) except that nnvvlliisstt__xxdduupp(()) can use a different allocator. The nnvvlliisstt__mmeerrggee(()) function adds copies of all name-value pairs from _n_v_l to _d_s_t. Name-value pairs in _d_s_t are replaced with name-value pairs from _n_v_l that have identical names (if _d_s_t has the type NNVV__UUNNIIQQUUEE__NNAAMMEE) or identical names and types (if _d_s_t has the type NNVV__UUNNIIQQUUEE__NNAAMMEE__TTYYPPEE). The nnvvlliisstt__llooookkuupp__nnvv__aalllloocc(()) function retrieves the pointer to the allocator that was used when manipulating a name-value pair list. PPlluuggggaabbllee AAllllooccaattoorrss UUssiinngg PPlluuggggaabbllee AAllllooccaattoorrss The nnvv__aalllloocc__iinniitt(()), nnvv__aalllloocc__rreesseett(()) and nnvv__aalllloocc__ffiinnii(()) functions provide an interface to specify the allocator to be used when manipulating a name-value pair list. The nnvv__aalllloocc__iinniitt(()) function determines the allocator properties and puts them into the _n_v_a argument. The application must specify the _n_v___a_r_g and _n_v_o arguments and an optional variable argument list. The optional arguments are passed to the (*nnvv__aaoo__iinniitt(())) function. The _n_v_a argument must be passed to nnvvlliisstt__xxaalllloocc(()), nnvvlliisstt__xxppaacckk(()), nnvvlliisstt__xxuunnppaacckk(()) and nnvvlliisstt__xxdduupp(()). The nnvv__aalllloocc__rreesseett(()) function is responsible for resetting the allocator properties to the data specified by nnvv__aalllloocc__iinniitt(()). When no (*nnvv__aaoo__rreesseett(())) function is specified, nnvv__aalllloocc__rreesseett(()) has no effect. The nnvv__aalllloocc__ffiinnii(()) function destroys the allocator properties determined by nnvv__aalllloocc__iinniitt(()). When a (*nnvv__aaoo__ffiinnii(())) function is specified, it is called from nnvv__aalllloocc__ffiinnii(()). The disposition of the allocated objects and the memory used to store them is left to the allocator implementation. The nnvv__aalllloocc__nnoosslleeeepp nnvv__aalllloocc__tt can be used with nnvvlliisstt__xxaalllloocc(()) to mimic the behavior of nnvvlliisstt__aalllloocc(()). The nvpair allocator framework provides a pointer to the operation structure of a fixed buffer allocator. This allocator, nnvv__ffiixxeedd__ooppss, uses a pre-allocated buffer for memory allocations. It is intended primarily for kernel use and is described on nnvvlliisstt__aalllloocc(9F). An example program that uses the pluggable allocator functionality is provided on nnvvlliisstt__aalllloocc(9F). CCrreeaattiinngg PPlluuggggaabbllee AAllllooccaattoorrss Any producer of name-value pairs can specify its own allocator functions. The application must provide the following pluggable allocator operations: int (*nv_ao_init)(nv_alloc_t *nva, va_list nv_valist); void (*nv_ao_fini)(nv_alloc_t *nva); void *(*nv_ao_alloc)(nv_alloc_t *nva, size_t sz); void (*nv_ao_reset)(nv_alloc_t *nva); void (*nv_ao_free)(nv_alloc_t *nva, void *buf, size_t sz); The _n_v_a argument of the allocator implementation is always the first argument. The optional (*nnvv__aaoo__iinniitt(())) function is responsible for filling the data specified by nnvv__aalllloocc__iinniitt(()) into the _n_v_a___a_r_g argument. The (*nnvv__aaoo__iinniitt(())) function is only called when nnvv__aalllloocc__iinniitt(()) is executed. The optional (*nnvv__aaoo__ffiinnii(())) function is responsible for the cleanup of the allocator implementation. It is called by nnvv__aalllloocc__ffiinnii(()). The required (*nnvv__aaoo__aalllloocc(())) function is used in the nvpair allocation framework for memory allocation. The _s_z argument specifies the size of the requested buffer. The optional (*nnvv__aaoo__rreesseett(())) function is responsible for resetting the _n_v_a___a_r_g argument to the data specified by nnvv__aalllloocc__iinniitt(()). The required (*nnvv__aaoo__ffrreeee(())) function is used in the nvpair allocator framework for memory deallocation. The _b_u_f argument is a pointer to a block previously allocated by the (*nnvv__aaoo__aalllloocc(())) function. The size argument _s_z must exactly match the original allocation. The disposition of the allocated objects and the memory used to store them is left to the allocator implementation. RREETTUURRNN VVAALLUUEESS These functions return 0 on success and an error value on failure. The nnvvlliisstt__llooookkuupp__nnvv__aalllloocc(()) function returns a pointer to an allocator. EERRRROORRSS These functions will fail if: EEIINNVVAALL There is an invalid argument. The nnvvlliisstt__aalllloocc(()), nnvvlliisstt__dduupp(()), nnvvlliisstt__ppaacckk(()), nnvvlliisstt__uunnppaacckk(()), nnvvlliisstt__mmeerrggee(()), nnvvlliisstt__xxaalllloocc(()), nnvvlliisstt__xxdduupp(()), nnvvlliisstt__xxppaacckk(()), and nnvvlliisstt__xxuunnppaacckk(()) functions will fail if: EENNOOMMEEMM There is insufficient memory. The nnvvlliisstt__ppaacckk(()), nnvvlliisstt__uunnppaacckk(()), nnvvlliisstt__xxppaacckk(()), and nnvvlliisstt__xxuunnppaacckk(()) functions will fail if: EEFFAAUULLTT An encode/decode error occurs. EENNOOTTSSUUPP An encode/decode method is not supported. EEXXAAMMPPLLEESS /* * Program to create an nvlist. */ #include #include #include #include /* generate a packed nvlist */ static int create_packed_nvlist(char **buf, uint_t *buflen, int encode) { uchar_t bytes[] = {0xaa, 0xbb, 0xcc, 0xdd}; int32_t int32[] = {3, 4, 5}; char *strs[] = {"child0", "child1", "child2"}; int err; nvlist_t *nvl; err = nvlist_alloc(&nvl, NV_UNIQUE_NAME, 0); /* allocate list */ if (err) { (void) printf("nvlist_alloc() failed\n"); return (err); } /* add a value of some types */ if ((nvlist_add_byte(nvl, "byte", bytes[0]) != 0) || (nvlist_add_int32(nvl, "int32", int32[0]) != 0) || (nvlist_add_int32_array(nvl, "int32_array", int32, 3) != 0) || (nvlist_add_string_array(nvl, "string_array", strs, 3) != 0)) { nvlist_free(nvl); return (-1); } err = nvlist_size(nvl, buflen, encode); if (err) { (void) printf("nvlist_size: %s\n", strerror(err)); nvlist_free(nvl); return (err); } /* pack into contig. memory */ err = nvlist_pack(nvl, buf, buflen, encode, 0); if (err) (void) printf("nvlist_pack: %s\n", strerror(err)); /* free the original list */ nvlist_free(nvl); return (err); } /* selectively print nvpairs */ static void nvlist_lookup_and_print(nvlist_t *nvl) { char **str_val; int i, int_val; uint_t nval; if (nvlist_lookup_int32(nvl, "int32", &int_val) == 0) (void) printf("int32 = %d\n", int_val); if (nvlist_lookup_string_array(nvl, "string_array", &str_val, &nval) == 0) { (void) printf("string_array ="); for (i = 0; i < nval; i++) (void) printf(" %s", str_val[i]); (void) printf("\n"); } } /*ARGSUSED*/ int main(int argc, char *argv[]) { int err; char *buf = NULL; size_t buflen; nvlist_t *nvl = NULL; if (create_packed_nvlist(&buf, &buflen, NV_ENCODE_XDR) != 0) { (void) printf("cannot create packed nvlist buffer\n"); return(-1); } /* unpack into an nvlist_t */ err = nvlist_unpack(buf, buflen, &nvl, 0); if (err) { (void) printf("nvlist_unpack(): %s\n", strerror(err)); return(-1); } /* selectively print out attributes */ nvlist_lookup_and_print(nvl); return(0); } AATTTTRRIIBBUUTTEESS See aattttrriibbuutteess(5) for descriptions of the following attributes: +--------------------+-----------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +--------------------+-----------------+ |Interface Stability | Evolving | +--------------------+-----------------+ |MT-Level | MT-Safe | +--------------------+-----------------+ SSEEEE AALLSSOO lliibbnnvvppaaiirr(3LIB), aattttrriibbuutteess(5), nnvvlliisstt__aalllloocc(9F) February 15, 2016 NVLIST_ALLOC(3NVPAIR)