1*b9cf0dafSRobert Mustacchi.\" 2c10c16deSRichard Lowe.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. 3*b9cf0dafSRobert Mustacchi.\" 4*b9cf0dafSRobert Mustacchi.\" The contents of this file are subject to the terms of the 5*b9cf0dafSRobert Mustacchi.\" Common Development and Distribution License (the "License"). 6*b9cf0dafSRobert Mustacchi.\" You may not use this file except in compliance with the License. 7*b9cf0dafSRobert Mustacchi.\" 8*b9cf0dafSRobert Mustacchi.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or 9*b9cf0dafSRobert Mustacchi.\" http://www.opensolaris.org/os/licensing. 10*b9cf0dafSRobert Mustacchi.\" See the License for the specific language governing permissions 11*b9cf0dafSRobert Mustacchi.\" and limitations under the License. 12*b9cf0dafSRobert Mustacchi.\" 13*b9cf0dafSRobert Mustacchi.\" When distributing Covered Code, include this CDDL HEADER in each 14*b9cf0dafSRobert Mustacchi.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15*b9cf0dafSRobert Mustacchi.\" If applicable, add the following below this CDDL HEADER, with the 16*b9cf0dafSRobert Mustacchi.\" fields enclosed by brackets "[]" replaced with your own identifying 17*b9cf0dafSRobert Mustacchi.\" information: Portions Copyright [yyyy] [name of copyright owner] 18*b9cf0dafSRobert Mustacchi.\" 19*b9cf0dafSRobert Mustacchi.\" Copyright 2021 Oxide Computer Company 20*b9cf0dafSRobert Mustacchi.Dd June 12, 2021 21*b9cf0dafSRobert Mustacchi.Dt NVLIST_ALLOC 9F 22*b9cf0dafSRobert Mustacchi.Os 23*b9cf0dafSRobert Mustacchi.Sh NAME 24*b9cf0dafSRobert Mustacchi.Nm nvlist_alloc , 25*b9cf0dafSRobert Mustacchi.Nm nvlist_free , 26*b9cf0dafSRobert Mustacchi.Nm nvlist_size , 27*b9cf0dafSRobert Mustacchi.Nm nvlist_pack , 28*b9cf0dafSRobert Mustacchi.Nm nvlist_unpack , 29*b9cf0dafSRobert Mustacchi.Nm nvlist_dup , 30*b9cf0dafSRobert Mustacchi.Nm nv_alloc_init , 31*b9cf0dafSRobert Mustacchi.Nm nv_alloc_fini , 32*b9cf0dafSRobert Mustacchi.Nm nvlist_xalloc , 33*b9cf0dafSRobert Mustacchi.Nm nvlist_xpack , 34*b9cf0dafSRobert Mustacchi.Nm nvlist_xunpack , 35*b9cf0dafSRobert Mustacchi.Nm nvlist_xdup , 36*b9cf0dafSRobert Mustacchi.Nm nvlist_merge 37*b9cf0dafSRobert Mustacchi.Nd Manage a name-value pair list 38*b9cf0dafSRobert Mustacchi.Sh SYNOPSIS 39*b9cf0dafSRobert Mustacchi.In sys/nvpair.h 40*b9cf0dafSRobert Mustacchi.Ss List Manipulation 41*b9cf0dafSRobert Mustacchi.Ft int 42*b9cf0dafSRobert Mustacchi.Fo nvlist_alloc 43*b9cf0dafSRobert Mustacchi.Fa "nvlist_t **nvlp" 44*b9cf0dafSRobert Mustacchi.Fa "uint_t nvflag" 45*b9cf0dafSRobert Mustacchi.Fa "int kmflag" 46*b9cf0dafSRobert Mustacchi.Fc 47*b9cf0dafSRobert Mustacchi.Ft int 48*b9cf0dafSRobert Mustacchi.Fo nvlist_xalloc 49*b9cf0dafSRobert Mustacchi.Fa "nvlist_t **nvlp" 50*b9cf0dafSRobert Mustacchi.Fa "uint_t nvflag" 51*b9cf0dafSRobert Mustacchi.Fa "nv_alloc_t *nva" 52*b9cf0dafSRobert Mustacchi.Fc 53*b9cf0dafSRobert Mustacchi.Ft void 54*b9cf0dafSRobert Mustacchi.Fo nvlist_free 55*b9cf0dafSRobert Mustacchi.Fa "nvlist_t *nvl" 56*b9cf0dafSRobert Mustacchi.Fc 57*b9cf0dafSRobert Mustacchi.Ft int 58*b9cf0dafSRobert Mustacchi.Fo nvlist_size 59*b9cf0dafSRobert Mustacchi.Fa "nvlist_t *nvl" 60*b9cf0dafSRobert Mustacchi.Fa "size_t *size" 61*b9cf0dafSRobert Mustacchi.Fa "int encoding" 62*b9cf0dafSRobert Mustacchi.Fc 63*b9cf0dafSRobert Mustacchi.Ft int 64*b9cf0dafSRobert Mustacchi.Fo nvlist_pack 65*b9cf0dafSRobert Mustacchi.Fa "nvlist_t *nvl" 66*b9cf0dafSRobert Mustacchi.Fa "char **bufp" 67*b9cf0dafSRobert Mustacchi.Fa "size_t *buflen" 68*b9cf0dafSRobert Mustacchi.Fa "int encoding" 69*b9cf0dafSRobert Mustacchi.Fa "int flag" 70*b9cf0dafSRobert Mustacchi.Fc 71*b9cf0dafSRobert Mustacchi.Ft int 72*b9cf0dafSRobert Mustacchi.Fo nvlist_xpack 73*b9cf0dafSRobert Mustacchi.Fa "nvlist_t *nvl" 74*b9cf0dafSRobert Mustacchi.Fa "char **bufp" 75*b9cf0dafSRobert Mustacchi.Fa "size_t *buflen" 76*b9cf0dafSRobert Mustacchi.Fa "int encoding" 77*b9cf0dafSRobert Mustacchi.Fa "nv_alloc_t *nva" 78*b9cf0dafSRobert Mustacchi.Fc 79*b9cf0dafSRobert Mustacchi.Ft int 80*b9cf0dafSRobert Mustacchi.Fo nvlist_unpack 81*b9cf0dafSRobert Mustacchi.Fa "char *buf" 82*b9cf0dafSRobert Mustacchi.Fa "size_t buflen" 83*b9cf0dafSRobert Mustacchi.Fa "nvlist_t **nvlp" 84*b9cf0dafSRobert Mustacchi.Fa "int kmflag" 85*b9cf0dafSRobert Mustacchi.Fc 86*b9cf0dafSRobert Mustacchi.Ft int 87*b9cf0dafSRobert Mustacchi.Fo nvlist_xunpack 88*b9cf0dafSRobert Mustacchi.Fa "char *buf" 89*b9cf0dafSRobert Mustacchi.Fa size_t buflen" 90*b9cf0dafSRobert Mustacchi.Fa nvlist_t **nvlp" 91*b9cf0dafSRobert Mustacchi.Fa nv_alloc_t *nva" 92*b9cf0dafSRobert Mustacchi.Fc 93*b9cf0dafSRobert Mustacchi.Ft int 94*b9cf0dafSRobert Mustacchi.Fo nvlist_dup 95*b9cf0dafSRobert Mustacchi.Fa "nvlist_t *nvl" 96*b9cf0dafSRobert Mustacchi.Fa "nvlist_t **nvlp" 97*b9cf0dafSRobert Mustacchi.Fa "int kmflag" 98*b9cf0dafSRobert Mustacchi.Fc 99*b9cf0dafSRobert Mustacchi.Ft int 100*b9cf0dafSRobert Mustacchi.Fo nvlist_xdup 101*b9cf0dafSRobert Mustacchi.Fa "nvlist_t *nvl" 102*b9cf0dafSRobert Mustacchi.Fa "nvlist_t **nvlp" 103*b9cf0dafSRobert Mustacchi.Fa "nv_alloc_t *nva" 104*b9cf0dafSRobert Mustacchi.Fc 105*b9cf0dafSRobert Mustacchi.Ft int 106*b9cf0dafSRobert Mustacchi.Fo nvlist_merge 107*b9cf0dafSRobert Mustacchi.Fa "nvlist_t *dst" 108*b9cf0dafSRobert Mustacchi.Fa "nvlist_t *nvl" 109*b9cf0dafSRobert Mustacchi.Fa "int kmflag" 110*b9cf0dafSRobert Mustacchi.Fc 111*b9cf0dafSRobert Mustacchi.Ss Pluggable Allocator Configuration 112*b9cf0dafSRobert Mustacchi.Ft "nv_alloc_t *" 113*b9cf0dafSRobert Mustacchi.Fo nvlist_lookup_nv_alloc 114*b9cf0dafSRobert Mustacchi.Fa "nvlist_t *nvl" 115*b9cf0dafSRobert Mustacchi.Fc 116*b9cf0dafSRobert Mustacchi.Ft int 117*b9cf0dafSRobert Mustacchi.Fo nv_alloc_init 118*b9cf0dafSRobert Mustacchi.Fa "nv_alloc_t *nva" 119*b9cf0dafSRobert Mustacchi.Fa "const nv_alloc_ops_t *nvo" 120*b9cf0dafSRobert Mustacchi.Fa "..." 121*b9cf0dafSRobert Mustacchi.Fc 122*b9cf0dafSRobert Mustacchi.Ft void 123*b9cf0dafSRobert Mustacchi.Fo nv_alloc_reset 124*b9cf0dafSRobert Mustacchi.Fa "nv_alloc_t *nva" 125*b9cf0dafSRobert Mustacchi.Fc 126*b9cf0dafSRobert Mustacchi.Ft void 127*b9cf0dafSRobert Mustacchi.Fo nv_alloc_fini 128*b9cf0dafSRobert Mustacchi.Fa "nv_alloc_t *nva" 129*b9cf0dafSRobert Mustacchi.Fc 130*b9cf0dafSRobert Mustacchi.Ss Pluggable Allocation Initialization with Fixed Allocator 131*b9cf0dafSRobert Mustacchi.Ft int 132*b9cf0dafSRobert Mustacchi.Fo nv_alloc_init 133*b9cf0dafSRobert Mustacchi.Fa "nv_alloc_t *nva" 134*b9cf0dafSRobert Mustacchi.Fa "nv_fixed_ops" 135*b9cf0dafSRobert Mustacchi.Fa "void *bufptr" 136*b9cf0dafSRobert Mustacchi.Fa "sz" 137*b9cf0dafSRobert Mustacchi.Fc 138*b9cf0dafSRobert Mustacchi.Sh INTERFACE LEVEL 1393184921aSRichard Loweillumos DDI specific (illumos DDI) 140*b9cf0dafSRobert Mustacchi.Sh PARAMETERS 141*b9cf0dafSRobert Mustacchi.Bl -tag -width Fa 142*b9cf0dafSRobert Mustacchi.It Fa nvlp 143*b9cf0dafSRobert MustacchiAddress of a pointer to list of name-value pairs 144*b9cf0dafSRobert Mustacchi.Pq Ft nvlist_t . 145*b9cf0dafSRobert Mustacchi.It Fa nvflag 146*b9cf0dafSRobert MustacchiSpecify bit fields defining 147*b9cf0dafSRobert Mustacchi.Ft nvlist_t 148*b9cf0dafSRobert Mustacchiproperties: 149*b9cf0dafSRobert Mustacchi.Bl -tag -width Dv 150*b9cf0dafSRobert Mustacchi.It Dv NV_UNIQUE_NAME 151*b9cf0dafSRobert Mustacchinvpair names are unique. 152*b9cf0dafSRobert Mustacchi.It Dv NV_UNIQUE_NAME_TYPE 153c10c16deSRichard LoweName-data type combination is unique 154*b9cf0dafSRobert Mustacchi.El 155*b9cf0dafSRobert Mustacchi.It Fa kmflag 156*b9cf0dafSRobert MustacchiKernel memory allocation policy, either 157*b9cf0dafSRobert Mustacchi.Dv KM_SLEEP 158*b9cf0dafSRobert Mustacchior 159*b9cf0dafSRobert Mustacchi.Dv KM_NOSLEEP . 160*b9cf0dafSRobert Mustacchi.It Fa nvl 161*b9cf0dafSRobert Mustacchi.Ft nvlist_t 162*b9cf0dafSRobert Mustacchito be processed. 163*b9cf0dafSRobert Mustacchi.It Fa dst 164*b9cf0dafSRobert MustacchiDestination 165*b9cf0dafSRobert Mustacchi.Ft nvlist_t . 166*b9cf0dafSRobert Mustacchi.It Fa size 167c10c16deSRichard LowePointer to buffer to contain the encoded size. 168*b9cf0dafSRobert Mustacchi.It Fa bufp 169*b9cf0dafSRobert MustacchiAddress of buffer to pack nvlist into. 170*b9cf0dafSRobert MustacchiMust be 8-byte aligned. 171*b9cf0dafSRobert MustacchiIf 172*b9cf0dafSRobert Mustacchi.Dv NULL , 173c10c16deSRichard Lowelibrary will allocate memory. 174*b9cf0dafSRobert Mustacchi.It buf 175*b9cf0dafSRobert MustacchiBuffer containing packed 176*b9cf0dafSRobert Mustacchi.Ft nvlist_t . 177*b9cf0dafSRobert Mustacchi.It buflen buflen 178*b9cf0dafSRobert MustacchiSize of buffer 179*b9cf0dafSRobert Mustacchi.Fa bufp 180*b9cf0dafSRobert Mustacchior 181*b9cf0dafSRobert Mustacchi.Fa buf 182*b9cf0dafSRobert Mustacchipoints to. 183*b9cf0dafSRobert Mustacchi.It Fa encoding 184c10c16deSRichard LoweEncoding method for packing. 185*b9cf0dafSRobert Mustacchi.It Fa nvo 186*b9cf0dafSRobert MustacchiPluggable allocator operations pointer 187*b9cf0dafSRobert Mustacchi.Pq Ft nv_alloc_ops_t . 188*b9cf0dafSRobert Mustacchi.It nva 189*b9cf0dafSRobert MustacchiPoints to a 190*b9cf0dafSRobert Mustacchi.Ft nv_alloc_t 191*b9cf0dafSRobert Mustacchistructure to be used for the specified 192*b9cf0dafSRobert Mustacchi.Ft nvlist_t . 193*b9cf0dafSRobert Mustacchi.El 194*b9cf0dafSRobert Mustacchi.Sh DESCRIPTION 195*b9cf0dafSRobert Mustacchi.Ss List Manipulation 196*b9cf0dafSRobert MustacchiThe 197*b9cf0dafSRobert Mustacchi.Fn nvlist_alloc 198*b9cf0dafSRobert Mustacchifunction allocates a new name-value pair list and updates 199*b9cf0dafSRobert Mustacchi.Fa nvlp 200*b9cf0dafSRobert Mustacchito point to the handle. 201*b9cf0dafSRobert MustacchiThe argument 202*b9cf0dafSRobert Mustacchi.Fa nvflag 203*b9cf0dafSRobert Mustacchispecifies 204*b9cf0dafSRobert Mustacchi.Ft nvlist_t 205*b9cf0dafSRobert Mustacchiproperties to remain persistent across packing, unpacking, and duplication. 206*b9cf0dafSRobert Mustacchi.Pp 207*b9cf0dafSRobert MustacchiIf 208*b9cf0dafSRobert Mustacchi.Dv NV_UNIQUE_NAME 209*b9cf0dafSRobert Mustacchiis specified for nvflag, existing nvpairs with matching names are removed 210*b9cf0dafSRobert Mustacchibefore the new nvpair is added. 211*b9cf0dafSRobert MustacchiIf 212*b9cf0dafSRobert Mustacchi.Dv NV_UNIQUE_NAME_TYPE 213c10c16deSRichard Loweis specified for nvflag, existing nvpairs with matching names and data types 214*b9cf0dafSRobert Mustacchiare removed before the new nvpair is added. 215*b9cf0dafSRobert MustacchiSee 216*b9cf0dafSRobert Mustacchi.Xr nvlist_add_byte 9F 217*b9cf0dafSRobert Mustacchifor more details. 218*b9cf0dafSRobert Mustacchi.Pp 219*b9cf0dafSRobert MustacchiThe 220*b9cf0dafSRobert Mustacchi.Fn nvlist_xalloc 221*b9cf0dafSRobert Mustacchifunction differs from 222*b9cf0dafSRobert Mustacchi.Fn nvlist_alloc 223*b9cf0dafSRobert Mustacchiin that 224*b9cf0dafSRobert Mustacchi.Fn nvlist_xalloc 225*b9cf0dafSRobert Mustacchican use a different allocator, as described in the 226*b9cf0dafSRobert Mustacchi.Sx Pluggable Allocators 227*b9cf0dafSRobert Mustacchisection. 228*b9cf0dafSRobert Mustacchi.Pp 229*b9cf0dafSRobert MustacchiThe 230*b9cf0dafSRobert Mustacchi.Fn nvlist_free 231*b9cf0dafSRobert Mustacchifunction frees a name-value pair list. 232*b9cf0dafSRobert MustacchiIf 233*b9cf0dafSRobert Mustacchi.Fa nvl 234aab83bb8SJosef 'Jeff' Sipekis a null pointer, no action occurs. 235*b9cf0dafSRobert Mustacchi.Pp 236*b9cf0dafSRobert MustacchiThe 237*b9cf0dafSRobert Mustacchi.Fn nvlist_size 238*b9cf0dafSRobert Mustacchifunction returns the minimum size of a contiguous buffer large enough to pack 239*b9cf0dafSRobert Mustacchi.Fa nvl . 240*b9cf0dafSRobert MustacchiThe 241*b9cf0dafSRobert Mustacchi.Fa encoding 242*b9cf0dafSRobert Mustacchiparameter specifies the method of encoding when packing 243*b9cf0dafSRobert Mustacchi.Fa nvl 244*b9cf0dafSRobert MustacchiSupported encoding methods are: 245*b9cf0dafSRobert Mustacchi.Bl -tag -width Dv -offset indent 246*b9cf0dafSRobert Mustacchi.It Dv NV_ENCODE_NATIVE 247*b9cf0dafSRobert MustacchiStraight 248*b9cf0dafSRobert Mustacchi.Fn bcopy 249*b9cf0dafSRobert Mustacchias described in 250*b9cf0dafSRobert Mustacchi.Xr bcopy 9F . 251*b9cf0dafSRobert Mustacchi.It Dv NV_ENCODE_XDR 252c10c16deSRichard LoweUse XDR encoding, suitable for sending to another host. 253*b9cf0dafSRobert Mustacchi.El 254*b9cf0dafSRobert Mustacchi.Pp 255*b9cf0dafSRobert MustacchiThe 256*b9cf0dafSRobert Mustacchi.Fn nvlist_pack 257*b9cf0dafSRobert Mustacchifunction packs 258*b9cf0dafSRobert Mustacchi.Fa nvl 259*b9cf0dafSRobert Mustacchiinto contiguous memory starting at 260*b9cf0dafSRobert Mustacchi.Pf * Fa bufp . 261*b9cf0dafSRobert MustacchiThe 262*b9cf0dafSRobert Mustacchi.Fa encoding 263*b9cf0dafSRobert Mustacchiparameter specifies the method of encoding (see above). 264*b9cf0dafSRobert Mustacchi.Bl -bullet -offset indent 265*b9cf0dafSRobert Mustacchi.It 266*b9cf0dafSRobert MustacchiIf 267*b9cf0dafSRobert Mustacchi.Pf * Fa bufp 268*b9cf0dafSRobert Mustacchiis not 269*b9cf0dafSRobert Mustacchi.Dv NULL , 270*b9cf0dafSRobert Mustacchi.Pf * Fa bufp 271*b9cf0dafSRobert Mustacchiis expected to be a caller-allocated buffer of size 272*b9cf0dafSRobert Mustacchi.Pf * Fa buflen . 273*b9cf0dafSRobert MustacchiThe 274*b9cf0dafSRobert Mustacchi.Fa kmflag 275*b9cf0dafSRobert Mustacchiargument is ignored. 276*b9cf0dafSRobert Mustacchi.It 277*b9cf0dafSRobert MustacchiIf 278*b9cf0dafSRobert Mustacchi.Pf * Fa bufp 279*b9cf0dafSRobert Mustacchiis 280*b9cf0dafSRobert Mustacchi.Dv NULL , 281*b9cf0dafSRobert Mustacchithe library allocates memory and updates 282*b9cf0dafSRobert Mustacchi.Pf * Fa bufp 283*b9cf0dafSRobert Mustacchito point to the memory and updates 284*b9cf0dafSRobert Mustacchi.Pf * Fa buflen 285*b9cf0dafSRobert Mustacchito contain the size of the allocated memory. 286*b9cf0dafSRobert MustacchiThe value of 287*b9cf0dafSRobert Mustacchi.Fa kmflag 288*b9cf0dafSRobert Mustacchiindicates the memory allocation policy 289*b9cf0dafSRobert Mustacchi.El 290*b9cf0dafSRobert Mustacchi.Pp 291*b9cf0dafSRobert MustacchiThe 292*b9cf0dafSRobert Mustacchi.Fn nvlist_xpack 293*b9cf0dafSRobert Mustacchifunction differs from 294*b9cf0dafSRobert Mustacchi.Fn nvlist_pack 295*b9cf0dafSRobert Mustacchiin that 296*b9cf0dafSRobert Mustacchi.Fn nvlist_xpack 297*b9cf0dafSRobert Mustacchican use a different allocator. 298*b9cf0dafSRobert Mustacchi.Pp 299*b9cf0dafSRobert MustacchiThe 300*b9cf0dafSRobert Mustacchi.Fn nvlist_unpack 301*b9cf0dafSRobert Mustacchifunction takes a buffer with a packed 302*b9cf0dafSRobert Mustacchi.Ft nvlist_t 303*b9cf0dafSRobert Mustacchiand unpacks it into a searchable 304*b9cf0dafSRobert Mustacchi.Ft nvlist_t . 305*b9cf0dafSRobert MustacchiThe library allocates memory for 306*b9cf0dafSRobert Mustacchi.Ft nvlist_t . 307*b9cf0dafSRobert MustacchiThe caller is responsible for freeing the memory by calling 308*b9cf0dafSRobert Mustacchi.Fn nvlist_free 309*b9cf0dafSRobert Mustacchi.Pp 310*b9cf0dafSRobert MustacchiThe 311*b9cf0dafSRobert Mustacchi.Fn nvlist_xunpack 312*b9cf0dafSRobert Mustacchifunction differs from 313*b9cf0dafSRobert Mustacchi.Fn nvlist_unpack 314*b9cf0dafSRobert Mustacchiin that 315*b9cf0dafSRobert Mustacchi.Fn nvlist_xunpack 316*b9cf0dafSRobert Mustacchican use a different allocator. 317*b9cf0dafSRobert Mustacchi.Pp 318*b9cf0dafSRobert MustacchiThe 319*b9cf0dafSRobert Mustacchi.Fn nvlist_dup 320*b9cf0dafSRobert Mustacchifunction makes a copy of 321*b9cf0dafSRobert Mustacchi.Fa nvl 322*b9cf0dafSRobert Mustacchiand updates 323*b9cf0dafSRobert Mustacchi.Fa nvlp 324*b9cf0dafSRobert Mustacchito point to the copy. 325*b9cf0dafSRobert Mustacchi.Pp 326*b9cf0dafSRobert MustacchiThe 327*b9cf0dafSRobert Mustacchi.Fn nvlist_xdup 328*b9cf0dafSRobert Mustacchifunction differs from 329*b9cf0dafSRobert Mustacchi.Fn nvlist_dup 330*b9cf0dafSRobert Mustacchiin that 331*b9cf0dafSRobert Mustacchi.Fn nvlist_xdup 332*b9cf0dafSRobert Mustacchican use a different allocator. 333*b9cf0dafSRobert Mustacchi.Pp 334*b9cf0dafSRobert MustacchiThe 335*b9cf0dafSRobert Mustacchi.Fn nvlist_merge 336*b9cf0dafSRobert Mustacchifunction adds copies of all name-value pairs from 337*b9cf0dafSRobert Mustacchi.Fa "nvlist_t nvl" 338*b9cf0dafSRobert Mustacchito 339*b9cf0dafSRobert Mustacchi.Fa "nvlist_t dst" . 340*b9cf0dafSRobert MustacchiName-value pairs in 341*b9cf0dafSRobert Mustacchi.Fa dst 342*b9cf0dafSRobert Mustacchiare replaced with name-value pairs from 343*b9cf0dafSRobert Mustacchi.Fa nvl 344*b9cf0dafSRobert Mustacchiwhich have identical names 345*b9cf0dafSRobert Mustacchi.Po 346*b9cf0dafSRobert Mustacchiif 347*b9cf0dafSRobert Mustacchi.Fa dst 348*b9cf0dafSRobert Mustacchihas the type 349*b9cf0dafSRobert Mustacchi.Dv NV_UNIQUE_NAME 350*b9cf0dafSRobert Mustacchi.Pc 351*b9cf0dafSRobert Mustacchior identical names and types 352*b9cf0dafSRobert Mustacchi.Po 353*b9cf0dafSRobert Mustacchiif 354*b9cf0dafSRobert Mustacchi.Fa dst 355*b9cf0dafSRobert Mustacchihas the type 356*b9cf0dafSRobert Mustacchi.Dv NV_UNIQUE_NAME_TYPE 357*b9cf0dafSRobert Mustacchi.Pc . 358*b9cf0dafSRobert Mustacchi.Pp 359*b9cf0dafSRobert MustacchiThe 360*b9cf0dafSRobert Mustacchi.Fn nvlist_lookup_nv_alloc 361*b9cf0dafSRobert Mustacchifunction retrieves the pointer to the allocator used when manipulating a 362*b9cf0dafSRobert Mustacchiname-value pair list. 363*b9cf0dafSRobert Mustacchi.Ss "Pluggable Allocators" 364*b9cf0dafSRobert MustacchiThe 365*b9cf0dafSRobert Mustacchi.Fn nv_alloc_init , 366*b9cf0dafSRobert Mustacchi.Fn nv_alloc_reset , 367*b9cf0dafSRobert Mustacchiand 368*b9cf0dafSRobert Mustacchi.Fn nv_alloc_fini 369c10c16deSRichard Lowefunctions provide an interface that specifies the allocator to be used when 370c10c16deSRichard Lowemanipulating a name-value pair list. 371*b9cf0dafSRobert Mustacchi.Pp 372*b9cf0dafSRobert MustacchiThe 373*b9cf0dafSRobert Mustacchi.Fn nv_alloc_init 374*b9cf0dafSRobert Mustacchidetermines allocator properties and puts them into 375*b9cf0dafSRobert Mustacchithe 376*b9cf0dafSRobert Mustacchi.Fa nva 377*b9cf0dafSRobert Mustacchiargument. 378*b9cf0dafSRobert MustacchiYou need to specify the 379*b9cf0dafSRobert Mustacchi.Fa nv_arg 380*b9cf0dafSRobert Mustacchiargument, the 381*b9cf0dafSRobert Mustacchi.Fa nvo 382*b9cf0dafSRobert Mustacchiargument and an optional variable argument list. 383*b9cf0dafSRobert MustacchiThe optional arguments are passed to the 384*b9cf0dafSRobert Mustacchi.Pf * Fn nv_ao_init 385*b9cf0dafSRobert Mustacchifunction. 386*b9cf0dafSRobert Mustacchi.Pp 387*b9cf0dafSRobert MustacchiThe 388*b9cf0dafSRobert Mustacchi.Fa nva 389*b9cf0dafSRobert Mustacchiargument must be passed to 390*b9cf0dafSRobert Mustacchi.Fn nvlist_xalloc , 391*b9cf0dafSRobert Mustacchi.Fn nvlist_xpack , 392*b9cf0dafSRobert Mustacchi.Fn nvlist_xunpack , 393*b9cf0dafSRobert Mustacchiand 394*b9cf0dafSRobert Mustacchi.Fn nvlist_xdup . 395*b9cf0dafSRobert Mustacchi.Pp 396*b9cf0dafSRobert MustacchiThe 397*b9cf0dafSRobert Mustacchi.Fn nv_alloc_reset 398*b9cf0dafSRobert Mustacchifunction resets the allocator properties to the data specified by 399*b9cf0dafSRobert Mustacchi.Fn nv_alloc_init . 400*b9cf0dafSRobert MustacchiWhen no 401*b9cf0dafSRobert Mustacchi.Pf * Fn nv_ao_reset 402*b9cf0dafSRobert Mustacchifunction is specified, 403*b9cf0dafSRobert Mustacchi.Fn nv_alloc_reset 404*b9cf0dafSRobert Mustacchiis without effect. 405*b9cf0dafSRobert Mustacchi.Pp 406*b9cf0dafSRobert MustacchiThe 407*b9cf0dafSRobert Mustacchi.Fn nv_alloc_fini 408*b9cf0dafSRobert Mustacchidestroys the allocator properties determined by 409*b9cf0dafSRobert Mustacchi.Fn nv_alloc_init . 410*b9cf0dafSRobert MustacchiWhen a 411*b9cf0dafSRobert Mustacchi.Pf * Fn nv_ao_fini 412*b9cf0dafSRobert Mustacchiroutine is specified, it is 413*b9cf0dafSRobert Mustacchicalled from 414*b9cf0dafSRobert Mustacchi.Fn nv_alloc_fini . 415*b9cf0dafSRobert Mustacchi.Pp 416c10c16deSRichard LoweThe disposition of the allocated objects and the memory used to store them is 417c10c16deSRichard Loweleft to the allocator implementation. 418*b9cf0dafSRobert Mustacchi.Pp 419*b9cf0dafSRobert MustacchiThe 420*b9cf0dafSRobert Mustacchi.Va nv_alloc_sleep 421*b9cf0dafSRobert Mustacchiand 422*b9cf0dafSRobert Mustacchi.Va nv_alloc_nosleep 423*b9cf0dafSRobert Mustacchi.Ft nv_alloc_t 424*b9cf0dafSRobert Mustacchipointers may be used with 425*b9cf0dafSRobert Mustacchi.Fn nvlist_xalloc 426*b9cf0dafSRobert Mustacchito mimic the behavior of 427*b9cf0dafSRobert Mustacchi.Fn nvlist_alloc 428*b9cf0dafSRobert Mustacchiwith 429*b9cf0dafSRobert Mustacchi.Dv KM_SLEEP and 430*b9cf0dafSRobert Mustacchi.Dv KM_NOSLEEP , 431*b9cf0dafSRobert Mustacchirespectively. 432*b9cf0dafSRobert Mustacchi.Pp 433c10c16deSRichard LoweThe nvpair framework provides a fixed-buffer allocator, accessible via 434*b9cf0dafSRobert Mustacchi.Pp 435c10c16deSRichard LoweGiven a buffer size and address, the fixed-buffer allocator allows for the 436*b9cf0dafSRobert Mustacchicreation of nvlists in contexts where 437*b9cf0dafSRobert Mustacchi.Xr malloc 3C 438*b9cf0dafSRobert Mustacchior 439*b9cf0dafSRobert Mustacchi.Xr kmem_alloc 9F 440*b9cf0dafSRobert Mustacchiservices may not be available. 441*b9cf0dafSRobert MustacchiThe fixed-buffer allocator is designed primarily to support the creation of 442*b9cf0dafSRobert Mustacchinvlists. 443*b9cf0dafSRobert Mustacchi.Pp 444*b9cf0dafSRobert MustacchiMemory freed using 445*b9cf0dafSRobert Mustacchi.Fn nvlist_free , 446*b9cf0dafSRobert Mustacchipair-removal, or similar routines is not reclaimed. 447*b9cf0dafSRobert Mustacchi.Pp 448*b9cf0dafSRobert MustacchiWhen used to initialize the fixed-buffer allocator, 449*b9cf0dafSRobert Mustacchi.Fn nv_alloc_init 450*b9cf0dafSRobert Mustacchishould be called as follows: 451*b9cf0dafSRobert Mustacchi.Pp 452*b9cf0dafSRobert Mustacchi.Fo nv_alloc_init 453*b9cf0dafSRobert Mustacchi.Fa "nv_alloc_t *nva" 454*b9cf0dafSRobert Mustacchi.Fa "nv_fixed_ops" 455*b9cf0dafSRobert Mustacchi.Fa "void *bufptr" 456*b9cf0dafSRobert Mustacchi.Fa "size_t sz" 457*b9cf0dafSRobert Mustacchi.Fc . 458*b9cf0dafSRobert Mustacchi.Pp 459*b9cf0dafSRobert MustacchiWhen invoked on a fixed-buffer, the 460*b9cf0dafSRobert Mustacchi\fBnv_alloc_reset()\fR 461*b9cf0dafSRobert Mustacchifunction resets the fixed buffer and prepares it for re-use. 462*b9cf0dafSRobert MustacchiThe framework consumer is responsible for freeing the buffer passed to 463*b9cf0dafSRobert Mustacchi\fBnv_alloc_init()\fR. 464*b9cf0dafSRobert Mustacchi.Ss Creating Pluggable Allocators 465*b9cf0dafSRobert MustacchiAny producer of name-value pairs may possibly specify his own allocator 466*b9cf0dafSRobert Mustacchiroutines. 467*b9cf0dafSRobert MustacchiYou must provide the following pluggable allocator operations in the allocator 468*b9cf0dafSRobert Mustacchiimplementation. 469*b9cf0dafSRobert Mustacchi.Bd -literal -offset indent 470c10c16deSRichard Loweint (*nv_ao_init)(nv_alloc_t *nva, va_list nv_valist); 471c10c16deSRichard Lowevoid (*nv_ao_fini)(nv_alloc_t *nva); 472c10c16deSRichard Lowevoid *(*nv_ao_alloc)(nv_alloc_t *nva, size_t sz); 473c10c16deSRichard Lowevoid (*nv_ao_reset)(nv_alloc_t *nva); 474c10c16deSRichard Lowevoid (*nv_ao_free)(nv_alloc_t *nva, void *buf, size_t sz); 475*b9cf0dafSRobert Mustacchi.Ed 476*b9cf0dafSRobert Mustacchi.Pp 477*b9cf0dafSRobert MustacchiThe 478*b9cf0dafSRobert Mustacchi.Fa nva 479*b9cf0dafSRobert Mustacchiargument of the allocator implementation is always the first argument. 480*b9cf0dafSRobert Mustacchi.Pp 481*b9cf0dafSRobert MustacchiThe optional 482*b9cf0dafSRobert Mustacchi.Pf * Fn nv_ao_init 483*b9cf0dafSRobert Mustacchifunction is responsible for filling the data specified by 484*b9cf0dafSRobert Mustacchi.Fn nv_alloc_init 485*b9cf0dafSRobert Mustacchiinto the 486*b9cf0dafSRobert Mustacchi.Fa nva_arg 487*b9cf0dafSRobert Mustacchimember. 488*b9cf0dafSRobert Mustacchi The 489*b9cf0dafSRobert Mustacchi.Pf * Fn nv_ao_init 490*b9cf0dafSRobert Mustacchifunction is called only when 491*b9cf0dafSRobert Mustacchi.Fn nv_alloc_init 492*b9cf0dafSRobert Mustacchiis executed. 493*b9cf0dafSRobert Mustacchi.Pp 494*b9cf0dafSRobert MustacchiThe optional 495*b9cf0dafSRobert Mustacchi.Pf * Fn nv_ao_fini 496*b9cf0dafSRobert Mustacchifunction is responsible for the cleanup of the allocator implementation. 497*b9cf0dafSRobert MustacchiIt is called by 498*b9cf0dafSRobert Mustacchi.Fn nv_alloc_fini . 499*b9cf0dafSRobert Mustacchi.Pp 500*b9cf0dafSRobert MustacchiThe required 501*b9cf0dafSRobert Mustacchi.Pf * Fn nv_ao_alloc 502*b9cf0dafSRobert Mustacchifunction is used in the nvpair allocation framework for memory allocation. 503*b9cf0dafSRobert MustacchiThe 504*b9cf0dafSRobert Mustacchi.Fa sz 505*b9cf0dafSRobert Mustacchiargument specifies the size of the requested buffer. 506*b9cf0dafSRobert Mustacchi.Pp 507*b9cf0dafSRobert MustacchiThe optional 508*b9cf0dafSRobert Mustacchi.Pf * Fn nv_ao_reset 509*b9cf0dafSRobert Mustacchifunction is responsible for resetting the 510*b9cf0dafSRobert Mustacchi.Fa nva_arg 511*b9cf0dafSRobert Mustacchimember to the data specified by 512*b9cf0dafSRobert Mustacchi.Fn nv_alloc_init . 513*b9cf0dafSRobert Mustacchi.Pp 514*b9cf0dafSRobert MustacchiThe required 515*b9cf0dafSRobert Mustacchi.Pf * Fn nv_ao_free 516*b9cf0dafSRobert Mustacchifunction is used in the nvpair allocator framework for memory de-allocation. 517*b9cf0dafSRobert MustacchiThe argument 518*b9cf0dafSRobert Mustacchi.Fa buf 519*b9cf0dafSRobert Mustacchiis a pointer to a block 520*b9cf0dafSRobert Mustacchipreviously allocated by 521*b9cf0dafSRobert Mustacchi.Pf * Fn nv_ao_alloc 522*b9cf0dafSRobert Mustacchifunction. 523*b9cf0dafSRobert MustacchiThe size argument 524*b9cf0dafSRobert Mustacchi.Fa sz 525c10c16deSRichard Lowemust exactly match the original allocation. 526*b9cf0dafSRobert Mustacchi.Pp 527c10c16deSRichard LoweThe disposition of the allocated objects and the memory used to store them is 528c10c16deSRichard Loweleft to the allocator implementation. 529*b9cf0dafSRobert Mustacchi.Sh CONTEXT 530*b9cf0dafSRobert MustacchiThe 531*b9cf0dafSRobert Mustacchi.Fn nvlist_alloc , 532*b9cf0dafSRobert Mustacchi.Fn nvlist_pack , 533*b9cf0dafSRobert Mustacchi.Fn nvlist_unpack , 534*b9cf0dafSRobert Mustacchiand 535*b9cf0dafSRobert Mustacchi.Fn nvlist_dup 536*b9cf0dafSRobert Mustacchifunctions can be called from interrupt context only if the 537*b9cf0dafSRobert Mustacchi.Dv KM_NOSLEEP 538*b9cf0dafSRobert Mustacchiflag is set. 539*b9cf0dafSRobert MustacchiThey can be called from user context with any valid flag. 540*b9cf0dafSRobert Mustacchi.Pp 541*b9cf0dafSRobert MustacchiThe 542*b9cf0dafSRobert Mustacchi.Fn nvlist_xalloc , 543*b9cf0dafSRobert Mustacchi.Fn nvlist_xpack , 544*b9cf0dafSRobert Mustacchi.Fn nvlist_xunpack , 545*b9cf0dafSRobert Mustacchiand 546*b9cf0dafSRobert Mustacchi.Fn nvlist_xdup 547*b9cf0dafSRobert Mustacchifunctions can be called from interrupt context only if 548*b9cf0dafSRobert Mustacchi.Pq 1 549*b9cf0dafSRobert Mustacchithe default allocator is used and the 550*b9cf0dafSRobert Mustacchi.Dv KM_NOSLEEP 551*b9cf0dafSRobert Mustacchiflag is set or 552*b9cf0dafSRobert Mustacchi.Pq 2 553*b9cf0dafSRobert Mustacchithe specified allocator did not sleep for free memory 554*b9cf0dafSRobert Mustacchi.Pq for example, it uses a pre-allocated buffer for memory allocations . 555*b9cf0dafSRobert Mustacchi.Pp 556*b9cf0dafSRobert MustacchiThese functions can be called from user or kernel context with any valid flag. 557*b9cf0dafSRobert Mustacchi.Sh RETURN VALUES 558*b9cf0dafSRobert MustacchiFor 559*b9cf0dafSRobert Mustacchi.Fn nvlist_alloc , 560*b9cf0dafSRobert Mustacchi.Fn nvlist_dup , 561*b9cf0dafSRobert Mustacchi.Fn nvlist_xalloc , 562*b9cf0dafSRobert Mustacchiand 563*b9cf0dafSRobert Mustacchi.Fn nvlist_xdup : 564*b9cf0dafSRobert Mustacchi.Bl -tag -width Er 565*b9cf0dafSRobert Mustacchi.It Er 0 566c10c16deSRichard Lowesuccess 567*b9cf0dafSRobert Mustacchi.It Er EINVAL 568c10c16deSRichard Loweinvalid argument 569*b9cf0dafSRobert Mustacchi.It Er ENOMEM 570c10c16deSRichard Loweinsufficient memory 571*b9cf0dafSRobert Mustacchi.El 572*b9cf0dafSRobert Mustacchi.Pp 573*b9cf0dafSRobert MustacchiFor 574*b9cf0dafSRobert Mustacchi.Fn nvlist_pack , 575*b9cf0dafSRobert Mustacchi.Fn nvlist_unpack , 576*b9cf0dafSRobert Mustacchi.Fn nvlist_xpack , 577*b9cf0dafSRobert Mustacchiand 578*b9cf0dafSRobert Mustacchi.Fn nvlist_xunpack : 579*b9cf0dafSRobert Mustacchi.Bl -tag -width Er 580*b9cf0dafSRobert Mustacchi.It Sy 0 581c10c16deSRichard Lowesuccess 582*b9cf0dafSRobert Mustacchi.It Er EINVAL 583c10c16deSRichard Loweinvalid argument 584*b9cf0dafSRobert Mustacchi.It Er ENOMEM 585c10c16deSRichard Loweinsufficient memory 586*b9cf0dafSRobert Mustacchi.It Er EFAULT 587c10c16deSRichard Loweencode/decode error 588*b9cf0dafSRobert Mustacchi.It Er ENOTSUP 589c10c16deSRichard Loweencode/decode method not supported 590*b9cf0dafSRobert Mustacchi.El 591*b9cf0dafSRobert Mustacchi.Pp 592*b9cf0dafSRobert MustacchiFor 593*b9cf0dafSRobert Mustacchi.Fn nvlist_size : 594*b9cf0dafSRobert Mustacchi.Bl -tag -width Er 595*b9cf0dafSRobert Mustacchi.It Sy 0 596c10c16deSRichard Lowesuccess 597*b9cf0dafSRobert Mustacchi.It Er EINVAL 598*b9cf0dafSRobert Mustacchi.El 599*b9cf0dafSRobert Mustacchi.Pp 600*b9cf0dafSRobert MustacchiThe 601*b9cf0dafSRobert Mustacchi.Fn nvlist_lookup_nv_alloc 602*b9cf0dafSRobert Mustacchifunction returns a pointer to the allocator or 603*b9cf0dafSRobert Mustacchi.Dv NULL 604*b9cf0dafSRobert Mustacchiif there is no allocator. 605*b9cf0dafSRobert Mustacchi.Sh USAGE 606*b9cf0dafSRobert MustacchiThe fixed-buffer allocator is very simple allocator. 607*b9cf0dafSRobert MustacchiIt uses a pre-allocated buffer for memory allocations and it can be used in 608*b9cf0dafSRobert Mustacchiinterrupt context. 609*b9cf0dafSRobert MustacchiYou are responsible for allocation and de-allocation for the pre-allocated 610*b9cf0dafSRobert Mustacchibuffer. 611*b9cf0dafSRobert Mustacchi.Sh EXAMPLES 612*b9cf0dafSRobert Mustacchi.Sy Example 1 613*b9cf0dafSRobert MustacchiUsing the fixed-buffer allocator 614*b9cf0dafSRobert Mustacchi.Bd -literal -offset indent 615*b9cf0dafSRobert Mustacchi#include <sys/nvpair.h> 616c10c16deSRichard Lowe 617*b9cf0dafSRobert Mustacchi/* initialize the nvpair allocator framework */ 618*b9cf0dafSRobert Mustacchistatic nv_alloc_t * 619*b9cf0dafSRobert Mustacchiinit(char *buf, size_t size) 620*b9cf0dafSRobert Mustacchi{ 621*b9cf0dafSRobert Mustacchi nv_alloc_t *nvap; 622*b9cf0dafSRobert Mustacchi 623*b9cf0dafSRobert Mustacchi if ((nvap = kmem_alloc(sizeof(nv_alloc_t), KM_SLEEP)) == NULL) 624*b9cf0dafSRobert Mustacchi return (NULL); 625*b9cf0dafSRobert Mustacchi 626*b9cf0dafSRobert Mustacchi if (nv_alloc_init(nvap, nv_fixed_ops, buf, size) == 0) 627*b9cf0dafSRobert Mustacchi return (nvap); 628*b9cf0dafSRobert Mustacchi 629*b9cf0dafSRobert Mustacchi return (NULL); 630*b9cf0dafSRobert Mustacchi} 631*b9cf0dafSRobert Mustacchi 632*b9cf0dafSRobert Mustacchistatic void 633*b9cf0dafSRobert Mustacchifini(nv_alloc_t *nvap) 634*b9cf0dafSRobert Mustacchi{ 635*b9cf0dafSRobert Mustacchi nv_alloc_fini(nvap); 636*b9cf0dafSRobert Mustacchi kmem_free(nvap, sizeof(nv_alloc_t)); 637*b9cf0dafSRobert Mustacchi} 638*b9cf0dafSRobert Mustacchi 639*b9cf0dafSRobert Mustacchistatic int 640*b9cf0dafSRobert Mustacchiinterrupt_context(nv_alloc_t *nva) 641*b9cf0dafSRobert Mustacchi{ 642*b9cf0dafSRobert Mustacchi nvlist_t *nvl; 643*b9cf0dafSRobert Mustacchi int error; 644*b9cf0dafSRobert Mustacchi 645*b9cf0dafSRobert Mustacchi if ((error = nvlist_xalloc(&nvl, NV_UNIQUE_NAME, nva)) != 0) 646*b9cf0dafSRobert Mustacchi return (-1); 647*b9cf0dafSRobert Mustacchi 648*b9cf0dafSRobert Mustacchi if ((error = nvlist_add_int32(nvl, "name", 1234)) == 0) 649*b9cf0dafSRobert Mustacchi error = send_nvl(nvl); 650*b9cf0dafSRobert Mustacchi 651*b9cf0dafSRobert Mustacchi nvlist_free(nvl); 652*b9cf0dafSRobert Mustacchi return (error); 653*b9cf0dafSRobert Mustacchi} 654*b9cf0dafSRobert Mustacchi.Ed 655*b9cf0dafSRobert Mustacchi.Sh SEE ALSO 656*b9cf0dafSRobert Mustacchi.Xr bcopy 9F , 657*b9cf0dafSRobert Mustacchi.Xr kmem_alloc 9F , 658*b9cf0dafSRobert Mustacchi.Xr nvlist_add_byte 9F 659