Manual Pages  — NV

The nvlist_clone() function clones nvl. 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() function dumps nvlist content for debugging purposes to the file descriptor fd.

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

The nvlist_size() function returns the size of the binary buffer that would be generated by 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 is stored there. This 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 the error state.

The nvlist_unpack() function converts a binary buffer to a new nvlist. The flags argument has the same meaning as the flags argument passed to nvlist_create(). If flags do not match the flags used to create the initial nvlist before it was packed, this function will fail. The flags of nested nvlists are not validated by this function. The caller is responsible for validating the flags on any nested nvlists using nvlist_flags(). This function returns the new nvlist on success or NULL in case of an error.

The nvlist_send() function sends nvl over the socket sock. Note that nvlists that contain file descriptors can only be sent over unix(4) domain sockets.

The nvlist_recv() function receives an nvlist over the socket sock. As with nvlist_unpack(), the flags argument is used to construct the new nvlist and must match the flags used to construct the original nvlist written to sock by the peer. The flags of nested nvlists are not validated by this function. The caller is responsible for validating the flags on any nested nvlists using nvlist_flags(). This function returns the new nvlist on success or NULL in case of an error.

The nvlist_xfer() function sends nvl over the socket sock argument and then receives a new nvlist over the same socket. The flags argument applies to the new nvlist similar to nvlist_recv(). The nvlist nvl is always destroyed. This function returns the new nvlist on success or NULL in case of an error.

The nvlist_next() function iterates over nvl returning the names and types of subsequent elements. The cookiep argument determines which element is returned. If *cookiep is NULL, the values for the first element in the list are returned. Otherwise, *cookiep should contain the result of a prior call to nvlist_next() in which case values for the next element from nvl are returned. This function returns NULL when there are no more elements on nvl. The typep argument can be NULL. Elements may not be removed from nvl the nvlist while traversing it. nvl must not be in the error state. Additional actions can be performed on an element identified by a cookie via the cnv(9) API .

The nvlist_exists() function returns true if an element named name exists in nvl (regardless of type) or false otherwise. The nvlist must not be in the error state.

The nvlist_exists_type() function returns true if an element named name of type type exists or false otherwise. The nvlist must not be in the error state.

The nvlist_exists_null(), nvlist_exists_bool(), nvlist_exists_number(), nvlist_exists_string(), nvlist_exists_nvlist(), nvlist_exists_descriptor(), nvlist_exists_binary(), nvlist_exists_bool_array(), nvlist_exists_number_array(), nvlist_exists_string_array(), nvlist_exists_nvlist_array(), nvlist_exists_descriptor_array() functions return true if element named name with the type determined by the function name exists or false otherwise. The nvlist must not be in the 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(), nvlist_add_bool_array(), nvlist_add_number_array(), nvlist_add_string_array(), nvlist_add_nvlist_array(), nvlist_add_descriptor_array() functions add an element to nvl. When adding a string or binary buffer, these functions allocate memory and copy the data. When adding an nvlist, the value nvlist is cloned and the clone is added to nvl. When adding a file descriptor, the descriptor is duplicated via the dup(2) system call and the new file descriptor is added. The array functions fail if there are any NULL elements in the array, or if the array pointer is NULL. If an error occurs while adding a new element, an 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(), nvlist_move_bool_array(), nvlist_move_number_array(), nvlist_move_string_array(), nvlist_move_nvlist_array(), nvlist_move_descriptor_array() functions add an element to nvl, but unlike the nvlist_add_<type>() functions they consume the given resource. For string, file descriptor, binary buffer, or nvlist values, no value should be moved into an nvlist multiple times; doing so will cause that value to be freed multiple times. Note that strings or binary buffers must be allocated with malloc(3), and the pointers will be released via free(3) when nvl is destroyed. The array functions fail if there are any NULL elements, or if the array pointer is NULL. If an error occurs while adding new element, the resource is destroyed and an 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(), nvlist_get_bool_array(), nvlist_get_number_array(), nvlist_get_string_array(), nvlist_get_nvlist_array(), nvlist_get_descriptor_array() functions return the value of the first element in nvl named name. For string, nvlist, file descriptor, binary buffer, or array values, the returned resource must not be modified - it still belongs to nvl.

If an element named name does not exist, the program aborts. To avoid this, the caller should check for the existence of the element before trying to obtain the value or use the dnv(9) extension which provides a default value in the case of a missing element.

The nvlist must not be in the error state.

The nvlist_get_parent() function returns the parent nvlist of nvl.

The nvlist_get_array_next() function returns the next element after nvl from an array of nvlists. If nvl is not in an array of nvlists or it is the last element, this function returns NULL. An nvlist is only in an nvlist array if it was added to an nvlist array using nvlist_add_nvlist_array(), nvlist_append_nvlist_array(), or nvlist_move_nvlist_array().

The nvlist_get_pararr() function returns the next element after nvl() from an array of nvlists. If nvl() is the last element in an array of nvlists, the parent nvlist of nvl, is returned. If nvl() is not in an array of nvlists, NULL is returned.

The nvlist_take_bool(), nvlist_take_number(), nvlist_take_string(), nvlist_take_nvlist(), nvlist_take_descriptor(), nvlist_take_binary(), nvlist_take_bool_array(), nvlist_take_number_array(), nvlist_take_string_array(), nvlist_take_nvlist_array(), nvlist_take_descriptor_array() functions return the value of the element named name and remove the element from nvl. For string and binary buffer values, the caller is responsible for freeing the returned value using the free(3) function. For nvlist values, the caller is responsible for destroying the returned nvlist using the nvlist_destroy() function. For file descriptor values, the caller is responsible for closing the returned descriptor using the close(2) system call. For array values, the caller is responsible for destroying every element of the array based on the element type. In addition, the caller must also free the pointer to the array using the free(3) function.

If an element named name does not exist, the program aborts. To avoid this, the caller should check for the existence of the element before trying to obtain the value or use the dnv(9) extension which provides a default value in the case of a missing element.

The nvlist must not be in the error state.

The nvlist_append_bool_array(), nvlist_append_number_array(), nvlist_append_string_array(), nvlist_append_nvlist_array(), nvlist_append_descriptor_array() functions append an element to an existing array using the same semantics as the add functions (that is, the element will be copied when applicable). If the array named name does not exist, then it will be created as if using the nvlist_add_<type>_array() function. If an error occurs while appending a new element, an internal error is set on nvl.

The nvlist_free() function removes the first element named name from nvl (regardless of type) and frees all resources associated with it. If no element named name exists, the program aborts. The nvlist must not be in the error state.

The nvlist_free_type() function removes the first element named name of type type from nvl and frees all resources associated with it. If no element named name of type type exists, the program aborts. The nvlist must not be in the error state.

The nvlist_free_null(), nvlist_free_bool(), nvlist_free_number(), nvlist_free_string(), nvlist_free_nvlist(), nvlist_free_descriptor(), nvlist_free_binary(), nvlist_free_bool_array(), nvlist_free_number_array(), nvlist_free_string_array(), nvlist_free_nvlist_array(), nvlist_free_descriptor_array() functions remove the first element named name with the type determined by the function name from nvl free all resources associated with it. If no element named name with the appropriate type exists, the program aborts. The nvlist must not be in the error state.

• File descriptor and file descriptor array value types are not supported.
• nvlist_recv(), nvlist_send(), and nvlist_xfer() are not supported.
• All memory allocations use the M_NVLIST memory type with malloc(9) and free(9). As a result, any allocated buffers moved into an nvlist must be allocated with M_NVLIST, and buffers returned by functions such as nvlist_pack() must be freed with M_NVLIST.

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 is 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 an nvlist and retrieving element values:

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

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

/* For command we accept a pointer to the nvlist's internal 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 file descriptor. */
fd = nvlist_take_descriptor(nvl, "fd");

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

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

Iterating over an nvlist:

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

nvl = nvlist_recv(sock, 0);
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(" );
}

Iterating over every nested nvlist:

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

nvl = nvlist_recv(sock, 0);
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);

Iterating over every nested nvlist and every nvlist element:

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

nvl = nvlist_recv(sock, 0);
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;
                } else if (type == NV_TYPE_NVLIST_ARRAY) {
                        nvl = nvlist_get_nvlist_array(nvl, name, NULL)[0];
                        cookie = NULL;
                }
        }
} while ((nvl = nvlist_get_pararr(nvl, &cookie)) != NULL);

Or alternatively:

nvlist_t *nvl, *tmp;
const nvlist_t * const *array;
const char *name;
void *cookie;
int type;

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

cooke = NULL;
tmp = nvl;
do {
        do {
                nvl = tmp;
                while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
                        if (type == NV_TYPE_NVLIST) {
                                nvl = nvlist_get_nvlist(nvl, name);
                                cookie = NULL;
                        } else if (type == NV_TYPE_NVLIST_ARRAY) {
                                nvl = nvlist_get_nvlist_array(nvl, name,
                                    NULL)[0];
                                cookie = NULL;
                        }
                }
                cookie = NULL;
        } while ((tmp = nvlist_get_array_next(nvl)) != NULL);
} while ((tmp = nvlist_get_parent(nvl, &cookie)) != NULL);