nvlist_alloc 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(3NVPAIR)					 NVLIST_ALLOC(3NVPAIR)

NAME
       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

SYNOPSIS
       cc [ flag... ] file... -lnvpair [ library... ]
       #include <libnvpair.h>

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

       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);

       nv_alloc_t * nvlist_lookup_nv_alloc(nvlist_t *nvl);

       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);

PARAMETERS
       nvlp
		   Address of a pointer to nvlist_t.

       nvflag
		   Specify bit fields defining nvlist properties:

		   NV_UNIQUE_NAME
					  The nvpair names are unique.

		   NV_UNIQUE_NAME_TYPE
					  Name-data   type   combination    is
					  unique.

       flag
		   Specify 0. Reserved for future use.

       nvl
		   The nvlist_t to be processed.

       dst
		   The 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.

       buflen
		   Size of buffer bufp or buf points to.

       encoding
		   Encoding method for packing.

       nvo
		   Pluggable allocator operations pointer (nv_alloc_ops_t).

       nva
		   A pointer to an nv_alloc_t structure to  be	used  for  the
		   specified 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  nvflag  argument  specifies
       nvlist  properties  to remain persistent across packing, unpacking, and
       duplication. If	NV_UNIQUE_NAME	was  specified	for  nvflag,  existing
       nvpairs with matching names are removed before the new nvpair is added.
       If NV_UNIQUE_NAME_TYPE was specified for nvflag, existing nvpairs  with
       matching	 names	and  data  types  are removed before the new nvpair is
       added. See nvlist_add_byte(3NVPAIR) for more information.

       The nvlist_xalloc() function is identical to nvlist_alloc() except 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(3C).

       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.

	   o	  If *bufp is NULL,  the  library  will	 allocate  memory  and
		  update  *bufp	 to  point to the memory and update *buflen to
		  contain the size of the allocated memory.

       The nvlist_xpack() function is identical to nvlist_pack()  except  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 is identical  to  nvlist_unpack()	except
       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 is identical	to  nvlist_dup()  except  that
       nvlist_xdup() can use a different allocator.

       The  nvlist_merge()  function  adds copies of all name-value pairs from
       nvl to dst.  Name-value pairs in dst are replaced with name-value pairs
       from nvl that 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 that was 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 to specify the allocator to be used	 when  manipu‐
       lating a name-value pair list.

       The  nv_alloc_init()  function  determines the allocator properties and
       puts them into the nva  argument.  The  application  must  specify  the
       nv_arg  and  nvo	 arguments and an optional variable argument list. The
       optional arguments 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 is responsible for resetting the alloca‐
       tor properties to  the  data  specified	by  nv_alloc_init().  When  no
       (*nv_ao_reset()) function is specified, nv_alloc_reset() has no effect.

       The  nv_alloc_fini()  function destroys the allocator properties deter‐
       mined by nv_alloc_init(). When a (*nv_ao_fini()) function 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_nosleep nv_alloc_t can be  used  with  nvlist_xalloc()  to
       mimic the behavior of nvlist_alloc().

       The  nvpair  allocator  framework  provides  a pointer to the operation
       structure of a fixed buffer allocator.  This  allocator,	 nv_fixed_ops,
       uses a pre-allocated buffer for memory allocations. It is intended pri‐
       marily for kernel use and is described on nvlist_alloc(9F).

       An example program that uses the pluggable allocator  functionality  is
       provided on nvlist_alloc(9F).

   Creating Pluggable Allocators
       Any  producer  of  name-value pairs can specify its own allocator func‐
       tions. 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  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 only called 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 deallocation. The buf argument is a pointer	 to  a
       block  previously  allocated by the (*nv_ao_alloc()) function. The size
       argument 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
       These functions return 0 on success and an error value on failure.

       The  nvlist_lookup_nv_alloc()  function returns a pointer to an alloca‐
       tor.

ERRORS
       These functions will fail if:

       EINVAL
		 There is an invalid argument.

       The  nvlist_alloc(),  nvlist_dup(),   nvlist_pack(),   nvlist_unpack(),
       nvlist_merge(),	nvlist_xalloc(),  nvlist_xdup(),  nvlist_xpack(),  and
       nvlist_xunpack() functions will fail if:

       ENOMEM
		 There is insufficient memory.

       The nvlist_pack(),  nvlist_unpack(),  nvlist_xpack(),  and  nvlist_xun‐
       pack() functions will fail if:

       EFAULT
		  An encode/decode error occurs.

       ENOTSUP
		  An encode/decode method is not supported.

EXAMPLES
	 /*
	  * Program to create an nvlist.
	  */
	 #include <stdio.h>
	 #include <sys/types.h>
	 #include <string.h>
	 #include <libnvpair.h>

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

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Evolving	      │
       ├────────────────────┼─────────────────┤
       │MT-Level	    │ MT-Safe	      │
       └────────────────────┴─────────────────┘

SEE ALSO
       libnvpair(3LIB), attributes(5), nvlist_alloc(9F)

				  Feb 2, 2004		 NVLIST_ALLOC(3NVPAIR)
[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