kstat2_open, kstat2_close, kstat2_update, kstat2_status_string, kstat2_alloc_matcher_list, kstat2_free_matcher_list, kstat2_add_matcher - initialize and access the kernel statistics facility, version 2
cc [ flag... ] file... -lkstat2 [ library...]
#include <kstat2.h>
kstat2_status_t kstat2_alloc_matcher_list(
kstat2_matcher_list_t *matchers);
kstat2_status_t kstat2_free_matcher_list(
kstat2_matcher_list_t *matchers);
kstat2_status_t kstat2_add_matcher(kstat2_match_type_t type,
const char *match, kstat2_matcher_list_t matchers);
kstat2_status_t kstat2_open(kstat2_handle_t *handle,
kstat2_matcher_list_t matchers);
kstat2_status_t kstat2_update(kstat2_handle_t handle);
const char* kstat2_status_string(kstat2_status_t status);
The kstat2_alloc_matcher_list() function allocates a new matcher list to allow matchers to be provided to the kstat2_open() function.
The kstat2_free_matcher_list() function frees the resources associated with the matcher list.
The kstat2_add_matcher() function adds matchers to the provided matcher list. Each call appends the new matcher to the provided matcher list. Matches are on kstat URI, with the following match types supported:
Performs a direct strcmp with the kstat URI. For more information, see the strcmp(3C) man page
Performs a glob pattern match using gmatch. For more information, see the gmatch(3GEN) man page
Performs a Perl Compatible Regular Expression(PCRE) match using pcre_exec.
The kstat2_open() function initializes an opaque kstat2 handle that provides access to a specific view of the kernel statistics. Only kstats that match one or more of the provided matchers will be available. If a NULL or empty matcher list is provided, all of the system's kstats will be available, which is equivalent to calling the kstat2_open() function. Restricting the number of kstats available will improve performance and reduce the memory footprint.
The kstat2_close() function frees all resources that are associated with the handle. It is the caller's responsibility to free any allocated matcher list by calling the kstat2_free_matcher_list() function.
The kstat2_update() function synchronises the user's view with that of the kernel. The kernel may at any point add or remove kstats, causing the user's view of the available kstats to become out of date. The kstat2_update() function should be called periodically to resynchronise the two views.
The kstat2_status_string() function will give a descriptive error message for the supplied status value. The status value will be one of:
Request was successful
Insufficient permissions for request
Insufficient memory available
Insufficient memory available
Invalid argument supplied
Invalid state for this request
Invalid data type found
Resource not found
Concurrent modification of map detected
Referenced map has been deleted
System call has failed, see errno
Upon successful completion, the kstat2_alloc_matcher_list(), kstat2_add_matcher(), kstat2_free_matcher_list(), kstat2_open(), kstat2_close(), and kstat2_update() functions return a kstat2_status_t value of KSTAT2_S_OK. If an error occurs a value other than KSTAT2_S_OK is returned. For more information, see the ERRORS section.
The kstat2_status_string() function will return a descriptive string for the supplied status code.
The kstat2_alloc_matcher_list() function will fail if:
The matchers parameter was invalid
No memory could be allocated
The kstat2_add_matcher() function will fail if:
The type, match or matchers parameter was invalid
No memory could be allocated
The kstat2_open() function will fail if:
The handle parameter was invalid
No memory could be allocated
An underlying syscall failed, see errno
The kstat2_open() function will return KSTAT2_S_SYS_FAIL, if any of the errors detected by open are encountered. For more information, see the open(2) man page.
The kstat2_close() function will fail if:
The handle parameter was invalid
An underlying syscall failed, see errno
The kstat2_close() function will return KSTAT2_S_SYS_FAIL, if any of the errors detected by open are encountered. For more information, see the open(2) man page
The kstat2_update() function will fail if:
The handle parameter was invalid
No memory could be allocated
An underlying syscall failed, see errno
Kernel statistics driver
Header
See the kstat2(3KSTAT2) man page.
See attributes(7) for descriptions of the following attributes:
|
kstat2(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_alloc(3KSTAT2), kstat2_mapref_deref(3KSTAT2), kstat2_mapref_free(3KSTAT2), kstat2_nv_meta(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.