usr.sbin/envstat/envstat.8

   1 .\"     $NetBSD: envstat.8,v 1.50 2009/02/15 00:01:19 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2000, 2007, 2008, 2009 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 February 14, 2009
  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 DfIlSTWx
  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 .Sh DESCRIPTION
  45 .Nm
  46 is a utility that handles various aspects of the sensors
  47 registered with the
  48 .Xr envsys 4
  49 framework.
  50 It is capable of displaying sensor values as well as
  51 changing parameters and setting critical limits for the sensors.
  52 .Pp
  53 In display mode, column widths as well as displayed sensors
  54 are fully customizable.
  55 Critical limits or other properties can be set via the configuration file.
  56 If critical limits were set previously, the display mode will show
  57 the critical limits in addition to the current values.
  58 .Pp
  59 The following options are available:
  60 .Bl -tag -width flag
  61 .It Fl c
  62 Accepts a file as argument to set properties for sensors in
  63 devices registered with the framework.
  64 See the
  65 .Xr envsys.conf 5
  66 manual page for more information.
  67 .It Fl D
  68 Display the names of the drivers that were registered with
  69 the
  70 .Xr envsys 4
  71 framework, one per line and some properties for the driver: refresh timeout
  72 value, for example.
  73 .It Fl d Ar device
  74 Display only the sensors for the given
  75 .Ar device .
  76 This is useful when there are multiple devices registered and
  77 you want to only see results from a specific device.
  78 .It Fl f
  79 Display temperature values in degrees Fahrenheit.
  80 The default is to display temperature values in degrees Celsius.
  81 .It Fl I
  82 This flag skips the sensors with invalid state, these are normally
  83 shown using the
  84 .Qq N/A
  85 string by default.
  86 .It Fl i Ar interval
  87 Repeat the display every
  88 .Ar interval
  89 seconds.
  90 Note that some devices do not provide fresh values on demand.
  91 See the individual device's manual page for meaningful values for
  92 .Ar interval .
  93 If not specified, or specified as 0,
  94 .Nm
  95 produces one round of values and exits.
  96 .It Fl k
  97 Display temperature values in Kelvin.
  98 The default is to display temperature values in degrees Celsius.
  99 .It Fl l
 100 List the names of all supported sensors, one per line.
 101 Use of this flag causes
 102 .Nm
 103 to ignore all other option flags.
 104 .It Fl r
 105 This flag is provided for compatibility reasons and there's no need
 106 to use it.
 107 In the previous implementation, it was used to enable the
 108 row mode; this mode is now the default.
 109 .It Fl S
 110 This flag is used to restore defaults to all devices registered with
 111 the framework.
 112 This will remove all properties that were set in
 113 the configuration file to the setting that the drivers use by
 114 default.
 115 .It Fl s Ar "device:sensor,..."
 116 Restrict the display to the named sensors.
 117 The pair device and sensor description must be supplied as a comma separated list.
 118 Device as well as sensor descriptions are case sensitive.
 119 .It Fl T
 120 Create and display max, min and average statistics for a sensor.
 121 Must be used with an
 122 .Ar interval ,
 123 otherwise statistics cannot be collected up.
 124 Please note that to get realistic
 125 values a lower interval value should be used, but that will also increase
 126 overhead.
 127 .It Fl w Ar width
 128 Use
 129 .Ar width
 130 as the column width for the output.
 131 Each column is additionally separated by a single space.
 132 The default is the length of the longest sensor name.
 133 .It Fl W
 134 Display the warning alarm minimum and maximum levels instead of the critical
 135 alarm levels.
 136 .It Fl x
 137 Shows the property list used by the
 138 .Xr sysmon_envsys 9
 139 framework that contains details about all registered drivers
 140 and sensors.
 141 .El
 142 .Sh EXAMPLES
 143 To display the
 144 .Dq charge
 145 sensor of the driver
 146 .Ar acpibat0
 147 in one line every ten seconds:
 148 .Pp
 149 .Dl $ envstat -s \*qacpibat0:charge\*q -i 10
 150 .Pp
 151 To list the drivers that are currently registered with
 152 .Xr envsys 4 :
 153 .Pp
 154 .Dl $ envstat -D
 155 .Pp
 156 To display the sensors of the driver
 157 .Ar aiboost0 :
 158 .Pp
 159 .Dl $ envstat -d aiboost0
 160 .Pp
 161 To set all properties specified in the configuration file:
 162 .Pp
 163 .Dl $ envstat -c /etc/envsys.conf
 164 .Pp
 165 To remove all properties that were set previously in the configuration
 166 file:
 167 .Pp
 168 .Dl $ envstat -S
 169 .Pp
 170 To display statistics for all sensors and ignoring sensors with
 171 invalid states every second:
 172 .Pp
 173 .Dl $ envstat -ITi1
 174 .Sh SEE ALSO
 175 .Xr proplib 3 ,
 176 .Xr acpiacad 4 ,
 177 .Xr acpibat 4 ,
 178 .Xr acpitz 4 ,
 179 .Xr admtemp 4 ,
 180 .Xr aiboost 4 ,
 181 .Xr amdtemp 4 ,
 182 .Xr aps 4 ,
 183 .Xr arcmsr 4 ,
 184 .Xr battery_pmu 4 ,
 185 .Xr cac 4 ,
 186 .Xr coretemp 4 ,
 187 .Xr dbcool 4 ,
 188 .Xr envctrl 4 ,
 189 .Xr envsys 4 ,
 190 .Xr finsio 4 ,
 191 .Xr ipmi 4 ,
 192 .Xr itesio 4 ,
 193 .Xr lm 4 ,
 194 .Xr lmtemp 4 ,
 195 .Xr mfi 4 ,
 196 .Xr nsclpcsio 4 ,
 197 .Xr owtemp 4 ,
 198 .Xr pic16lc 4 ,
 199 .Xr smsc 4 ,
 200 .Xr tctrl 4 ,
 201 .Xr thinkpad 4 ,
 202 .Xr tm121temp 4 ,
 203 .Xr ug 4 ,
 204 .Xr viaenv 4 ,
 205 .Xr envsys.conf 5
 206 .Sh HISTORY
 207 .Nm
 208 appeared in
 209 .Nx 1.5 .
 210 It was completely rewritten from scratch for
 211 .Nx 5.0 .
 212 .Sh AUTHORS
 213 .An -nosplit
 214 The
 215 .Nm
 216 utility that appeared in
 217 .Nx 5.0
 218 was written by
 219 .An Juan Romero Pardines .
 220 The previous version was written by
 221 .An Bill Squier .