nvlist_unpack(3EXT)

NAME | SYNOPSIS | API RESTRICTIONS | PARAMETERS | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES

NAME

nvlist_alloc, nvlist_free, nvlist_size, nvlist_pack, nvlist_unpack, nvlist_dup- allocate and manage name-value pair lists.

SYNOPSIS

$(OS_DIR)/lib/libnvpair.a
#include <libnvpair.h>
#include <sys/nvpair.h>

int nvlist_alloc(nvlist_t ** nvlp, uint_t nvflag, int kmflag);
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 kmflag);
int nvlist_unpack(char * buf, nvlist_t * nvlp, int kmflag);
int nvlist_dup(nvlist_t * nvl, nvlist_t * nvlp, int kmflag);

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

PARAMETERS

nvlp

Address of a pointer to nvlist_t .

nvflag

Attribute replacing policy, can be set to NV_UNIQUE_NAME or NV_UNIQUE_NAME_TYPE ;

kmflag

Microkernel memory allocation policy, either KM_SLEEP or KM_NOSLEEP . Not used in userland

nvl

nvlist_t to be processed

size

Pointer to buffer to contain the encoded size

bufp

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

buflen

Size of buffer bufp points to

buf

Buffer containing packed nvlist

encoding

Encoding method for packing

DESCRIPTION

The nvlist_alloc() function allocates a name-value pair list and updates nvlp so that it points to the handle.

If nvflag is set to NV_UNIQUE_NAME , attributes' names are kept unique: when a name is added to the attribute list, any attribute previously added with the same name is removed. If nvflag is set to NV_UNIQUE_NAME_TYPE , the name-type pair is kept unique: when a name is added to the attribute list, any attribute with the same name and type is removed.

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 copy

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.

If *bufp is not NULL , *bufp is expected to be a caller-allocated buffer of size *buflen . The kmflag argument is ignored;

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. If the call is made in the microkernel, kmflag indicates the memory allocation policy.

The nvlist_unpack() function takes buffer with a packed nvlist_t and unpacks them into a searchable nvlist_t . The library will manage the memory allocation.

RETURN VALUE

These functions return 0 on success. Otherwise, they return one of the following error codes.

ERRORS

• nvlist_alloc() - nvlist_dup()

  [EINVAL]

  Some of the arguments are null pointers

  [ENOMEM]

  Insufficient memory

• nvlist_pack() - nvlist_unpack()

  [EINVAL]

  Invalid argument

  [ENOMEN]

  Insuffcient memory

  [EFAULT]

  Encode/decode error

  [ENOTSUP]

  Encode/decode method not supported

• nvlist_size()

  [EINVAL]

  Invalid argument

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

ChorusOS 5.0  Last Revised December 2001

NAME | SYNOPSIS | API RESTRICTIONS | PARAMETERS | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES