Go to main content

man pages section 3: Extended Library Functions, Volume 2

Exit Print View

Updated: Thursday, June 13, 2019

kstat2_mapref_free (3KSTAT2)


kstat2_mapref_alloc, kstat2_mapref_deref, kstat2_mapref_free - update-safe references to kstat2 maps


cc [ flag... ] file... -lkstat2 [ library...]
     #include <kstat2.h>
kstat2_status_t kstat2_mapref_alloc(kstat2_map_t map,
         kstat2_mapref_t *ref);
kstat2_status_t kstat2_mapref_deref(kstat2_mapref_t ref,
         kstat2_map_t *map);
kstat2_status_t kstat2_mapref_free(kstat2_mapref_t *ref);


Traversing the kstat2 hierarchy to obtain a required kstat is a relatively expensive operation, so a facility to retain a reference to a map once it has been located is provided. However, when the application's kstat view is resynchronised to that of the kernel through a call to kstat2_update(), kstats that were previously present may have been deleted as a result of system configuration changes, rendering any retained kstat map references invalid. The kstat_mapref_*() functions allow safe retention of map references by allowing the application to determine if the underlying kstat has been deleted before accessing the retained reference.

The kstat2_mapref_alloc() function obtains a new reference to a kstat map.

The kstat2_mapref_deref() function dereferences the reference. If the reference is still valid, KSTAT2_S_OK will be returned and map will be set to the kstat map. If the underlying kstat has been deleted and the reference is now invalid, an error of KSTAT2_S_DEL_MAP will be returned and map will be set to NULL.

The kstat2_mapref_free() function frees a reference to a map and must be called when the application has finished with the reference, irrespective of the status of the underlying map.

Return Values

On successful completion the kstat2_mapref_alloc(), kstat2_mapref_deref(), and kstat2_mapref_free() calls will return an status of KSTAT2_S_OK. On failure an error code will be returned.


The kstat2_mapref_alloc() function will fail if:


The map or ref parameters are invalid


If memory for the reference could not be allocated

The kstat_mapref_deref() function will fail if:


If the map has been deleted


The map or ref parameters are invalid

The kstat2_mapref_free() function will fail if:


If the map reference is invalid



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