Go to main content

man pages section 3: Extended Library Functions, Volume 2

Exit Print View

Updated: Thursday, June 13, 2019
 
 

kstat2_status_string (3KSTAT2)

Name

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

Synopsis

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

Description

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:

KSTAT2_M_STRING

Performs a direct strcmp with the kstat URI. For more information, see the strcmp(3C) man page

KSTAT2_M_GLOB

Performs a glob pattern match using gmatch. For more information, see the gmatch(3GEN) man page

KSTAT2_M_RE

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:

KSTAT2_S_OK

Request was successful

KSTAT2_S_NO_PERM

Insufficient permissions for request

KSTAT2_S_NO_MEM

Insufficient memory available

KSTAT2_S_NO_SPACE

Insufficient memory available

KSTAT2_S_INVAL_ARG

Invalid argument supplied

KSTAT2_S_INVAL_STATE

Invalid state for this request

KSTAT2_S_INVAL_TYPE

Invalid data type found

KSTAT2_S_NOT_FOUND

Resource not found

KSTAT2_S_CONC_MOD

Concurrent modification of map detected

KSTAT2_S_DEL_MAP

Referenced map has been deleted

KSTAT2_S_SYS_FAIL

System call has failed, see errno

Return Values

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.

Errors

The kstat2_alloc_matcher_list() function will fail if:

KSTAT2_S_INVAL_ARG

The matchers parameter was invalid

KSTAT2_S_NO_MEM

No memory could be allocated

The kstat2_add_matcher() function will fail if:

KSTAT2_S_INVAL_ARG

The type, match or matchers parameter was invalid

KSTAT2_S_NO_MEM

No memory could be allocated

The kstat2_open() function will fail if:

KSTAT2_S_INVAL_ARG

The handle parameter was invalid

KSTAT2_S_NO_MEM

No memory could be allocated

KSTAT2_S_SYS_FAIL

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:

KSTAT2_S_INVAL_ARG

The handle parameter was invalid

KSTAT2_S_SYS_FAIL

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:

KSTAT2_S_INVAL_ARG

The handle parameter was invalid

KSTAT2_S_NO_MEM

No memory could be allocated

KSTAT2_S_SYS_FAIL

An underlying syscall failed, see errno

Files

/dev/kstat

Kernel statistics driver

/usr/include/kstat2.h

Header

Examples

See the kstat2(3KSTAT2) man page.

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

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.