nvlist_size man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

NVLIST_ALLOC(9F)					      NVLIST_ALLOC(9F)

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

SYNOPSIS
       #include <sys/nvpair.h>

       List Manipulation:

       int nvlist_alloc(nvlist_t **nvlp, uint_t nvflag,
	    int kmflag);

       int nvlist_xalloc(nvlist_t **nvlp, uint_t nvflag, nv_alloc_t *nva);

       void nvlist_free(nvlist_t *nvl);

       int nvlist_size(nvlist_t *nvl, size_t *size, int encoding);

       int nvlist_pack(nvlist_t *nvl, char **bufp, size_t *buflen, int encoding,
	    int flag);

       int nvlist_xpack(nvlist_t *nvl, char **bufp, size_t *buflen, int encoding,
	    nv_alloc_t *nva);

       int nvlist_unpack(char *buf, size_t buflen, nvlist_t **nvlp, int flag);

       int nvlist_xunpack(char *buf, size_t buflen, nvlist_t **nvlp,
	    nv_alloc_t *nva);

       int nvlist_dup(nvlist_t *nvl, nvlist_t **nvlp, int flag);

       int nvlist_xdup(nvlist_t *nvl, nvlist_t **nvlp, nv_alloc_t *nva);

       int nvlist_merge(nvlist_t *dst, nvlist_t *nvl, int flag);

       Pluggable Allocator Configuration:

       nv_alloc_t *nvlist_lookup_nv_alloc(nvlist_t *);

       int nv_alloc_init(nv_alloc_t *nva,
	    const nv_alloc_ops_t * nvo,/* args */ ...);

       void  nv_alloc_reset(nv_alloc_t	*nva);

       void  nv_alloc_fini(nv_alloc_t *nva);

       Pluggable Allocation Initialization with Fixed Allocator:

       int nv_alloc_init(nv_alloc_t *nva,
	    nv_fixed_ops, void * bufptr,  size_t sz);

INTERFACE LEVEL
       Solaris DDI specific (Solaris DDI)

PARAMETERS
       nvlp
		   Address  of	a  pointer  to	list   of   name-value	 pairs
		   (nvlist_t).

       nvflag
		   Specify bit fields defining nvlist_t properties:

		   NV_UNIQUE_NAME
					  nvpair names are unique.

		   NV_UNIQUE_NAME_TYPE
					  Name-data type combination is unique

       kmflag
		   Kernel   memory   allocation	 policy,  either  KM_SLEEP  or
		   KM_NOSLEEP.

       nvl
		   nvlist_t to be processed.

       dst
		   Destination nvlist_t.

       size
		   Pointer to buffer to contain the encoded size.

       bufp
		   Address of buffer to	 pack  nvlist  into.  Must  be	8-byte
		   aligned. If NULL, library will allocate memory.

       buf
		   Buffer containing packed nvlist_t.

       buflen
		   Size of buffer bufp or buf points to.

       encoding
		   Encoding method for packing.

       nvo
		   Pluggable allocator operations pointer (nv_alloc_ops_t).

       nva
		   Points  to a nv_alloc_t structure to be used for the speci‐
		   fied nvlist_t.

DESCRIPTION
       List Manipulation:

       The nvlist_alloc() function allocates a new name-value  pair  list  and
       updates	nvlp  to  point	 to  the handle. The argument nvflag specifies
       nvlist_t properties to remain persistent across packing, unpacking, and
       duplication.

       If NV_UNIQUE_NAME is specified for nvflag, existing nvpairs with match‐
       ing  names  are	removed	 before	 the   new   nvpair   is   added.   If
       NV_UNIQUE_NAME_TYPE  is	specified  for	nvflag,	 existing nvpairs with
       matching names and data types are removed  before  the  new  nvpair  is
       added. See nvlist_add_byte(9F) for more details.

       The  nvlist_xalloc()  function  differs	from  nvlist_alloc()  in  that
       nvlist_xalloc() can use a different  allocator,	as  described  in  the
       Pluggable Allocators section.

       The nvlist_free() function frees a name-value pair list.

       The  nvlist_size()  function  returns  the minimum size of a contiguous
       buffer large enough to pack nvl. The encoding parameter	specifies  the
       method of encoding when packing nvl. Supported encoding methods are:

       NV_ENCODE_NATIVE
			   Straight bcopy() as described in bcopy(9F).

       NV_ENCODE_XDR
			   Use	XDR  encoding, suitable for sending to another
			   host.

       The nvlist_pack() function packs nvl into contiguous memory starting at
       *bufp.  The  encoding  parameter	 specifies the method of encoding (see
       above).

	   o	  If *bufp is not NULL, *bufp is expected to be a caller-allo‐
		  cated	 buffer	 of  size  *buflen.  The  kmflag  argument  is
		  ignored.

	   o	  If *bufp is NULL, the library allocates memory  and  updates
		  *bufp	 to point to the memory and updates *buflen to contain
		  the size of the allocated memory. The value of kmflag	 indi‐
		  cates the memory allocation policy

       The   nvlist_xpack()   function	differs	 from  nvlist_pack()  in  that
       nvlist_xpack() can use a different allocator.

       The nvlist_unpack() function takes a buffer with a packed nvlist_t  and
       unpacks it into a searchable nvlist_t. The library allocates memory for
       nvlist_t. The caller is responsible for freeing the memory  by  calling
       nvlist_free().

       The  nvlist_xunpack()  function	differs	 from  nvlist_unpack() in that
       nvlist_xunpack() can use a different allocator.

       The nvlist_dup() function makes a copy of nvl and updates nvlp to point
       to the copy.

       The   nvlist_xdup()   function	differs	  from	nvlist_dup()  in  that
       nvlist_xdup() can use a different allocator.

       The nvlist_merge() function adds copies of all  name-value  pairs  from
       nvlist_t nvl to nvlist_t dst. Name-value pairs in dst are replaced with
       name-value pairs from nvl which have identical names (if	 dst  has  the
       type NV_UNIQUE_NAME), or identical names and types (if dst has the type
       NV_UNIQUE_NAME_TYPE).

       The nvlist_lookup_nv_alloc() function  retrieves	 the  pointer  to  the
       allocator used when manipulating a name-value pair list.

   PLUGGABLE ALLOCATORS
       Using Pluggable Allocators:

       The  nv_alloc_init(),  nv_alloc_reset()	and  nv_alloc_fini() functions
       provide an interface that specifies  the	 allocator  to	be  used  when
       manipulating a name-value pair list.

       The  nv_alloc_init() determines allocator properties and puts them into
       the nva argument. You need to specify  the  nv_arg  argument,  the  nvo
       argument	 and  an  optional variable argument list.  The optional argu‐
       ments are passed to the (*nv_ao_init()) function.

       The nva argument must be	 passed	 to  nvlist_xalloc(),  nvlist_xpack(),
       nvlist_xunpack() and nvlist_xdup().

       The  nv_alloc_reset()  function	resets the allocator properties to the
       data specified by nv_alloc_init(). When no (*nv_ao_reset()) function is
       specified, nv_alloc_reset() is without effect.

       The  nv_alloc_fini()  destroys  the  allocator properties determined by
       nv_alloc_init(). When a (*nv_ao_fini()) routine	is  specified,	it  is
       called from nv_alloc_fini().

       The  disposition	 of the allocated objects and the memory used to store
       them is left to the allocator implementation.

       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.

	 o  nv_alloc_nosleep
	 o  nv_alloc_sleep

       The nvpair framework provides a fixed-buffer allocator, accessible  via
       nv_fixed_ops.

	 o  nv_fixed_ops

       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.

       Memory freed using nvlist_free(), pair-removal, or similar routines  is
       not reclaimed.

       When  used  to  initialize  the	fixed-buffer  allocator, nv_alloc_init
       should be called as follows:

	 int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo,
	     void *bufptr, size_t sz);

       When invoked on a fixed-buffer, the  nv_alloc_reset()  function	resets
       the  fixed buffer and prepares it for re-use. The framework consumer is
       responsible for freeing the buffer passed to nv_alloc_init().

   CREATING PLUGGABLE ALLOCATORS
       Any producer of name-value pairs may possibily specify his own  alloca‐
       tor routines. You must provide the following pluggable allocator opera‐
       tions in the allocator implementation.

	 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 nva argument of the allocator implementation is  always  the	 first
       argument.

       The  optional  (*nv_ao_init() ) function is responsible for filling the
       data specified by nv_alloc_init() into  the  nva_arg()  argument.   The
       (*nv_ao_init())	function  is  called only when nv_alloc_init() is exe‐
       cuted.

       The optional (*nv_ao_fini()) function is responsible for the cleanup of
       the allocator implementation. It is called by nv_alloc_fini().

       The required (*nv_ao_alloc()) function is used in the nvpair allocation
       framework for memory allocation. The sz argument specifies the size  of
       the requested buffer.

       The optional (*nv_ao_reset()) function is responsible for resetting the
       nva_arg argument to the data specified by nv_alloc_init().

       The required (*nv_ao_free()) function is used in the  nvpair  allocator
       framework  for memory de-allocation. The argument buf is a pointer to a
       block previously allocated by (*nv_ao_alloc()) function. The size argu‐
       ment sz 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.

RETURN VALUES
       For nvlist_alloc(), nvlist_dup(), nvlist_xalloc(), and nvlist_xdup():

       0
		 success

       EINVAL
		 invalid argument

       ENOMEM
		 insufficient memory

       For nvlist_pack(),  nvlist_unpack(),  nvlist_xpack(),  and  nvlist_xun‐
       pack():

       0
		  success

       EINVAL
		  invalid argument

       ENOMEM
		  insufficient memory

       EFAULT
		  encode/decode error

       ENOTSUP
		  encode/decode method not supported

       For nvlist_size():

       0
		 success

       EINVAL
		 invalid argument

       For nvlist_lookup_nv_alloc():

       pointer to the allocator

USAGE
       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.

EXAMPLES
	   /*
	    * 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);
	       }

CONTEXT
       The nvlist_alloc(), nvlist_pack(),  nvlist_unpack(),  and  nvlist_dup()
       functions  can  be called from interrupt context only if the KM_NOSLEEP
       flag is set. They can be called from user context with any valid flag.

       The    nvlist_xalloc(),	  nvlist_xpack(),    nvlist_xunpack(),	   and
       nvlist_xdup()  functions	 can  be called from interrupt context only if
       (1) the default allocator is used and the KM_NOSLEEP 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).

       These functions can be called from user	or  kernel  context  with  any
       valid flag.

				 Jan 16, 2006		      NVLIST_ALLOC(9F)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net