com.sun.jna.platform.unix.solaris.Kstat2 Maven / Gradle / Ivy
Show all versions of jna-platform Show documentation
/* Copyright (c) 2022 Daniel Widdis, All Rights Reserved
*
* The contents of this file is dual-licensed under 2
* alternative Open Source/Free licenses: LGPL 2.1 or later and
* Apache License 2.0. (starting with JNA version 4.0.0).
*
* You can freely decide which license you want to apply to
* the project.
*
* You may obtain a copy of the LGPL License at:
*
* http://www.gnu.org/licenses/licenses.html
*
* A copy is also included in the downloadable source code package
* containing JNA, in file "LGPL2.1".
*
* You may obtain a copy of the Apache License at:
*
* http://www.apache.org/licenses/
*
* A copy is also included in the downloadable source code package
* containing JNA, in file "AL2.0".
*/
package com.sun.jna.platform.unix.solaris;
import com.sun.jna.Library;
import com.sun.jna.Native;
import com.sun.jna.Pointer;
import com.sun.jna.PointerType;
import com.sun.jna.Structure;
import com.sun.jna.Structure.FieldOrder;
import com.sun.jna.Union;
import com.sun.jna.platform.unix.solaris.Kstat2.Kstat2NV.UNION.IntegersArr;
import com.sun.jna.platform.unix.solaris.Kstat2.Kstat2NV.UNION.StringsArr;
import com.sun.jna.ptr.PointerByReference;
/**
* Kstat2 library. The kstat2 facility is a general-purpose mechanism for
* providing kernel statistics to users.
*
* Kstat2 is available in Solaris 11.4 and later.
*/
public interface Kstat2 extends Library {
/**
* Requires Solaris 11.4. Users should test for UnsatisfiedLinkError
*/
Kstat2 INSTANCE = Native.load("kstat2", Kstat2.class);
// enum kstat2_status -- return values and error codes
int KSTAT2_S_OK = 0; // Request was successful
int KSTAT2_S_NO_PERM = 1; // Insufficient permissions for request
int KSTAT2_S_NO_MEM = 2; // Insufficient memory available
int KSTAT2_S_NO_SPACE = 3; // No space available for operation
int KSTAT2_S_INVAL_ARG = 4; // Invalid argument supplied
int KSTAT2_S_INVAL_STATE = 5; // Invalid state for this request
int KSTAT2_S_INVAL_TYPE = 6; // Invalid data type found
int KSTAT2_S_NOT_FOUND = 7; // Resource not found
int KSTAT2_S_CONC_MOD = 8; // Concurrent modification of map detected
int KSTAT2_S_DEL_MAP = 9; // Referenced map has been deleted
int KSTAT2_S_SYS_FAIL = 10; // System call has failed, see errno
// enum kstat2_match_type
int KSTAT2_M_STRING = 0; // String
int KSTAT2_M_GLOB = 1; // Glob with ?, *, or [...]
int KSTAT2_M_RE = 2; // PCRE Regex
/*
* Values in Kstat2NV structure
*/
// enum kstat2_nv_type
byte KSTAT2_NVVT_MAP = 0; // Nested Name/Value map
byte KSTAT2_NVVT_INT = 1; // 64-bit unsigned integer
byte KSTAT2_NVVT_INTS = 2; // Array of 64-bit unsigned integers
byte KSTAT2_NVVT_STR = 3; // Null-terminated C string
byte KSTAT2_NVVT_STRS = 4; // Array of null-terminated C strings
// enum kstat2_nv_kind
byte KSTAT2_NVK_SYS = 0x01; // System kstat value type
byte KSTAT2_NVK_USR = 0x02; // User-supplied value type
byte KSTAT2_NVK_MAP = 0x04; // Sub-map value type
byte KSTAT2_NVK_ALL = 0x07; // All value types (only for iteration)
// enum kstat2_nv_flag
short KSTAT2_NVF_NONE = 0x00; // No flags present
short KSTAT2_NVF_INVAL = 0x01; // Value is invalid
/**
* Opaque kstat handle.
*/
class Kstat2Handle extends PointerType {
private PointerByReference ref = new PointerByReference();
/**
* Instantiates and opens a new Kstat2Handle with no filtering. All of the
* system's kstats will be available. Convenience method for
* {@link Kstat2#kstat2_open(PointerByReference, Kstat2MatcherList)} with a null
* matcher list.
*/
public Kstat2Handle() {
this(null);
}
/**
* Instantiates and opens a new Kstat2Handle filtered with the provided matcher.
* Convenience method for
* {@link Kstat2#kstat2_open(PointerByReference, Kstat2MatcherList)}.
*
* @param matchers
* 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. Restricting the number of
* kstats available will improve performance and reduce the memory
* footprint.
*/
public Kstat2Handle(Kstat2MatcherList matchers) {
super();
int ks = INSTANCE.kstat2_open(ref, matchers);
if (ks != KSTAT2_S_OK) {
throw new Kstat2StatusException(ks);
}
this.setPointer(ref.getValue());
}
/**
* Convenience method for {@link Kstat2#kstat2_update(Kstat2Handle)} that
* 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.
*
* @return Upon successful completion, returns a int value of
* {@link Kstat2#KSTAT2_S_OK}. If an error occurs a value other than
* KSTAT2_S_OK is returned.
*/
public int update() {
return INSTANCE.kstat2_update(this);
}
/**
* Convenience method for
* {@link Kstat2#kstat2_lookup_map(Kstat2Handle, String, PointerByReference)}
* that obtains a reference to a kstat2 map given the URI of the map.
*
* @param uri
* The URI of the map to return.
* @return A reference to the map.
*/
public Kstat2Map lookupMap(String uri) {
PointerByReference pMap = new PointerByReference();
int ks = INSTANCE.kstat2_lookup_map(this, uri, pMap);
if (ks != KSTAT2_S_OK) {
throw new Kstat2StatusException(ks);
}
return new Kstat2Map(pMap.getValue());
}
/**
* Convenience method for {@link Kstat2#kstat2_close(PointerByReference)}. After
* use, the kstat handle should be closed to reclaim the handles and memory that
* it allocated on open.
*
* @return Upon successful completion, returns a int value of
* {@link Kstat2#KSTAT2_S_OK}. If an error occurs a value other than
* KSTAT2_S_OK is returned.
*/
public int close() {
return INSTANCE.kstat2_close(ref);
}
}
/**
* Opaque kstat match list.
*/
class Kstat2MatcherList extends PointerType {
private PointerByReference ref = new PointerByReference();
/**
* Instantiates a new Kstat2MatcherList, allocating the necessary resources.
* Convenience method for
* {@link Kstat2#kstat2_alloc_matcher_list(PointerByReference)}.
*
* It is the caller's responsibility to free this matcher list by calling
* {@link #free()}.
*/
public Kstat2MatcherList() {
super();
int ks = INSTANCE.kstat2_alloc_matcher_list(ref);
if (ks != KSTAT2_S_OK) {
throw new Kstat2StatusException(ks);
}
this.setPointer(ref.getValue());
}
/**
* Convenience method for
* {@link Kstat2#kstat2_add_matcher(int, String, Kstat2MatcherList)} that 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: {@link Kstat2#KSTAT2_M_STRING} which performs a direct
* {@code strcmp} with the kstat URI, {@link Kstat2#KSTAT2_M_GLOB} which
* performs a glob pattern match using {@code gmatch}, and
* {@link Kstat2#KSTAT2_M_RE} which performs a Perl Compatible Regular
* Expression (PCRE) match using {@code pcre_exec}.
*
* @param type
* The type of matcher, from the {@code kstat2_match_type_t}
* enumeration.
* @param match
* The string to match.
* @return Upon successful completion, returns a int value of
* {@link Kstat2#KSTAT2_S_OK}. If an error occurs a value other than
* KSTAT2_S_OK is returned.
*/
public int addMatcher(int type, String match) {
return INSTANCE.kstat2_add_matcher(type, match, this);
}
/**
* Convenience method for
* {@link Kstat2#kstat2_free_matcher_list(PointerByReference)} that frees the
* resources associated with the matcher list.
*
* @return Upon successful completion, returns a int value of
* {@link Kstat2#KSTAT2_S_OK}. If an error occurs a value other than
* KSTAT2_S_OK is returned.
*/
public int free() {
return INSTANCE.kstat2_free_matcher_list(ref);
}
}
/**
* Opaque kstat map handle.
*/
class Kstat2Map extends PointerType {
public Kstat2Map() {
super();
}
public Kstat2Map(Pointer p) {
super(p);
}
/**
* Convenience method for
* {@link Kstat2#kstat2_map_get(Kstat2Map, String, PointerByReference)} that
* retrieves the name/value (nv) pair identified by the supplied name.
*
* @param name
* The uri of the data to retrieve.
* @return The name/value data.
*/
public Kstat2NV mapGet(String name) {
PointerByReference pbr = new PointerByReference();
int ks = INSTANCE.kstat2_map_get(this, name, pbr);
if (ks != KSTAT2_S_OK) {
throw new Kstat2StatusException(ks);
}
return new Kstat2NV(pbr.getValue());
}
/**
* Convenience method for
* {@link Kstat2#kstat2_map_get(Kstat2Map, String, PointerByReference)} that
* retrieves the name/value (nv) pair identified by the supplied name and
* returns the value as an object.
*
* @param name
* The name of the data to retrieve.
* @return If the value is of type {@link Kstat2#KSTAT2_NVVT_MAP}, a
* {@link Kstat2Map} is returned.
*
* If the value is of type {@link Kstat2#KSTAT2_NVVT_INT}, a
* {@link long} is returned.
*
* If the value is of type {@link Kstat2#KSTAT2_NVVT_INTS}, an array of
* {@link long} is returned.
*
* If the value is of type {@link Kstat2#KSTAT2_NVVT_STR}, a
* {@link String} is returned.
*
* If the value is of type {@link Kstat2#KSTAT2_NVVT_STRS}, an array of
* {@link String} is returned.
*
* If no value exists for this property (error or invalid data
* {@link Kstat2#KSTAT2_NVF_INVAL}), returns {@code null}.
*/
public Object getValue(String name) {
try {
Kstat2NV nv = mapGet(name);
if (nv.flags == KSTAT2_NVF_INVAL) {
return null;
}
switch (nv.type) {
case KSTAT2_NVVT_MAP:
return nv.data.map;
case KSTAT2_NVVT_INT:
return nv.data.integerVal;
case KSTAT2_NVVT_INTS:
return nv.data.integers.addr.getLongArray(0, nv.data.integers.len);
case KSTAT2_NVVT_STR:
return nv.data.strings.addr.getString(0);
case KSTAT2_NVVT_STRS:
return nv.data.strings.addr.getStringArray(0, nv.data.strings.len);
default:
return null;
}
} catch (Kstat2StatusException e) {
return null;
}
}
}
/**
* Immutable Name/Value pair.
*/
@FieldOrder({ "name", "type", "kind", "flags", "data" })
class Kstat2NV extends Structure {
public String name; // Name of the pair
public byte type; // Value type of the pair
public byte kind; // Kind of the pair
public short flags; // Flags of the pair
public UNION data; // Data value
public static class UNION extends Union {
public Kstat2Map map;
public long integerVal;
public IntegersArr integers;
public StringsArr strings;
@FieldOrder({ "addr", "len" })
public static class IntegersArr extends Structure {
public Pointer addr;
public int len; // length of array
}
@FieldOrder({ "addr", "len" })
public static class StringsArr extends Structure {
public Pointer addr;
public int len; // length of array
}
}
public Kstat2NV() {
super();
}
public Kstat2NV(Pointer p) {
super(p);
read();
}
@Override
public void read() {
super.read();
switch (type) {
case KSTAT2_NVVT_MAP:
data.setType(Kstat2Map.class);
break;
case KSTAT2_NVVT_INT:
data.setType(long.class);
break;
case KSTAT2_NVVT_INTS:
data.setType(IntegersArr.class);
break;
case KSTAT2_NVVT_STR:
case KSTAT2_NVVT_STRS:
data.setType(StringsArr.class);
break;
default:
break;
}
data.read();
}
}
/**
* Initializes an opaque kstat2 handle that provides access to a specific view
* of the kernel statistics.
*
* @param handle
* A pointer to the handle to be initialized.
* @param matchers
* 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.
* @return Upon successful completion, returns a int value of
* {@link Kstat2#KSTAT2_S_OK}. If an error occurs a value other than
* KSTAT2_S_OK is returned.
*/
int kstat2_open(PointerByReference /* Kstat2Handle */ handle, Kstat2MatcherList matchers);
/**
* 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.
*
* @param handle
* The handle to be updated.
* @return Upon successful completion, returns a int value of
* {@link Kstat2#KSTAT2_S_OK}. If an error occurs a value other than
* KSTAT2_S_OK is returned.
*/
int kstat2_update(Kstat2Handle handle);
/**
* 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.
*
* @param handle
* A reference to the handle to close.
* @return Upon successful completion, returns a int value of
* {@link Kstat2#KSTAT2_S_OK}. If an error occurs a value other than
* KSTAT2_S_OK is returned.
*/
int kstat2_close(PointerByReference /* Kstat2Handle */ handle);
/**
* Allocates a new matcher list to allow matchers to be provided to the
* {@link Kstat2#kstat2_open(PointerByReference, Kstat2MatcherList)} function.
*
* @param matchers
* Receives a pointer to the allocated matcher list.
* @return Upon successful completion, returns a int value of
* {@link Kstat2#KSTAT2_S_OK}. If an error occurs a value other than
* KSTAT2_S_OK is returned.
*/
int kstat2_alloc_matcher_list(PointerByReference /* Kstat2MatcherList */ matchers);
/**
* Frees the resources associated with the matcher list.
*
* @param matchers
* A pointer to the {@link Kstat2MatcherList} to be freed.
* @return Upon successful completion, returns a int value of
* {@link Kstat2#KSTAT2_S_OK}. If an error occurs a value other than
* KSTAT2_S_OK is returned.
*/
int kstat2_free_matcher_list(PointerByReference /* Kstat2MatcherList */ matchers);
/**
* 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: {@link Kstat2#KSTAT2_M_STRING} which performs a direct
* {@code strcmp} with the kstat URI, {@link Kstat2#KSTAT2_M_GLOB} which
* performs a glob pattern match using {@code gmatch}, and
* {@link Kstat2#KSTAT2_M_RE} which performs a Perl Compatible Regular
* Expression (PCRE) match using {@code pcre_exec}.
*
* @param type
* The type of matcher, from the {@code kstat2_match_type_t}
* enumeration.
* @param match
* The string to match.
* @param matchers
* The list to which to append the matcher.
* @return Upon successful completion, returns a int value of
* {@link Kstat2#KSTAT2_S_OK}. If an error occurs a value other than
* KSTAT2_S_OK is returned.
*/
int kstat2_add_matcher(int type, String match, Kstat2MatcherList matchers);
/**
* Obtains a reference to a kstat2 map given the URI of the map.
*
* @param handle
* The handle to obtain the map from.
* @param uri
* The string to match.
* @param map
* Receives a reference to the relevant map.
* @return Upon successful completion, the function will set the map parameter
* to reference the relevant map and {@link Kstat2#KSTAT2_S_OK} will be
* returned. If the requested item cannot be found, the map reference
* will be set to {@code NULL} and an error will be returned.
*/
int kstat2_lookup_map(Kstat2Handle handle, String uri, PointerByReference /* Kstat2Map */ map);
/**
* 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().
*
* @param map
* The map from which to retrieve the data.
* @param name
* The uri of the data to retrieve.
* @param nv
* Receives a reference to the name/value data.
* @return Upon successful completion, returns {@link Kstat2#KSTAT2_S_OK}. If
* there is an error performing the requested operation, an error code
* will be returned.
*/
int kstat2_map_get(Kstat2Map map, String name, PointerByReference /* Kstat2NV */ nv);
/**
* Gives a descriptive error message for the supplied status value.
*
* @param status
* A value in the {@code kstat2_status} enumeration.
* @return A descriptive string for the supplied status code.
*/
String kstat2_status_string(int status);
}