Go to main content

man pages section 3: Extended Library Functions, Volume 2

Exit Print View

Updated: Thursday, June 13, 2019
 
 

kstat2_map_put_integers (3KSTAT2)

Name

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

Synopsis

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

Description

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:

KSTAT2_MAPF_NONE

No map flags are set

KSTAT2_MAPF_DORM

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.

Return Values

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.

Errors

The above functions will fail if:

KSTAT2_S_INVAL_ARG

The supplied handle is invalid

KSTAT2_S_NO_MEM

Memory could not be allocated for the data

KSTAT2_S_SYS_FAIL

An underlying syscall failed, see errno

In addition, kstat2_map_size() function will fail if:

KSTAT2_S_INVAL_TYPE

The type parameter is invalid

The kstat2_map_get() function will fail if:

KSTAT2_S_NOT_FOUND

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:

KSTAT2_S_NO_PERM

The requested key is already in use by the kstats framework

KSTAT2_S_NO_SPACE

There is no space left in the map for the new item

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

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.