ENVSYS(4)

🌈 envsys — Environmental Systems framework (version 2) 🌈

ENVSYS(4) · Kernel Interfaces Manual

🎀 NAME 🎀

envsys — Environmental Systems framework (version 2)

✨ SYNOPSIS ✨

#include <sys/envsys.h>

💅 DESCRIPTION 💅

Okay bestie, so the envsys framework is literally the support system for hardware monitor devices. Hardware monitoring chips are able to report values from different types of sensors. No cap. 💖

The envsys framework consists of two parts:

the userland part, to receive the current sensor data and to set some properties on sensors: envstat(8).
The kernel part that is able to talk to the devices providing sensor data: sysmon_envsys(9).

The envsys framework uses proplib(3) for communication between kernel and user space. The following ioctl(2) types are available:

💖 ENVSYS_GETDICTIONARY (prop_dictionary_t) 💖

This ioctl(2) is used to receive the global dictionary that is being used in the kernel by the sysmon_envsys(9) framework. It will contain an array of dictionaries per device and one dictionary per sensor plus another special dictionary that contains the properties for a device. Each sensor dictionary will have its own characteristics and values.

The following XML property list represents a virtual device “device0” with one entry for sensor “sensor0” and all available properties set on it, plus another entry for the “device-properties” dictionary (which contains specific properties for a device):

<key>device0</key>
<array>
        <dict>
                <key>allow-rfact</key>
                <true/>
                <key>avg-value</key>
                <integer>36400</integer>
                <key>battery-capacity</key>
                <string>NORMAL</string>
                <key>critical-capacity</key>
                <integer>21417</integer>
                <key>critical-max</key>
                <integer>343150000</integer>
                <key>critical-min</key>
                <integer>288150000</integer>
                <key>cur-value</key>
                <integer>406000</integer>
                <key>description</key>
                <string>CPU Temp</string>
                <key>high-capacity</key>
                <integer>21417</integer>
                <key>index</key>
                <string>sensor0</string>
                <key>max-value</key>
                <integer>3894000</integer>
                <key>maximum-capacity</key>
                <integer>21417</integer>
                <key>min-value</key>
                <integer>2894000</integer>
                <key>monitoring-state-critical</key>
                <true/>
                <key>monitoring-state-critover</key>
                <true/>
                <key>monitoring-state-critunder</key>
                <true/>
                <key>monitoring-state-state-changed</key>
                <true/>
                <key>monitoring-state-warnover</key>
                <true/>
                <key>monitoring-state-warnunder</key>
                <true/>
                <key>monitoring-supported</key>
                <true/>
                <key>state</key>
                <string>valid</string>
                <key>type</key>
                <string>Ampere hour</string>
                <key>want-percentage</key>
                <true/>
                <key>warning-capacity</key>
                <integer>19234</integer>
                <key>warning-max</key>
                <integer>323150000</integer>
                <key>warning-min</key>
                <integer>298150000</integer>
        </dict>
        <dict>
                <key>device-properties</key>
                <dict>
                        <key>refresh-timeout</key>
                        <integer>0xa</integer>
                </dict>
        </dict>
</array>

Let's explain some more about those objects:

allow-rfact — Set to true means that the sensor is able to change the resistor factor, only used in Voltage sensors.
avg-value — Current average value in the sensor.
battery-capacity — Current capacity state for a battery capacity sensor.
critical-capacity — Critical capacity set previously by the ENVSYS_SETDICTIONARY ioctl(2). Only available on sensors with the want-percentage object enabled.
critical-max — Critical max limit set previously by the ENVSYS_SETDICTIONARY ioctl(2).
critical-min — Critical min limit set previously by the ENVSYS_SETDICTIONARY ioctl(2).
cur-value — Current value in the sensor.
description — Description of the sensor.
high-capacity — High capacity set previously by the ENVSYS_SETDICTIONARY ioctl(2). Only available on sensors with the want-percentage object enabled. Used to monitor possible over-charging of batteries.
index — Index position of the sensor.
max-value — Current max value in the sensor.
maximum-capacity — Maximum capacity set previously by the ENVSYS_SETDICTIONARY ioctl(2). Only available on sensors with the want-percentage object enabled. Used to monitor possible over-charging of batteries.
min-value — Current min value in the sensor.
monitoring-state-critical — If true, the device has enabled the flag to monitor a critical state.
monitoring-state-hw-range-limits — If true, the device has enabled the flag to monitor warning or critical limits.
monitoring-state-state-changed — If true, the device has enabled the flag to monitor for state changes in a drive or Battery state sensor.
monitoring-supported — If true, critical/warning capacity/max/min limits may be set by the ENVSYS_SETDICTIONARY ioctl(2).
state — Current state in the sensor.
type — Type of unit in the sensor.
want-percentage — If true, max-value and cur-value are valid and a percentage may be computed from them.
warning-capacity — Warning capacity set previously by the ENVSYS_SETDICTIONARY ioctl(2). Only available on sensors with the want-percentage object enabled.
warning-max — Warning max limit set previously by the ENVSYS_SETDICTIONARY ioctl(2).
warning-min — Warning min limit set previously by the ENVSYS_SETDICTIONARY ioctl(2).

🦋 ENVSYS_REMOVEPROPS (prop_dictionary_t) 🦋

This ioctl(2) is used to remove all properties that are currently set via the ENVSYS_SETDICTIONARY ioctl. The values will be set to defaults, the ones that the device uses.

Only one object is allowed on this dictionary:

<key>envsys-remove-props</key>
<true/>

It is a boolean object and must be set to true to be effective.

🌸 ENVSYS_SETDICTIONARY (prop_dictionary_t) 🌸

This ioctl(2) is used to send a dictionary with new properties that should be processed by the envsys framework. Only a set of predefined keywords are recognized by the kernel part. The following is the property list representation of a dictionary with all recognized and required keywords that a sensor understands:

<dict>
        <key>description</key>
        <string>cpu temp</string>
        <key>rfact</key>
        <integer>56000</integer>
        <key>critical-capacity</key>
        <integer>10</integer>
        <key>critical-max</key>
        <integer>3400</integer>
        <key>critical-min</key>
        <integer>2800</integer>
        <key>high-capacity</key>
        <integer>95</integer>
        <key>maximum-capacity</key>
        <integer>100</integer>
        <key>warning-capacity</key>
        <integer>15</integer>
        <key>warning-max</key>
        <integer>3200</integer>
        <key>warning-min</key>
        <integer>2900</integer>
</dict>

Also if some properties in a device need to be changed, the “device-properties” dictionary must be used. At this moment only the “refresh-timeout” property is understood. This has the following structure:

<dict>
        <key>device-properties</key>
        <dict>
                <key>refresh-timeout</key>
                <integer>0xa</integer>
        </dict>
</dict>

A dictionary sent to the kernel with this ioctl(2) should have the following structure:

okay so the dictionary shape it wants is literally:

           <dict>
                   <key>device_name</key>
                   <array>
                           <dict>
                                   <key>index</key>
                                   <string>sensor0</string>
                                   <key>description</key>
                                   <string>cpu temp</string>
                                   ...
                                   Another property for this sensor
                                   ...
                           </dict>
                           ...
                           Another dictionary for device-properties or sensor
                           ...
                   </array>
                   ...
                   Another device as above
                   ...
           </dict>

the named device is gonna be an array full of dictionaries, and every dictionary needs the index object that names the sensor those new properties are for. if you send an unknown object inside the dictionary, you get EINVAL back — or if the sensor doesn’t support changing rfact (voltage sensors) or critical/warning/capacity limits, ENOTSUP comes back instead.

on top of that, there are these ioctl(2) commands kept around for compatibility, for apps written against the original experimental envsys API that existed between NetBSD 1.5 and NetBSD 4.0. they’ve been deprecated since NetBSD 5.0, and they may be removed at any time, so like… don’t get attached:

ENVSYS_GTREDATA (envsys_tre_data_t)
ENVSYS_GTREINFO (envsys_basic_info_t)

💖 NOTES 💖

when you’re setting a critical/warning max or min limit through the ENVSYS_SETDICTIONARY ioctl(2), bestie, you gotta know that sysmon_envsys(9) expects a proper unit — so the value has to be converted first. peep sysmon_envsys(9) for the full deets.

also, when you’re setting a critical or warning capacity limit, the formula to send a proper value to sysmon_envsys(9) is literally:

value = (value / 100) * max value

the max value is available in the sensor’s dictionary. periodt.

🌸 EXAMPLES 🌸

this example shows how to change the description of sensor0 in the aibs0 device with the ENVSYS_SETDICTIONARY ioctl(2):

       int
       main(void)
       {
               prop_dictionary_t global_dict, sensor_dict;
               prop_array_t array;
               prop_object_t obj;
               int fd, error;

               global_dict = prop_dictionary_create();
               sensor_dict = prop_dictionary_create();
               array = prop_array_create();

               if (!prop_dictionary_set(global_dict, "aibs0", array))
                       err(EINVAL, "prop_dictionary_set global");

               obj = prop_string_create_nocopy("sensor0");
               if (obj == NULL ||
                   !prop_dictionary_set(sensor_dict, "index", obj))
                       err(EINVAL, "sensor index");

               prop_object_release(obj);

               /* new description */
               obj = prop_string_create_cstring_nocopy("CPU core voltage");
               if (obj == NULL ||
                   !prop_dictionary_set(sensor_dict, "description", obj))
                       err(EINVAL, "new description");

               prop_object_release(obj);

               if (!prop_array_add(array, sensor_dict))
                       err(EINVAL, "prop_array_add");

               if ((fd = open(_PATH_SYSMON, O_RDWR)) == -1)
                       err(EXIT_FAILURE, "open");

               /* we are done, send the dictionary */
               error = prop_dictionary_send_ioctl(global_dict,
                                                  fd,
                                                  ENVSYS_SETDICTIONARY);
               prop_object_release(array);
               prop_object_release(sensor_dict);
               prop_object_release(global_dict);
               (void)close(fd);
               return error;
       }

🦋 SEE ALSO 🦋

envsys.conf(5)
envstat(8)
powerd(8)
sysmon_envsys(9)

🎀 HISTORY 🎀

the OG first envsys framework first appeared in NetBSD 1.5. the envsys 2 framework first appeared in NetBSD 5.0. glow-up timeline fr fr ✨

👑 AUTHORS 👑

the (current) envsys 2 framework was implemented by Juan Romero Pardines. additional input on the design was provided by many NetBSD developers around the world — global bestie brainstorm energy 🌍💖

the first envsys framework was implemented by Jason R. Thorpe, Tim Rightnour, and Bill Squier. icons only.

source/version check, because receipts are cute: Debian, May 4, 2021 — ENVSYS(4) 💅🎀

📦 where this page comes from

nixpkgs unstable: netbsd-source 11.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms