GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  NVLIST_NEXT (3)

NAME

nvlist_create, nvlist_destroy, nvlist_error, nvlist_set_error, nvlist_empty, nvlist_flags, nvlist_exists, nvlist_free, nvlist_clone, nvlist_dump, nvlist_fdump, nvlist_size, nvlist_pack, nvlist_unpack, nvlist_send, nvlist_recv, nvlist_xfer, nvlist_next, nvlist_add, nvlist_move, nvlist_get, nvlist_take - library for name/value pairs

CONTENTS

Library
Synopsis
Description
Examples
See Also
History
Authors

LIBRARY


.Lb libnv

SYNOPSIS


.In nv.h nvlist_t * nvlist_create int flags void nvlist_destroy nvlist_t *nvl int nvlist_error const nvlist_t *nvl void nvlist_set_error nvlist_t *nvl, int error bool nvlist_empty const nvlist_t *nvl int nvlist_flags const nvlist_t *nvl nvlist_t * nvlist_clone const nvlist_t *nvl void nvlist_dump const nvlist_t *nvl, int fd void nvlist_fdump const nvlist_t *nvl, FILE *fp size_t nvlist_size const nvlist_t *nvl void * nvlist_pack const nvlist_t *nvl size_t *sizep nvlist_t * nvlist_unpack const void *buf size_t size int nvlist_send int sock const nvlist_t *nvl nvlist_t * nvlist_recv int sock nvlist_t * nvlist_xfer int sock nvlist_t *nvl const char * nvlist_next const nvlist_t *nvl int *typep void **cookiep bool nvlist_exists const nvlist_t *nvl const char *name bool nvlist_exists_type const nvlist_t *nvl const char *name int type bool nvlist_exists_null const nvlist_t *nvl const char *name bool nvlist_exists_bool const nvlist_t *nvl const char *name bool nvlist_exists_number const nvlist_t *nvl const char *name bool nvlist_exists_string const nvlist_t *nvl const char *name bool nvlist_exists_nvlist const nvlist_t *nvl const char *name bool nvlist_exists_descriptor const nvlist_t *nvl const char *name bool nvlist_exists_binary const nvlist_t *nvl const char *name void nvlist_add_null nvlist_t *nvl const char *name void nvlist_add_bool nvlist_t *nvl const char *name bool value void nvlist_add_number nvlist_t *nvl const char *name uint64_t value void nvlist_add_string nvlist_t *nvl const char *name const char *value void nvlist_add_stringf nvlist_t *nvl const char *name const char *valuefmt ... void nvlist_add_stringv nvlist_t *nvl const char *name const char *valuefmt va_list valueap void nvlist_add_nvlist nvlist_t *nvl const char *name const nvlist_t *value void nvlist_add_descriptor nvlist_t *nvl const char *name int value void nvlist_add_binary nvlist_t *nvl const char *name const void *value size_t size void nvlist_move_string nvlist_t *nvl const char *name char *value void nvlist_move_nvlist nvlist_t *nvl const char *name nvlist_t *value void nvlist_move_descriptor nvlist_t *nvl const char *name int value void nvlist_move_binary nvlist_t *nvl const char *name void *value size_t size bool nvlist_get_bool const nvlist_t *nvl const char *name uint64_t nvlist_get_number const nvlist_t *nvl const char *name const char * nvlist_get_string const nvlist_t *nvl const char *name const nvlist_t * nvlist_get_nvlist const nvlist_t *nvl const char *name int nvlist_get_descriptor const nvlist_t *nvl const char *name const void * nvlist_get_binary const nvlist_t *nvl const char *name size_t *sizep const nvlist_t * nvlist_get_parent const nvlist_t *nvl void **cookiep bool nvlist_take_bool nvlist_t *nvl const char *name uint64_t nvlist_take_number nvlist_t *nvl const char *name char * nvlist_take_string nvlist_t *nvl const char *name nvlist_t * nvlist_take_nvlist nvlist_t *nvl const char *name int nvlist_take_descriptor nvlist_t *nvl const char *name void * nvlist_take_binary nvlist_t *nvl const char *name size_t *sizep void nvlist_free nvlist_t *nvl const char *name void nvlist_free_type nvlist_t *nvl const char *name int type void nvlist_free_null nvlist_t *nvl const char *name void nvlist_free_bool nvlist_t *nvl const char *name void nvlist_free_number nvlist_t *nvl const char *name void nvlist_free_string nvlist_t *nvl const char *name void nvlist_free_nvlist nvlist_t *nvl const char *name void nvlist_free_descriptor nvlist_t *nvl const char *name void nvlist_free_binary nvlist_t *nvl const char *name

DESCRIPTION

The libnv library allows to easily manage name value pairs as well as send and receive them over sockets. A group (list) of name value pairs is called an nvlist. The API supports the following data types:
null( NV_TYPE_NULL) There is no data associated with the name.
bool( NV_TYPE_BOOL) The value can be either true or false.
number( NV_TYPE_NUMBER) The value is a number stored as
.Vt uint64_t .
string( NV_TYPE_STRING) The value is a C string.
nvlist( NV_TYPE_NVLIST) The value is a nested nvlist.
descriptor( NV_TYPE_DESCRIPTOR) The value is a file descriptor. Note that file descriptors can be sent only over unix(4) domain sockets.
binary( NV_TYPE_BINARY) The value is a binary buffer.

The nvlist_create function allocates memory and initializes an nvlist.

The following flag can be provided:

NV_FLAG_IGNORE_CASE
  Perform case-insensitive lookups of provided names.

The nvlist_destroy function destroys the given nvlist. Function does nothing if NULL nvlist is provided. Function never modifies the errno global variable.

The nvlist_error function returns any error value that the nvlist accumulated. If the given nvlist is NULL the ENOMEM error will be returned.

The nvlist_set_error function sets an nvlist to be in the error state. Subsequent calls to nvlist_error will return the given error value. This function cannot be used to clear the error state from an nvlist. This function does nothing if the nvlist is already in the error state.

The nvlist_empty function returns true if the given nvlist is empty and false otherwise. The nvlist must not be in error state.

The nvlist_flags function returns flags used to create the nvlist with the nvlist_create function.

The nvlist_clone functions clones the given nvlist. The clone shares no resources with its origin. This also means that all file descriptors that are part of the nvlist will be duplicated with the dup(2) system call before placing them in the clone.

The nvlist_dump dumps nvlist content for debugging purposes to the given file descriptor fd.

The nvlist_fdump dumps nvlist content for debugging purposes to the given file stream fp.

The nvlist_size function returns the size of the given nvlist after converting it to binary buffer with the nvlist_pack function.

The nvlist_pack function converts the given nvlist to a binary buffer. The function allocates memory for the buffer, which should be freed with the free(3) function. If the sizep argument is not NULL, the size of the buffer will be stored there. The function returns NULL in case of an error (allocation failure). If the nvlist contains any file descriptors NULL will be returned. The nvlist must not be in error state.

The nvlist_unpack function converts the given buffer to the nvlist. The function returns NULL in case of an error.

The nvlist_send function sends the given nvlist over the socket given by the sock argument. Note that nvlist that contains file descriptors can only be send over unix(4) domain sockets.

The nvlist_recv function receives nvlist over the socket given by the sock argument.

The nvlist_xfer function sends the given nvlist over the socket given by the sock argument and receives nvlist over the same socket. The given nvlist is always destroyed.

The nvlist_next function iterates over the given nvlist returning names and types of subsequent elements. The cookiep argument allows the function to figure out which element should be returned next. The *cookiep should be set to NULL for the first call and should not be changed later. Returning NULL means there are no more elements on the nvlist. The typep argument can be NULL. Elements may not be removed from the nvlist while traversing it. The nvlist must not be in error state.

The nvlist_exists function returns true if element of the given name exists (besides of its type) or false otherwise. The nvlist must not be in error state.

The nvlist_exists_type function returns true if element of the given name and the given type exists or false otherwise. The nvlist must not be in error state.

The nvlist_exists_null, nvlist_exists_bool, nvlist_exists_number, nvlist_exists_string, nvlist_exists_nvlist, nvlist_exists_descriptor, nvlist_exists_binary functions return true if element of the given name and the given type determined by the function name exists or false otherwise. The nvlist must not be in error state.

The nvlist_add_null, nvlist_add_bool, nvlist_add_number, nvlist_add_string, nvlist_add_stringf, nvlist_add_stringv, nvlist_add_nvlist, nvlist_add_descriptor, nvlist_add_binary functions add element to the given nvlist. When adding string or binary buffor the functions will allocate memory and copy the data over. When adding nvlist, the nvlist will be cloned and clone will be added. When adding descriptor, the descriptor will be duplicated using the dup(2) system call and the new descriptor will be added. If an error occurs while adding new element, internal error is set which can be examined using the nvlist_error function.

The nvlist_move_string, nvlist_move_nvlist, nvlist_move_descriptor, nvlist_move_binary functions add new element to the given nvlist, but unlike nvlist_add_<type> functions they will consume the given resource. If an error occurs while adding new element, the resource is destroyed and internal error is set which can be examined using the nvlist_error function.

The nvlist_get_bool, nvlist_get_number, nvlist_get_string, nvlist_get_nvlist, nvlist_get_descriptor, nvlist_get_binary functions allow to obtain value of the given name. In case of string, nvlist, descriptor or binary, returned resource should not be modified - it still belongs to the nvlist. If element of the given name does not exist, the program will be aborted. To avoid that the caller should check for existence before trying to obtain the value or use dnvlist(3) extension, which allows to provide default value for a missing element. The nvlist must not be in error state.

The nvlist_get_parent function allows to obtain the parent nvlist from the nested nvlist.

The nvlist_take_bool, nvlist_take_number, nvlist_take_string, nvlist_take_nvlist, nvlist_take_descriptor, nvlist_take_binary functions return value associated with the given name and remove the element from the nvlist. In case of string and binary values, the caller is responsible for free returned memory using the free(3) function. In case of nvlist, the caller is responsible for destroying returned nvlist using the nvlist_destroy function. In case of descriptor, the caller is responsible for closing returned descriptor using the close 2 system call. If element of the given name does not exist, the program will be aborted. To avoid that the caller should check for existence before trying to obtain the value or use dnvlist(3) extension, which allows to provide default value for a missing element. The nvlist must not be in error state.

The nvlist_free function removes element of the given name from the nvlist (besides of its type) and frees all resources associated with it. If element of the given name does not exist, the program will be aborted. The nvlist must not be in error state.

The nvlist_free_type function removes element of the given name and the given type from the nvlist and frees all resources associated with it. If element of the given name and the given type does not exist, the program will be aborted. The nvlist must not be in error state.

The nvlist_free_null, nvlist_free_bool, nvlist_free_number, nvlist_free_string, nvlist_free_nvlist, nvlist_free_descriptor, nvlist_free_binary functions remove element of the given name and the given type determined by the function name from the nvlist and free all resources associated with it. If element of the given name and the given type does not exist, the program will be aborted. The nvlist must not be in error state.

EXAMPLES

The following example demonstrates how to prepare an nvlist and send it over unix(4) domain socket.
nvlist_t *nvl;
int fd;

fd = open("/tmp/foo", O_RDONLY); if (fd < 0) err(1, "open(\"/tmp/foo\") failed");

nvl = nvlist_create(0); /* * There is no need to check if nvlist_create() succeeded, * as the nvlist_add_<type>() functions can cope. * If it failed, nvlist_send() will fail. */ nvlist_add_string(nvl, "filename", "/tmp/foo"); nvlist_add_number(nvl, "flags", O_RDONLY); /* * We just want to send the descriptor, so we can give it * for the nvlist to consume (that’s why we use nvlist_move * not nvlist_add). */ nvlist_move_descriptor(nvl, "fd", fd); if (nvlist_send(sock, nvl) < 0) {         nvlist_destroy(nvl);         err(1, "nvlist_send() failed"); } nvlist_destroy(nvl);

Receiving nvlist and getting data:

nvlist_t *nvl;
const char *command;
char *filename;
int fd;

nvl = nvlist_recv(sock); if (nvl == NULL)         err(1, "nvlist_recv() failed");

/* For command we take pointer to nvlist’s buffer. */ command = nvlist_get_string(nvl, "command"); /* * For filename we remove it from the nvlist and take * ownership of the buffer. */ filename = nvlist_take_string(nvl, "filename"); /* The same for the descriptor. */ fd = nvlist_take_descriptor(nvl, "fd");

printf("command=%s filename=%s fd=%d0, command, filename, fd);

nvlist_destroy(nvl); free(filename); close(fd); /* command was freed by nvlist_destroy() */

Iterating over nvlist:

nvlist_t *nvl;
const char *name;
void *cookie;
int type;

nvl = nvlist_recv(sock); if (nvl == NULL)         err(1, "nvlist_recv() failed");

cookie = NULL; while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {         printf("%s=", name);         switch (type) {         case NV_TYPE_NUMBER:                 printf("%ju", (uintmax_t)nvlist_get_number(nvl, name));                 break;         case NV_TYPE_STRING:                 printf("%s", nvlist_get_string(nvl, name));                 break;         default:                 printf("N/A");                 break;         }         printf("\n"); }

Iterating over every nested nvlist:

nvlist_t *nvl;
const char *name;
void *cookie;
int type;

nvl = nvlist_recv(sock); if (nvl == NULL)         err(1, "nvlist_recv() failed");

cookie = NULL; do {         while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {                 if (type == NV_TYPE_NVLIST) {                         nvl = nvlist_get_nvlist(nvl, name);                         cookie = NULL;                 }         } } while ((nvl = nvlist_get_parent(nvl, &cookie)) != NULL);

SEE ALSO

close(2), dup(2), open(2), err(3), free(3), printf(3), unix(4)

HISTORY

The libnv library appeared in
.Fx 11.0 .

AUTHORS


.An -nosplit The libnv library was implemented by
.An Pawel Jakub Dawidek Aq pawel@dawidek.net under sponsorship from the FreeBSD Foundation.
Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.