Go to main content

man pages section 3: Extended Library Functions, Volume 2

Exit Print View

Updated: Thursday, June 13, 2019
 
 

kstat2_mapiter_remove (3KSTAT2)

Name

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

Synopsis

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

Description

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().

Errors

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

KSTAT2_S_INVAL_ARG

The handle or ir iterator parameter was invalid

KSTAT2_S_NO_MEM

Memory could not be allocated for the data

KSTAT2_S_DEL_MAP

If the kstat has been deleted by the kernel

KSTAT2_S_NO_MEM

If no memory could be allocated

KSTAT2_S_SYS_FAIL

If an underlying system call failed, see errno

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

KSTAT2_S_INVAL_STATE

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:

KSTAT2_S_CONC_MOD

The map has been modified elsewhere

The kstat2_mapiter_remove() function will fail if:

KSTAT2_S_NO_PERM

An attempt to remove a system value has been made

Files

/dev/kstat

kernel statistics driver

/usr/include/kstat2.h

header

Examples

See the kstat2(3KSTAT2) manpage.

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
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)

Notes

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.