kstat2_map_get, kstat2_map_flags, kstat2_map_size, kstat2_map_put_integer, kstat2_map_put_integers, kstat2_map_put_string, kstat2_map_put_strings, kstat2_map_remove, kstat2_map_to_array, kstat2_map_parent - manipulate kstat2 data maps and handles
cc [ flag... ] file... -lkstat2 [ library...]
#include <kstat2.h>
kstat2_status_t kstat2_map_size(kstat2_map_t map,
kstat2_nv_kind_t kind, uint32_t *size);
kstat2_status_t kstat2_map_get(kstat2_map_t map, const char *name,
kstat2_nv_t *nv);
kstat2_status_t kstat2_map_flags(kstat2_map_t map, uint32_t *flags);
kstat2_status_t kstat2_map_put_integer(kstat2_map_t map,
const char *name, uint64_t value);
kstat2_status_t kstat2_map_put_integers(kstat2_map_t map,
const char *name, uint64_t values[], uint32_t length);
kstat2_status_t kstat2_map_put_string(kstat2_map_t map,
const char *name, const char *value);
kstat2_status_t kstat2_map_put_strings(kstat2_map_t map,
const char *name, const char *const values[], uint32_t length);
kstat2_status_t kstat2_map_remove(kstat2_map_t map, const char *name);
kstat2_status_t kstat2_map_to_array(kstat2_map_t map,
kstat2_nv_t *nv_array[], uint32_t *size, uint32_t *entries);
kstat2_status_t kstat2_map_parent(kstat2_map_t map,
kstat2_map_t *parent);
The kstat2_map_size() function returns the number of elements in the map. The kind parameter specifies the type of element to be counted, either system, user or all name/value elements.
The kstat2_map_get() function retrieves the name/value (nv) pair identified by the supplied name. The reference returned is managed by the library and must not be passed to free(). See kstat2(3KSTAT2) for a description of the returned structure.
The kstat2_map_flags() function retrieves any flags associated with the map. Possible flag values are:
No map flags are set
Kstat map is dormant. Kernel values remain unchanged when a kstat is in the dormant state.
The kstat2_map_put_integer() function adds or replaces an integer value in the map, with the specified name.
The kstat2_map_put_integers() function adds or replaces a list of integers in the map, with the specified name. length must be the length of the supplied array of integer values. The supplied values will be copied and the caller is responsible for managing the space occupied by the parameters.
The kstat2_map_put_string() function adds or replaces a string value in the map, with the specified name. The supplied value will be copied and the caller is responsible for managing the space occupied by it.
The kstat2_map_put_strings() function adds or replaces a list of strings in the map, with the specified name. length must be the length of the supplied array of string values. The supplied values will be copied and the caller is responsible for managing the space occupied by them.
kstat2_map_remove() removes the specified name/value pair from the map. Only items added by one of the above kstat2_map_put_*() functions may be removed.
kstat2_map_to_array() copies references to the name or value pairs from the map into the passed array. The array parameter should either be NULL or have been allocated with malloc(). size must contain current size of the array, entries will be set on return to the number of entries that have been copied into the array. If array is NULL, a new array will be allocated with malloc(). If the supplied array is too small, the existing memory will be freed and a new array allocated. When the array is no longer required, the caller is responsible for disposing of the array with the free() function. As this array directly references the name or value pairs stored in the map, any updates to the map, such as the removal of name or values or a call to the kstat2_update() function will invalidate this array, requiring it to be generated.
kstat2_map_parent() retrieves a reference to the parent map of the current map and returns it in parent. If the map is at the top of the hierarchy, parent will be NULL on return.
Upon successful completion, the above functions will return KSTAT2_S_OK. If there is an error performing the requested operation, an error code will be returned. Note that only name/value pairs that do not collide with an existing system provided name can be added to maps, if a name collision is detected no changes will be made and an error will be returned.
The above functions will fail if:
The supplied handle is invalid
Memory could not be allocated for the data
An underlying syscall failed, see errno
In addition, kstat2_map_size() function will fail if:
The type parameter is invalid
The kstat2_map_get() function will fail if:
The requested item could not be found
The kstat2_map_put_integer(), kstat2_map_put_integers(), kstat2_map_put_string(), and kstat2_map_put_strings() functions will fail if:
The requested key is already in use by the kstats framework
There is no space left in the map for the new item
kernel statistics driver
header
See the kstat2(3KSTAT2) manpage.
See attributes(7) for descriptions of the following attributes:
|
kstat2_close(3KSTAT2), kstat2_lookup_map(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_mapiter_start(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.