'\" te
.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH nvlist_alloc 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
nvlist_alloc, nvlist_free, nvlist_size, nvlist_pack, nvlist_unpack, nvlist_dup,
nv_alloc_init, nv_alloc_fini, nvlist_xalloc, nvlist_xpack, nvlist_xunpack,
nvlist_xdup, nvlist_merge \- Manage a name-value pair list
.SH SYNOPSIS
.LP
.nf
#include <sys/nvpair.h> 

List Manipulation:

\fBint\fR \fBnvlist_alloc\fR(\fBnvlist_t **\fR\fInvlp\fR, \fBuint_t\fR \fInvflag\fR,
     \fBint\fR \fIkmflag\fR);
.fi

.LP
.nf
\fBint\fR \fBnvlist_xalloc\fR(\fBnvlist_t **\fR\fInvlp\fR, \fBuint_t\fR \fInvflag\fR, \fBnv_alloc_t *\fR\fInva\fR);
.fi

.LP
.nf
\fBvoid\fR \fBnvlist_free\fR(\fBnvlist_t *\fR\fInvl\fR);
.fi

.LP
.nf
\fBint\fR \fBnvlist_size\fR(\fBnvlist_t *\fR\fInvl\fR, \fBsize_t *\fR\fIsize\fR, \fBint\fR \fIencoding\fR);
.fi

.LP
.nf
\fBint\fR \fBnvlist_pack\fR(\fBnvlist_t *\fR\fInvl\fR, \fBchar **\fR\fIbufp\fR, \fBsize_t *\fR\fIbuflen\fR, \fBint\fR \fIencoding\fR,
     \fBint\fR \fIflag\fR);
.fi

.LP
.nf
\fBint\fR \fBnvlist_xpack\fR(\fBnvlist_t *\fR\fInvl\fR, \fBchar **\fR\fIbufp\fR, \fBsize_t *\fR\fIbuflen\fR, \fBint\fR \fIencoding\fR,
     \fBnv_alloc_t *\fR\fInva\fR);
.fi

.LP
.nf
\fBint\fR \fBnvlist_unpack\fR(\fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIbuflen\fR, \fBnvlist_t **\fR\fInvlp\fR, \fBint\fR \fIflag\fR);
.fi

.LP
.nf
\fBint\fR \fBnvlist_xunpack\fR(\fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIbuflen\fR, \fBnvlist_t **\fR\fInvlp\fR, 
     \fBnv_alloc_t *\fR\fInva\fR);
.fi

.LP
.nf
\fBint\fR \fBnvlist_dup\fR(\fBnvlist_t *\fR\fInvl\fR, \fBnvlist_t **\fR\fInvlp\fR, \fBint\fR \fIflag\fR);
.fi

.LP
.nf
\fBint\fR \fBnvlist_xdup\fR(\fBnvlist_t *\fR\fInvl\fR, \fBnvlist_t **\fR\fInvlp\fR, \fBnv_alloc_t *\fR\fInva\fR);
.fi

.LP
.nf
\fBint\fR \fBnvlist_merge\fR(\fBnvlist_t *\fR\fIdst\fR, \fBnvlist_t *\fR\fInvl\fR, \fBint\fR \fIflag\fR);
.fi

.LP
.nf
Pluggable Allocator Configuration:

\fBnv_alloc_t *\fR\fBnvlist_lookup_nv_alloc\fR(\fBnvlist_t *);\fR
.fi

.LP
.nf
\fBint\fR \fBnv_alloc_init\fR(\fBnv_alloc_t *\fR\fInva\fR, 
     \fBconst nv_alloc_ops_t *\fR \fInvo,\fR/* args */ ...);
.fi

.LP
.nf
\fBvoid\fR  \fBnv_alloc_reset\fR(\fBnv_alloc_t  *\fR\fInva\fR);
.fi

.LP
.nf
\fBvoid\fR  \fBnv_alloc_fini\fR(\fBnv_alloc_t *\fR\fInva\fR);
.fi

.LP
.nf
Pluggable Allocation Initialization with Fixed Allocator:

\fBint\fR \fBnv_alloc_init\fR(\fBnv_alloc_t *\fR\fInva\fR,
     \fBnv_fixed_ops\fR, \fBvoid *\fR \fIbufptr\fR,  \fBsize_t\fR sz);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fInvlp\fR\fR
.ad
.RS 12n
.rt  
Address of a pointer to list of name-value pairs (\fBnvlist_t\fR).
.RE

.sp
.ne 2
.mk
.na
\fB\fInvflag\fR\fR
.ad
.RS 12n
.rt  
Specify bit fields defining \fBnvlist_t\fR properties:
.sp
.ne 2
.mk
.na
\fB\fBNV_UNIQUE_NAME\fR\fR
.ad
.RS 23n
.rt  
\fBnvpair\fR names are unique.
.RE

.sp
.ne 2
.mk
.na
\fB\fBNV_UNIQUE_NAME_TYPE\fR\fR
.ad
.RS 23n
.rt  
Name-data type combination is unique
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fIkmflag\fR\fR
.ad
.RS 12n
.rt  
Kernel memory allocation policy, either \fBKM_SLEEP\fR or \fBKM_NOSLEEP\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fInvl\fR\fR
.ad
.RS 12n
.rt  
\fBnvlist_t\fR to be processed.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdst\fR\fR
.ad
.RS 12n
.rt  
Destination \fBnvlist_t\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIsize\fR\fR
.ad
.RS 12n
.rt  
Pointer to buffer to contain the encoded size.
.RE

.sp
.ne 2
.mk
.na
\fB\fIbufp\fR\fR
.ad
.RS 12n
.rt  
Address of buffer to pack \fBnvlist\fR into. Must be 8-byte aligned. If NULL,
library will allocate memory.
.RE

.sp
.ne 2
.mk
.na
\fB\fIbuf\fR\fR
.ad
.RS 12n
.rt  
Buffer containing packed \fBnvlist_t\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIbuflen\fR\fR
.ad
.RS 12n
.rt  
Size of buffer \fIbufp\fR or \fIbuf\fR points to.
.RE

.sp
.ne 2
.mk
.na
\fB\fIencoding\fR\fR
.ad
.RS 12n
.rt  
Encoding method for packing.
.RE

.sp
.ne 2
.mk
.na
\fB\fInvo\fR\fR
.ad
.RS 12n
.rt  
Pluggable allocator operations pointer (nv_alloc_ops_t).
.RE

.sp
.ne 2
.mk
.na
\fB\fInva\fR\fR
.ad
.RS 12n
.rt  
Points to a nv_alloc_t structure to be used for the specified \fBnvlist_t\fR.
.RE

.SH DESCRIPTION
.sp
.LP
List Manipulation:
.sp
.LP
The \fBnvlist_alloc()\fR function allocates a new name-value pair list and
updates \fInvlp\fR to point to the handle. The argument \fInvflag\fR specifies
\fBnvlist_t\fR properties to remain persistent across packing, unpacking, and
duplication.
.sp
.LP
If \fBNV_UNIQUE_NAME\fR is specified for nvflag, existing nvpairs with matching
names are removed before the new nvpair is added. If \fBNV_UNIQUE_NAME_TYPE\fR
is specified for nvflag, existing nvpairs with matching names and data types
are removed before the new nvpair is added. See \fBnvlist_add_byte\fR(9F) for
more details.
.sp
.LP
The \fBnvlist_xalloc()\fR function differs from \fBnvlist_alloc()\fR in that
\fBnvlist_xalloc()\fR can use a different allocator, as described in the
Pluggable Allocators section.
.sp
.LP
The \fBnvlist_free()\fR function frees a name-value pair list.
.sp
.LP
The \fBnvlist_size()\fR function returns the minimum size of a contiguous
buffer large enough to pack \fInvl\fR. The \fIencoding\fR parameter specifies
the method of encoding when packing \fInvl\fR. Supported encoding methods are:
.sp
.ne 2
.mk
.na
\fB\fBNV_ENCODE_NATIVE\fR\fR
.ad
.RS 20n
.rt  
Straight \fBbcopy()\fR as described in \fBbcopy\fR(9F).
.RE

.sp
.ne 2
.mk
.na
\fB\fBNV_ENCODE_XDR\fR\fR
.ad
.RS 20n
.rt  
Use XDR encoding, suitable for sending to another host.
.RE

.sp
.LP
The \fBnvlist_pack()\fR function packs \fInvl\fR into contiguous memory
starting at *\fIbufp\fR. The \fIencoding\fR parameter specifies the method of
encoding (see above).
.RS +4
.TP
.ie t \(bu
.el o
If *\fIbufp\fR is not NULL, *\fIbufp\fR is expected to be a caller-allocated
buffer of size *\fIbuflen\fR. The \fIkmflag\fR argument is ignored.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If *\fIbufp\fR is NULL, the library allocates memory and updates *\fIbufp\fR to
point to the memory and updates *\fIbuflen\fR to contain the size of the
allocated memory. The value of \fIkmflag\fR indicates the memory allocation
policy
.RE
.sp
.LP
The \fBnvlist_xpack()\fR function differs from \fBnvlist_pack()\fR in that
\fBnvlist_xpack()\fR can use a different allocator.
.sp
.LP
The \fBnvlist_unpack()\fR function takes a buffer with a packed \fBnvlist_t\fR
and unpacks it into a searchable \fBnvlist_t\fR. The library allocates memory
for \fBnvlist_t\fR. The caller is responsible for freeing the memory by calling
\fBnvlist_free()\fR.
.sp
.LP
The \fBnvlist_xunpack()\fR function differs from \fBnvlist_unpack()\fR in that
\fBnvlist_xunpack()\fR can use a different allocator.
.sp
.LP
The \fBnvlist_dup()\fR function makes a copy of \fInvl\fR and updates
\fInvlp\fR to point to the copy.
.sp
.LP
The \fBnvlist_xdup()\fR function differs from \fBnvlist_dup()\fR in that
\fBnvlist_xdup()\fR can use a different allocator.
.sp
.LP
The \fBnvlist_merge()\fR function adds copies of all name-value pairs from
\fBnvlist_t\fR \fInvl\fR to \fBnvlist_t dst\fR. Name-value pairs in dst are
replaced with name-value pairs from \fBnvl\fR which have identical names (if
dst has the type \fBNV_UNIQUE_NAME\fR), or identical names and types (if dst
has the type \fBNV_UNIQUE_NAME_TYPE\fR).
.sp
.LP
The \fBnvlist_lookup_nv_alloc()\fR function retrieves the pointer to the
allocator used when manipulating a name-value pair list.
.SS "PLUGGABLE ALLOCATORS"
.sp
.LP
Using Pluggable Allocators:
.sp
.LP
The \fBnv_alloc_init()\fR, \fBnv_alloc_reset()\fR and \fBnv_alloc_fini()\fR
functions provide an interface that specifies the allocator to be used when
manipulating a name-value pair list.
.sp
.LP
The \fBnv_alloc_init()\fR determines allocator properties and puts them into
the \fInva\fR argument. You need to specify the \fInv_arg\fR argument, the
\fInvo\fR argument and an optional variable argument list.  The optional
arguments are passed to the (*\fBnv_ao_init()\fR) function.
.sp
.LP
The \fInva\fR argument must be passed to \fBnvlist_xalloc()\fR,
\fBnvlist_xpack()\fR, \fBnvlist_xunpack()\fR and \fBnvlist_xdup()\fR.
.sp
.LP
The \fBnv_alloc_reset()\fR function resets the allocator properties to the data
specified by \fBnv_alloc_init()\fR. When no (*\fBnv_ao_reset()\fR) function is
specified, \fBnv_alloc_reset()\fR is without effect.
.sp
.LP
The \fBnv_alloc_fini()\fR destroys the allocator properties determined by
\fBnv_alloc_init()\fR. When a (*\fBnv_ao_fini()\fR) routine is specified, it is
called from \fBnv_alloc_fini()\fR.
.sp
.LP
The disposition of the allocated objects and the memory used to store them is
left to the allocator implementation.
.sp
.LP
The `nv_alloc_sleep' and `nv_alloc_nosleep' nv_alloc_t pointers may be used
with nvlist_xalloc to mimic the behavior of nvlist_alloc with KM_SLEEP and
KM_NOSLEEP, respectively.
.sp
.in +2
.nf
o  nv_alloc_nosleep
o  nv_alloc_sleep
.fi
.in -2

.sp
.LP
The nvpair framework provides a fixed-buffer allocator, accessible via
nv_fixed_ops.
.sp
.in +2
.nf
o  nv_fixed_ops
.fi
.in -2

.sp
.LP
Given a buffer size and address, the fixed-buffer allocator allows for the
creation of nvlists in contexts where malloc or kmem_alloc services may not be
available. The fixed-buffer allocator is designed primarily to support the
creation of nvlists.
.sp
.LP
Memory freed using \fBnvlist_free()\fR, pair-removal, or similar routines is
not reclaimed.
.sp
.LP
When used to initialize the fixed-buffer allocator, nv_alloc_init should be
called as follows:
.sp
.in +2
.nf
int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo,
    void *bufptr, size_t sz);
.fi
.in -2

.sp
.LP
When invoked on a fixed-buffer, the \fBnv_alloc_reset()\fR function resets the
fixed buffer and prepares it for re-use. The framework consumer is responsible
for freeing the buffer passed to \fBnv_alloc_init()\fR.
.SS "CREATING PLUGGABLE ALLOCATORS"
.sp
.LP
Any producer of name-value pairs may possibily specify his own allocator
routines. You must provide the following pluggable allocator operations in the
allocator implementation.
.sp
.in +2
.nf
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);
.fi
.in -2

.sp
.LP
The \fInva\fR argument of the allocator implementation is always the first
argument.
.sp
.LP
The optional (*\fBnv_ao_init()\fR ) function is responsible for filling the
data specified by \fBnv_alloc_init()\fR into the \fBnva_arg()\fR argument.  The
(*\fBnv_ao_init()\fR) function is called only when \fBnv_alloc_init()\fR is
executed.
.sp
.LP
The optional (*\fBnv_ao_fini()\fR) function is responsible for the cleanup of
the allocator implementation. It is called by \fBnv_alloc_fini()\fR.
.sp
.LP
The required (*\fBnv_ao_alloc()\fR) function is used in the nvpair allocation
framework for memory allocation. The sz argument specifies the size of the
requested buffer.
.sp
.LP
The optional (*\fBnv_ao_reset()\fR) function is responsible for resetting the
nva_arg argument to the data specified by \fBnv_alloc_init()\fR.
.sp
.LP
The required (*\fBnv_ao_free()\fR) function is used in the nvpair allocator
framework for memory de-allocation. The argument buf is a pointer to a block
previously allocated by (*\fBnv_ao_alloc()\fR) function. The size argument sz
must exactly match the original allocation.
.sp
.LP
The disposition of the allocated objects and the memory used to store them is
left to the allocator implementation.
.SH RETURN VALUES
.sp
.LP
For \fBnvlist_alloc()\fR, \fBnvlist_dup()\fR, \fBnvlist_xalloc()\fR, and
\fBnvlist_xdup()\fR:
.sp
.ne 2
.mk
.na
\fB\fB0\fR\fR
.ad
.RS 10n
.rt  
success
.RE

.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
invalid argument
.RE

.sp
.ne 2
.mk
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 10n
.rt  
insufficient memory
.RE

.sp
.LP
For \fBnvlist_pack()\fR, \fBnvlist_unpack()\fR, \fBnvlist_xpack()\fR, and
\fBnvlist_xunpack()\fR:
.sp
.ne 2
.mk
.na
\fB\fB0\fR\fR
.ad
.RS 11n
.rt  
success
.RE

.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 11n
.rt  
invalid argument
.RE

.sp
.ne 2
.mk
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 11n
.rt  
insufficient memory
.RE

.sp
.ne 2
.mk
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 11n
.rt  
encode/decode error
.RE

.sp
.ne 2
.mk
.na
\fB\fBENOTSUP\fR\fR
.ad
.RS 11n
.rt  
encode/decode method not supported
.RE

.sp
.LP
For \fBnvlist_size()\fR:
.sp
.ne 2
.mk
.na
\fB\fB0\fR\fR
.ad
.RS 10n
.rt  
success
.RE

.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
invalid argument
.RE

.sp
.LP
For \fBnvlist_lookup_nv_alloc()\fR:
.sp
.LP
pointer to the allocator
.SH USAGE
.sp
.LP
The fixed-buffer allocator is very simple allocator. It uses a pre-allocated
buffer for memory allocations and it can be used in interrupt context. You are
responsible for allocation and de-allocation for the pre-allocated buffer.
.SH EXAMPLES
.sp
.in +2
.nf
  /*
   * using the fixed-buffer allocator.
   */
   #include <sys/nvpair.h>
      
  /* initialize the nvpair allocator framework */
  static nv_alloc_t *
  init(char *buf, size_t size)
  {
       nv_alloc_t *nvap;
 
       if ((nvap = kmem_alloc(sizeof(nv_alloc_t), KM_SLEEP)) == NULL)
           return (NULL);
 
       if (nv_alloc_init(nvap, nv_fixed_ops, buf, size) == 0)
           return (nvap);
 
       return (NULL);
   }
 
   static void
   fini(nv_alloc_t *nvap)
   {
         nv_alloc_fini(nvap);
         kmem_free(nvap, sizeof(nv_alloc_t));
   } 
    static int
    interrupt_context(nv_alloc_t *nva)
    {
       nvlist_t *nvl;
       int error;
 
       if ((error = nvlist_xalloc(&nvl, NV_UNIQUE_NAME, nva)) != 0)
            return (-1);
 
       if ((error = nvlist_add_int32(nvl, "name", 1234)) == 0)
            error = send_nvl(nvl);
      
       nvlist_free(nvl); 
       return (error);
      }
.fi
.in -2

.SH CONTEXT
.sp
.LP
The \fBnvlist_alloc()\fR, \fBnvlist_pack()\fR, \fBnvlist_unpack()\fR, and
\fBnvlist_dup()\fR functions can be called from interrupt context only if the
\fBKM_NOSLEEP\fR flag is set. They can be called from user context with any
valid flag.
.sp
.LP
The \fBnvlist_xalloc()\fR, \fBnvlist_xpack()\fR, \fBnvlist_xunpack()\fR, and
\fBnvlist_xdup()\fR functions can be called from interrupt context only if (1)
the default allocator is used and the \fBKM_NOSLEEP\fR flag is set or (2) the
specified allocator did not sleep for free memory (for example, it uses a
pre-allocated buffer for memory allocations).
.sp
.LP
These functions can be called from user or kernel context with any valid flag.