1.\" $NetBSD: envstat.8,v 1.67 2022/11/21 21:24:02 brad Exp $ 2.\" 3.\" Copyright (c) 2000, 2007, 2008, 2009, 2014 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Juan Romero Pardines and Bill Squier. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd November 14, 2020 31.Dt ENVSTAT 8 32.Os 33.Sh NAME 34.Nm envstat 35.Nd utility to handle environmental sensors 36.Sh SYNOPSIS 37.Nm 38.Op Fl DfIklnSTW 39.Op Fl c Ar file 40.Op Fl d Ar device 41.Op Fl i Ar interval 42.Op Fl s Ar "device:sensor,..." 43.Op Fl w Ar width 44.Nm 45.Fl x 46.Op Fl d Ar device 47.Op Fl s Ar "device:sensor,..." 48.Op Ar property... 49.Sh DESCRIPTION 50.Nm 51is a utility that handles various aspects of the sensors 52registered with the 53.Xr envsys 4 54framework. 55It is capable of displaying sensor values as well as 56changing parameters and setting critical limits for the sensors. 57.Pp 58In display mode, column widths as well as displayed sensors 59are fully customizable. 60Critical limits or other properties can be set via the configuration file. 61If critical limits were set previously, the display mode will show 62the critical limits in addition to the current values. 63.Pp 64The following options are available: 65.Bl -tag -width flag 66.It Fl c 67Accepts a file as argument to set properties for sensors in 68devices registered with the framework. 69See the 70.Xr envsys.conf 5 71manual page for more information. 72.It Fl D 73Display the names of the devices that are currently registered with 74the 75.Xr envsys 4 76framework, one per line, along with some properties for the device 77(for example, its refresh timeout value). 78.It Fl d Ar device 79Display only the sensors for the given 80.Ar device . 81This is useful when there are multiple devices registered and 82you want to only see results from a specific device. 83.It Fl f 84Display temperature values in degrees Fahrenheit. 85The default is to display temperature values in degrees Celsius. 86.It Fl I 87This flag skips the sensors with invalid state; these are normally 88shown using the 89.Qq N/A 90string by default. 91.It Fl i Ar interval 92Repeat the display every 93.Ar interval 94seconds. 95Note that some devices do not provide fresh values on demand. 96See the individual device's manual page for meaningful values for 97.Ar interval . 98If not specified, or specified as 0, 99.Nm 100produces one round of values and exits. 101.It Fl k 102Display temperature values in Kelvin. 103The default is to display temperature values in degrees Celsius. 104.It Fl l 105List the names of all supported sensors, one per line. 106Use of this flag causes 107.Nm 108to ignore all other option flags. 109.It Fl n 110Print only the current value of a sensor and no headers. 111If statistics are selected with 112.Fl T 113then also display max, min and average. 114.It Fl r 115This flag is provided for compatibility reasons and there's no need 116to use it. 117In the previous implementation, it was used to enable the 118row mode; this mode is now the default. 119.It Fl S 120This flag is used to restore defaults to all devices registered with 121the framework. 122This will remove all properties that were set in 123the configuration file to the setting that the devices use by 124default. 125.It Fl s Ar "device:sensor,..." 126Restrict the display to the named devices and sensors. 127The pair device and sensor description must be supplied as a comma separated list. 128Device as well as sensor descriptions are case sensitive. 129Note that the order of the arguments given does not influence the order of output. 130.It Fl T 131Create and display max, min and average statistics for a sensor. 132Must be used with an 133.Ar interval , 134otherwise statistics cannot be collected up. 135Please note that to get realistic 136values a lower interval value should be used, but that will also increase 137overhead. 138.It Fl w Ar width 139Use 140.Ar width 141as the column width for the output. 142Each column is additionally separated by a single space. 143The default is the length of the longest sensor name. 144.It Fl W 145This option has no effect. 146It is retained for historical reasons. 147.It Fl x 148Shows the raw XML property list used by the 149.Xr sysmon_envsys 9 150framework that contains details about all registered devices 151and sensors. 152If 153.Ar property 154is specified, the value of that property is printed. 155The property list can be filtered with the 156.Fl d 157or 158.Fl s 159options. 160If 161.Fl s 162is used with only a single sensor, only the properties 163of this sensor are returned, not a list of sensors. 164.El 165.Sh UNITS 166The display mode may show some values with abbreviated units; 167for example: 168.Bl -tag -width "12345678" -compact -offset indent 169.It A 170Amperes 171.It Ah 172Ampere-hours 173.It degC 174degrees Celsius 175.It degF 176degrees Fahrenheit 177.It K 178Kelvin 179.It Ohms 180Ohms 181.It RPM 182Revolutions per minute 183.It V 184Volts DC 185.It VAC 186Volts AC 187.It W 188Watts 189.It Wh 190Watt-hours 191.It %rH 192relative Humidity 193.It hPa 194Hectopascals 195.El 196.Sh EXAMPLES 197To display the 198.Dq charge 199sensor of the device 200.Ar acpibat0 201in one line every ten seconds: 202.Pp 203.Dl $ envstat -s \*qacpibat0:charge\*q -i 10 204.Pp 205To list the devices that are currently registered with 206.Xr envsys 4 : 207.Pp 208.Dl $ envstat -D 209.Pp 210To display the sensors of the device 211.Ar aibs0 : 212.Pp 213.Dl $ envstat -d aibs0 214.Pp 215To set all properties specified in the configuration file: 216.Pp 217.Dl $ envstat -c /etc/envsys.conf 218.Pp 219To remove all properties that were set previously in the configuration 220file: 221.Pp 222.Dl $ envstat -S 223.Pp 224To display statistics for all sensors and ignoring sensors with 225invalid states every second: 226.Pp 227.Dl $ envstat -ITi1 228.Pp 229To return a single temperature value: 230.Pp 231.Dl $ envstat -s vcmbox0:temperature -x /cur-value 232.Pp 233To return values of multiple temperature sensors from a single device 234.Pp 235.Dl $ envstat -s 'thinkpad0:temperature 0,thinkpad0:temperature 1' -x /thinkpad0/0/cur-value /thinkpad0/1/cur-value 236.Pp 237To return values of temperature sensors from multiple devices: 238.Pp 239.Dl $ envstat -s 'coretemp0:cpu0 temperature,coretemp1:cpu 2 temperature' -x /coretemp0/0/cur-value /coretemp1/0/cur-value 240.Sh SEE ALSO 241.Xr units 1 , 242.Xr proplib 3 , 243.Xr acpiacad 4 , 244.Xr acpibat 4 , 245.Xr acpitz 4 , 246.Xr admtemp 4 , 247.Xr aibs 4 , 248.Xr amdtemp 4 , 249.Xr aps 4 , 250.Xr arcmsr 4 , 251.Xr battery_pmu 4 , 252.Xr cac 4 , 253.Xr dbcool 4 , 254.Xr envsys 4 , 255.Xr finsio 4 , 256.Xr hythygtemp 4 , 257.Xr ipmi 4 , 258.Xr itesio 4 , 259.Xr lm 4 , 260.Xr lmtemp 4 , 261.Xr mfi 4 , 262.Xr nsclpcsio 4 , 263.Xr owtemp 4 , 264.\".Xr pic16lc 4 , 265.Xr smsc 4 , 266.Xr sparc/tctrl 4 , 267.Xr sparc64/envctrl 4 , 268.Xr thinkpad 4 , 269.Xr tm121temp 4 , 270.Xr ug 4 , 271.Xr viaenv 4 , 272.Xr x86/coretemp 4 , 273.Xr envsys.conf 5 274.Sh HISTORY 275.Nm 276appeared in 277.Nx 1.5 . 278It was completely rewritten from scratch for 279.Nx 5.0 . 280.Sh AUTHORS 281.An -nosplit 282The 283.Nm 284utility that appeared in 285.Nx 5.0 286was written by 287.An Juan Romero Pardines . 288The previous version was written by 289.An Bill Squier . 290.Sh BUGS 291When displaying statistics using the 292.Fl T 293option, the average value is an average of the minimum, maximum, and 294current sensor values. 295It is not an average of all current values displayed during the session. 296