kstat_named_init(9F) Kernel Functions for Drivers kstat_named_init(9F)NAME
kstat_named_init, kstat_named_setstr - initialize a named kstat
SYNOPSIS
#include <sys/types.h>
#include <sys/kstat.h>
void kstat_named_init(kstat_named_t *knp, const char *name,
uchar_t data_type);
void kstat_named_setstr(kstat_named_t *knp, const char *str);
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI)
PARAMETERS
knp Pointer to a kstat_named(9S) structure.
name The name of the statistic.
data_type The type of value. This indicates which field of the kstat_named(9S) structure should be used. Valid values are:
KSTAT_DATA_CHAR The "char" field.
KSTAT_DATA_LONG The "long" field.
KSTAT_DATA_ULONG The "unsigned long" field.
KSTAT_DATA_LONGLONG Obsolete. Use KSTAT_DATA_INT64.
KSTAT_DATA_ULONGLONG Obsolete. Use KSTAT_DATA_UINT64.
KSTAT_DATA_STRING Arbitrary length "long string" field.
str Pointer to a NULL-terminated string.
DESCRIPTION
kstat_named_init() associates a name and a type with a kstat_named(9S) structure.
kstat_named_setstr() associates str with the named kstat knp. It is an error for knp to be of type other than KSTAT_DATA_STRING. The string
argument must remain valid even after the function that is calling kstat_named_setstr() is returned. This is the only supported method of
changing the value of long strings.
RETURN VALUES
None.
CONTEXT
kstat_named_init() and kstat_named_setstr() can be called from user or kernel context.
SEE ALSO kstat_create(9F), kstat_install(9F), kstat(9S), kstat_named(9S)
Writing Device Drivers
SunOS 5.11 29 Feb 2008 kstat_named_init(9F)
Check Out this Related Man Page
ks_snapshot(9E) Driver Entry Points ks_snapshot(9E)NAME
ks_snapshot - take a snapshot of kstat data
SYNOPSIS
#include <sys/types.h>
#include <sys/kstat.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>
int prefix_ks_snapshot(kstat_t *ksp, void *buf, int rw);
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI).
PARAMETERS
ksp Pointer to a kstat(9S) structure.
buf Pointer to a buffer to copy the snapshot into.
rw Read/Write flag. Possible values are:
KSTAT_READ Copy driver statistics from the driver to the buffer.
KSTAT_WRITE Copy statistics from the buffer to the driver.
DESCRIPTION
The kstat mechanism allows for an optional ks_snapshot() function to copy kstat data. This is the routine that is called to marshall the
kstat data to be copied to user-land. A driver can opt to use a custom snapshot routine rather than the default snapshot routine; to take
advantage of this feature, set the ks_snapshot field before calling kstat_install(9F).
The ks_snapshot() function must have the following structure:
static int
xx_kstat_snapshot(kstat_t *ksp, void *buf, int rw)
{
if (rw == KSTAT_WRITE) {
/* set the native stats to the values in buf */
/* return EACCES if you don't support this */
} else {
/* copy the kstat-specific data into buf */
}
return(0);
}
In general, the ks_snapshot() routine might need to refer to provider-private data; for example, it might need a pointer to the provider's
raw statistics. The ks_private field is available for this purpose. Its use is entirely at the provider's discretion.
No kstat locking should be done inside the ks_update() routine. The caller will already be holding the kstat's ks_lock (to ensure consis-
tent data) and will prevent the kstat from being removed.
1. ks_snaptime must be set (via gethrtime(9F)) to timestamp the data.
2. Data gets copied from the kstat to the buffer on KSTAT_READ, and from the buffer to the kstat on KSTAT_WRITE.
RETURN VALUES
0 Success
EACCES If KSTAT_WRITE is not allowed
EIO For any other error
CONTEXT
This function is called from user context only.
EXAMPLES
Example 1 Named kstats with Long Strings (KSTAT_DATA_STRING)
static int
xxx_kstat_snapshot(kstat_t *ksp, void *buf, int rw)
{
if (rw == KSTAT_WRITE) {
return (EACCES);
} else {
kstat_named_t *knp = buf;
char *end = knp + ksp->ks_ndata;
uint_t i;
bcopy(ksp->ks_data, buf,
sizeof (kstat_named_t) * ksp->ks_ndata);
/*
* Now copy the strings to the end of the buffer, and
* update the pointers appropriately.
*/
for (i = 0; i < ksp->ks_ndata; i++, knp++)
if (knp->data_type == KSTAT_DATA_STRING &&
KSTAT_NAMED_STR_PTR(knp) != NULL) {
bcopy(KSTAT_NAMED_STR_PTR(knp), end,
KSTAT_NAMED_STR_BUFLEN(knp));
KSTAT_NAMED_STR_PTR(knp) = end;
end += KSTAT_NAMED_STR_BUFLEN(knp);
}
}
return(0);
}
SEE ALSO ks_update(9E), kstat_create(9F), kstat_install(9F), kstat(9S)
Writing Device Drivers
SunOS 5.11 4 Dec 2002 ks_snapshot(9E)