Go to main content

man pages section 3: Extended Library Functions, Volume 2

Exit Print View

Updated: Thursday, June 13, 2019

kstat2_mapiter_start (3KSTAT2)


kstat2_mapiter_start, kstat2_mapiter_hasnext, kstat2_mapiter_next, kstat2_mapiter_remove, kstat2_mapiter_end - iterate over kstat2 map entries


cc [ flag... ] file... -lkstat2 [ library...]
     #include <kstat2.h>
kstat2_status_t kstat2_mapiter_start(kstat2_map_t map,
         kstat2_nv_type_t type, kstat2_mapiter_t *iter);
kstat2_status_t kstat2_mapiter_hasnext(kstat2_mapiter_t iter,
         boolean_t *has_next);
kstat2_status_t kstat2_mapiter_next(kstat2_mapiter_t iter,
         kstat2_nv_t *nv);
kstat2_status_t kstat2_mapiter_remove(kstat2_mapiter_t iter);
kstat2_status_t kstat2_mapiter_end(kstat2_mapiter_t *iter);


The kstat2_mapiter_start() function creates a new iterator that can be used to traverse the specified map. The type parameter specifies the type of map keys to be visited and is an ORed combination of KSTAT2_NVK_SYS for kernel kstat values, KSTAT2_NVK_USR for user-added values, KSTAT2_NVK_MAP for sub-maps, or KSTAT2_NVK_ALL to visit all types of values. The order in which values are visited is undefined, but provided no changes are made to the map, both successive and concurrent iterations over the map will return the values in the same order.

kstat2_mapiter_hasnext() sets has_next to true, if the map has unvisited values and to false if all values have been visited.

kstat2_mapiter_next() obtains the next unvisited value from the map.

kstat2_mapiter_remove() removes the current value from the map.

kstat2_mapiter_end() deallocates the iterator when the application has finished iterating over the map.

Return Values

Upon successful completion the iterator functions will return KSTAT2_S_OK, otherwise an error will be returned. A map may have multiple concurrent iterators but if the map is modified either directly (for example, by a call to a kstat2_map_put_*() function or kstat2_map_remove()) or through another iterator (for example, through the kstat2_mapiter_remove()), subsequent iterator calls will fail and any open iterators must be disposed of by a call to kstat2_mapiter_end().


The kstat2_mapiter_start(), kstat2_mapiter_hasnext(), kstat2_mapiter_next(), kstat2_mapiter_remove(), and kstat2_mapiter_end() functions will fail if:


The handle or ir iterator parameter was invalid


Memory could not be allocated for the data


If the kstat has been deleted by the kernel


If no memory could be allocated


If an underlying system call failed, see errno

The kstat2_mapiter_next(), kstat2_mapiter_remove(), and kstat2_mapiter_end() functions will fail if:


The iterator has reached the end of the map or the item has already been removed

The kstat2_mapiter_hasnext(), kstat2_mapiter_next(), kstat2_mapiter_remove(), and kstat2_mapiter_end() functions will fail if:


The map has been modified elsewhere

The kstat2_mapiter_remove() function will fail if:


An attempt to remove a system value has been made



kernel statistics driver




See the kstat2(3KSTAT2) manpage.


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

Interface Stability
MT-Safe with exceptions

See Also

kstat2(3KSTAT2), kstat2_close(3KSTAT2), kstat2_close(3KSTAT2), kstat2_map_get(3KSTAT2), kstat2_map_get_userdata(3KSTAT2), kstat2_map_meta(3KSTAT2), kstat2_map_parent(3KSTAT2), kstat2_map_put_integer(3KSTAT2), kstat2_map_put_integers(3KSTAT2), kstat2_map_put_string(3KSTAT2), kstat2_map_put_strings(3KSTAT2), kstat2_map_remove(3KSTAT2), kstat2_map_set_data_cb(3KSTAT2), kstat2_map_set_destroy_cb(3KSTAT2), kstat2_map_set_tree_cb(3KSTAT2), kstat2_map_set_userdata(3KSTAT2), kstat2_map_size(3KSTAT2), kstat2_map_to_array(3KSTAT2), kstat2_map_uri(3KSTAT2), kstat2_mapiter_end(3KSTAT2), kstat2_mapiter_hasnext(3KSTAT2), kstat2_mapiter_next(3KSTAT2), kstat2_mapiter_remove(3KSTAT2), kstat2_mapref_alloc(3KSTAT2), kstat2_mapref_deref(3KSTAT2), kstat2_mapref_free(3KSTAT2), kstat2_nv_meta(3KSTAT2), kstat2_open(3KSTAT2), kstat2_status_string(3KSTAT2), kstat2_update(3KSTAT2), kstat2_uri_decode(3KSTAT2), kstat2_uri_encode(3KSTAT2), libkstat2(3LIB)


The kstat2 functions are MT-Safe with the exception that only one thread may actively use a kstat2_handle_t, or any object obtained through it, at any one time. Synchronization is required if multiple threads intend to share a kstat2_handle_t or any object obtained through it. Synchronization is left to the application.