Go to main content

man pages section 3: Extended Library Functions, Volume 2

Exit Print View

Updated: Thursday, June 13, 2019
 
 

kstat2_map_set_tree_cb (3KSTAT2)

Name

kstat2_map_set_tree_cb, kstat2_map_set_data_cb, kstat2_map_set_destroy_cb - kstat2 tree mutation callbacks

Synopsis

cc [ flag... ] file... -lkstat2 [ library...]
     #include <kstat2.h>
kstat2_status_t kstat2_map_set_tree_cb(kstat2_map_t map,
         kstat2_tree_cb_t callback);
kstat2_status_t kstat2_map_set_data_cb(kstat2_map_t map,
         kstat2_data_cb_t callback);
kstat2_status_t kstat2_map_set_destroy_cb(kstat2_map_t map,
         kstat2_map_cb_t callback);

Description

kstat2_map_set_tree_cb() establishes a callback function that will be called whenever a kstat2 map is added or removed to the tree below the specified map. The callback must conform to the following typedef:

typedef void (*kstat2_tree_cb_t)(kstat2_map_t map,
         kstat2_map_t sub_map, kstat2_tree_cb_event_t event);

The callback will be passed the map it was registered against and the sub-map that has just been created or is about to be destroyed. To remove the callback, a callback parameter of NULL can be passed to kstat2_map_set_tree_cb(). The third parameter identifies the operation as an addition or a deletion event:

typedef enum kstat2_tree_cb_event {
         KSTAT2_TREE_ADD = 0,
         KSTAT2_TREE_REM = 1
     } kstat2_tree_cb_event_t;

This callback may only access the user data and sub-map items in any map, see the descriptions of KSTAT2_NVK_SYS, KSTAT2_NVK_USR, and KSTAT2_NVK_MAP in kstat2(3KSTAT2) for details.

kstat2_map_set_data_cb() establishes a callback function that will be called whenever kernel kstat data is added to or removed from the current map and any map in the tree below it. The callback must conform to the following typedef:

typedef void (*kstat2_data_cb_t)(kstat2_map_t map,
         kstat2_map_t sub_map, kstat2_data_cb_event_t event);

The callback will be passed the map it was registered against and the sub-map to which kstat data is being added or removed. To remove the callback, a callback parameter of NULL can be passed to kstat2_map_set_data_cb().

typedef enum kstat2_data_cb_event {
         KSTAT2_DATA_ADD = 0,
         KSTAT2_DATA_REM = 1
     } kstat2_data_cb_event_t;

If the event parameter is KSTAT2_DATA_ADD, this callback may access all data items in any map. If the event parameter is KSTAT2_DATA_REM it can only access user data and sub-map items in any map. See the descriptions of KSTAT2_NVK_SYS, KSTAT2_NVK_USR, and KSTAT2_NVK_MAP in kstat2(3KSTAT2) for details.

kstat2_map_set_destroy_cb() establishes a callback that will be called immediately prior to the deletion of a kstat map. The callback must conform to the following typedef:

typedef void (*kstat2_map_cb_t)(kstat2_map_t map, void *user_data);

The callback will be passed the map it was registered against and any user data that has been associated with the map (see kstat2_map_set_userdata(3KSTAT2)), or NULL if there is no such data. To remove the callback, a callback parameter of NULL can be passed. This callback may be used to reclaim any resources associated with a map, for example, logging filehandles or external structure references.

This callback may only access the user data and sub-map items in any map, see the descriptions of KSTAT2_NVK_SYS, KSTAT2_NVK_USR, and KSTAT2_NVK_MAP in kstat2(3KSTAT2) for details.

The ordering of callbacks over the lifecycle of a map will be:

KSTAT2_TREE_ADD

tree callback

KSTAT2_DATA_ADD

data callback

KSTAT2_DATA_REM

data callback and destroy callback

Notes

All callbacks are made synchronously during kstat2_update() and callbacks that take a significant time to execute will stall the execution of kstat2_update(). Long running processing should therefore be deferred and performed outside of the callback functions.

Return Values

On successful completion, the kstat2_map_set_tree_cb(), kstat2_map_set_data_cb(), and kstat2_map_set_destroy_cb() will return KSTAT2_S_OK.

Errors

The kstat2_map_set_tree_cb(), kstat2_map_set_data_cb(), and kstat2_map_set_destroy_cb() functions will fail if:

KSTAT2_S_INVAL_ARG

the map parameter is NULL

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

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.