KSTAT_CREATE(9)

Bestie, welcome to kstat_create(9) from the Kernel Developer's Manual — this is the kernel statistics provider API and it's lowkey main character energy. 💖✨

✨ NAME ✨

kstat_create, kstat_read_nop, kstat_set_wlock, kstat_set_rlock, kstat_set_mutex, kstat_install, kstat_remove, kstat_destroy — kernel statistics provider API.

🌸 SYNOPSIS 🌸

       #include <sys/kstat.h>

       struct kstat *
       kstat_create(const char *provider, unsigned int instance,
           const char *name, unsigned int unit, unsigned int type,
           unsigned int flags);

       int
       kstat_read_nop(struct kstat *ks);

       void
       kstat_set_wlock(struct kstat *ks, struct rwlock *rwl);

       void
       kstat_set_rlock(struct kstat *ks, struct rwlock *rwl);

       void
       kstat_set_mutex(struct kstat *ks, struct mutex *mtx);

       void
       kstat_install(struct kstat *ks);

       void
       kstat_remove(struct kstat *ks);

       void
       kstat_destroy(struct kstat *ks);

💫 DESCRIPTION 💫

Okay so kernel subsystems can provide statistics to userland using the kernel statistics (kstat) API. That's the whole vibe. 💅

A kstat is uniquely identified by a tuple made up of the provider, instances, name, and unit arguments.

The information exported by a kstat is typed. The supported kstat types are:

• KSTAT_T_RAW — the kstat provides raw bytes. simple, raw, iconic.
• KSTAT_T_KV — the kstat provides a series of struct kstat_kv structures that represent key/value information. See kstat_kv_init(9) for more detail. key/value cuties.

Below is a simplified version of the kstat structure that shows the fields that a subsystem operates on:

       struct kstat {
               void                     *ks_softc;
               void                     *ks_ptr;

               void                     *ks_data;
               size_t                    ks_datalen;
               struct timespec           ks_updated;

               int                     (*ks_read)(struct kstat *ks);
               int                     (*ks_copy)(struct kstat *ks, void *dst);

               const struct kstat_lock_ops *
                                         ks_lock_ops;
               void                     *ks_lock;
       };

The ks_softc and ks_ptr fields are available for the subsystem providing the kstat to use. For example, if a hardware device driver is providing a kstat then ks_softc can be initialised with a reference to the softc structure allocated for that device driver. ks_ptr is intended for use by a subsystem to refer to data or state that is only needed when providing the kstat which would not otherwise be referenced by the provider.

The ks_datalen field specifies how much data is exported by the kstat to userland.

ks_updated is set by the provider to the system uptime when the kstat data was updated.

ks_data may be set to a data buffer used to store the kstat data payload.

The ks_read handler is called by the kstat API when userland requests the current kstat data. A kstat provider may ignore the request and update the data by another process. For example, a device may periodically update a set of statistics and notify the kernel when the new statistics are available with an interrupt. Such a driver would update the kstat data and ks_updated when the interrupt is processed, and ignore the request to update from userland. The default ks_read handler sets ks_updated using getnanouptime(9).

The ks_copy handler is used by the kstat API to copy the current kstat data into the dst buffer. The default ks_copy handler uses memcpy(3) to copy ks_datalen bytes from ks_data to dst.

Accesses to the above kstat structure fields and calls to the ks_read and ks_copy handlers by the kstat subsystem are serialised by the locking primitive referenced by ks_lock. By default ks_lock references a global write lock provided by the kstat API, but should be set to a provider specific lock with the kstat_set_rlock, kstat_set_wlock, or kstat_set_mutex functions. Lock it down, bestie.

The kstat_create() function allocates a kstat structure and adds it to the list of statistics that userland can query. Once a kstat structure has been created, the caller is responsible for initialising the structure.

kstat_read_nop() can be used as a ks_read handler to ignore the request to update the kstat data and ks_updated timestamp.

The kstat_set_wlock() and kstat_set_rlock() functions specifies that the rwl read/write lock should be used as an exclusive or shared lock respectively by the kstat API when interacting with the provider.

The kstat_set_mutex() function specifies that the mtx mutex should be acquired by the kstat API when interacting with the provider.

After the structure has been initialised, kstat_install() notifies the kstat subsystem that ks can be used to export information to userland.

kstat_remove() disables the kstat, preventing it from being used to export information to userland. This allows allocations referenced by the kstat struct to be released and configuration torn down before the kstat itself is freed with kstat_destroy().

kstat_destroy() removes ks from the list of exported statistics and frees it.

🌈 CONTEXT 🌈

kstat_create(), kstat_install(), kstat_remove(), kstat_set_wlock(), kstat_set_rlock(), kstat_set_mutex(), and kstat_destroy() can be called during autoconf, or from process context. They cannot be called by a ks_read or ks_copy handler. Not in those handlers, periodt.

🎀 RETURN VALUES 🎀

kstat_create() returns a pointer to a kstat structure on success, or NULL on failure. slay when it works, check for NULL when it doesn't.

👀 SEE ALSO 👀

• kstat(1)
• memcpy(3)
• kstat(4)
• kstat_kv_init(9)
• mtx_enter(9)
• rw_enter(9)

📜 HISTORY 📜

These functions first appeared in OpenBSD 6.8. OG status.

👑 AUTHORS 👑

David Gwynne <dlg@openbsd.org> the icon behind the API.

---

This page is from the Debian manual set, dated September 10, 2022 — it's the KSTAT_CREATE(9) page, and that's the tea ☕💅🫶.