NetBSD/usr.sbin/envstat/envstat.8

.\"	$NetBSD: envstat.8,v 1.27 2007/09/20 19:48:26 plunky Exp $
.\"
.\" Copyright (c) 2000, 2007 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Juan Romero Pardines and Bill Squier.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd September 20, 2007
.Dt ENVSTAT 8
.Os
.Sh NAME
.Nm envstat
.Nd utility to handle environmental sensors
.Sh SYNOPSIS
.Nm
.Op Fl DfIlx
.Op Fl d Ar device
.Op Fl i Ar interval
.Op Fl m Ar critical=... critmax=... critmin=... desc=... rfact=...
.Op Fl s Ar sensor1,sensor2,...
.Op Fl w Ar width
.Sh DESCRIPTION
.Nm
is a utility that handles various aspects of the sensors
registered with the
.Xr envsys 4
framework.
It is capable of displaying sensor values as well as
changing parameters and setting critical limits for the sensors.
.Pp
In display mode, column widths as well as displayed sensors
are fully customizable.
Critical limits can be set in a per-sensor basis.
If critical limits were set previously, the display mode will show
the critical limits in addition to the current values.
.Pp
The following options are available:
.Bl -tag -width flag
.It Fl D
Display the names of the drivers that were registered with
the
.Xr envsys 4
framework, one per line.
.It Fl d
Display only the sensors for a given
.Ar driver .
This is useful when there are multiple drivers registered and
you want to only see those from a specific driver.
.It Fl f
Display temperature values in degrees Fahrenheit.
The default is to display temperature values in degrees Celsius.
When changing properties on a sensor and this flag is specified,
the value provided must be in degrees Fahrenheit too.
.It Fl I
This flag skips the sensors with invalid state, they are showed up
with the
.Em N/A
string by default.
.It Fl i
Repeat the display every
.Ar interval
seconds.
Note that some devices do not provide fresh values on demand.
See the individual device's manual page for meaningful values for
.Ar interval .
If not specified, or specified as 0,
.Nm
produces one line of values and exits.
.It Fl l
List the names of all supported sensors, one per line.
Use of this flag causes
.Nm
to ignore all other option flags.
.It Fl m
This flag can be used to change a description of a sensor, to
change the rfact (resistor factor) in a voltage sensor or
to set critical capacity for (battery sensors) and critical
min and max limits (for all supported sensors).
Recognized keywords are:
.Ar critical , critmax , critmin , desc ,
and
.Ar rfact .
See the
.Sx EXAMPLES
section for more information.
.It Fl r
This flag is only used for compatibility reasons and there's no need
to use it. In the previous implementation, it was used to enable the
row mode; this mode is enabled by default.
.It Fl s
Restrict the display to the named sensors.
The sensor names must be supplied as a comma separated list.
Sensor names are case sensitive. Note that it's mandatory to use the
.Fl d
flag to specify the driver that has the sensor.
.It Fl w
Use
.Ar width
as the column width for the output.
Each column is additionally separated by a single space.
The default is the length of the longest sensor name.
.It Fl x
Shows the property list used by the
.Xr sysmon_envsys 9
framework that contains details about all registered drivers
and sensors.
.El
.Ss CRITICAL LIMITS
Starting with
.Tn envsys 2 ,
it is possible to set critical limits on a specified sensor.
Only one critical limit can be set at a time for a sensor.
For example, you cannot assign multiple limits for the same
sensor or for different sensors.
.Pp
There are three types of
critical limits:
.Ar capacity ,
.Ar max ,
and
.Ar min .
When one of them is set and sensor's current value reaches
it, an event will be sent to
.Xr powerd 8 .
.Pp
Three arguments are required to set/remove a critical/capacity limit,
to change a description or to change the rfact:
.Pp
.Bl -item -offset indent -compact
.It
.Fl d
is required to specify the device that is handling
the sensor.
.It
.Fl m
is required to set the new target mode.
.It
.Fl s
is required to specify sensor's name.
.El
.Pp
The available targets for the
.Fl m
flag are:
.Pp
.Bl -bullet -compact -offset indent
.It
.Ar critical
accepts a percentage number for battery sensors (those showing
a percentage in display mode), also the
.Sy remove
keyword can be used to remove the limit.
.It
.Ar critmax
accepts a number that will be used for the max critical limit
or accepts the
.Sy remove
keyword.
.It
.Ar critmin
accepts a number that will be used for the min critical limit
or accepts the
.Sy remove
keyword.
.It
.Ar desc
accepts a new string that will be used as new description.
.It
.Ar rfact
accepts a number that will be used as new rfact in voltage sensors.
.El
.Pp
Also is possible to remove a critical limit if one was set before,
with the
.Ar remove
keyword passed to the
.Ar critical ,
.Ar critmax ,
or
.Ar critmin
target.
See the
.Sx EXAMPLES
for information how to use it.
.Pp
.Ss CONFIGURATION FILE
It's possible to change properties with the
.Pa /etc/envsys.conf
configuration file. The syntax for this file is the following:
.Bd -literal
device:sensor name:target:value

aiboost0:CPU Temperature:critmax:70
lm0:Temp0:desc:CPU Temperature
smsc0:+3.3V:rfact:56000
.Ed
.Pp
In the example configuration file the first argument is the name of
the device, second argument is the name of the sensor that we want to change,
third argument is the target that will be used for the
.Ar -m
flag and finally the fourth argument is the value that will be used for the
target.
.Pp
The first example sets a critical over limit of
.Dq 70
degC to the
.Dq CPU Temperature
sensor in the
.Dq aiboost0
device. By default the value specified on temperature sensors must be
in degrees Celsius but also it is possible to specify it in degrees Fahrenheit too.
The
.Em value
argument will have to contain the
.Dq degF
keyword:
.Bd -literal
aiboost0:CPU Temperature:critmax:120degF
.Ed
.Pp
The second example in the configuration file sets the description
.Dq CPU Temperature
to the sensor
.Dq Temp0
in the
.Dq lm0
device.
.Pp
The last example in the configuration file sets the rfact value to
.Em 56000
to the
.Dq +3.3V
sensor in the
.Dq smsc0
device.
.Pp
It's possible to set all these properties at boot time with the
.Xr rc.d 8
script available at
.Pa /etc/rc.d/envsys .
.Pp
.Sh EXAMPLES
Display the
.Dq acpibat0 charge
sensor on one line every ten seconds:
.Pp
.Dl $ envstat -s \*qacpibat0 charge\*q -d acpibat0 -i 10
.Pp
Lists the drivers that are currently registered with
.Xr envsys 4 :
.Pp
.Dl $ envstat -D
.Pp
Display the sensors of the driver
.Ar aiboost0 :
.Pp
.Dl $ envstat -d aiboost0
.Pp
Change the description string for the
.Dq +3.3V
sensor to
.Dq +3.3 Volts
in the
.Ar aiboost0
device:
.Pp
.Dl $ envstat -s \*q+3.3V\*q -d aiboost0 -m desc=\*q+3.3 Volts\*q
.Pp
Set a critical max limit to 60 degC for the
.Dq CPU Temp
sensor, in the
.Ar aiboost0
device:
.Pp
.Dl $ envstat -s \*qCPU Temp\*q -d aiboost0 -m critmax=60
.Pp
Set a critical min limit to 1000 RPMs for the
.Dq CPU Fan
sensor, in the
.Ar aiboost0
device:
.Pp
.Dl $ envstat -s \*qCPU Fan\*q -d aiboost0 -m critmin=1000
.Pp
Remove a max critical limit for the
.Dq CPU Temp
sensor, in the
.Ar aiboost0
device:
.Pp
.Dl $ envstat -s \*qCPU Temp\*q -d aiboost0 -m critmax=remove
.Pp
Change the resistor factor (rfact) to 56000 for the
.Dq +3.3V
sensor, in the
.Ar lm0
device:
.Pp
.Dl $ envstat -s \*q+3.3V\*q -d lm0 -m rfact=56000
.Pp
Set a critical capacity to
.Sy 10%
for the
.Dq acpibat0 charge
sensor, in the
.Ar acpibat0
device:
.Pp
.Dl $ envstat -s \*qacpibat0 charge\*q -dacpibat0 -m critical=10
.Sh SEE ALSO
.Xr proplib 3 ,
.Xr acpiacad 4 ,
.Xr acpibat 4 ,
.Xr acpitz 4 ,
.Xr adt7467c 4 ,
.Xr aiboost 4 ,
.Xr aps 4 ,
.Xr envsys 4 ,
.Xr ipmi 4 ,
.Xr it 4 ,
.Xr lm 4 ,
.Xr lmtemp 4 ,
.Xr mfi 4 ,
.Xr nsclpcsio 4 ,
.Xr owtemp 4 ,
.Xr sparc/tctrl 4 ,
.Xr sparc64/envctrl 4 ,
.Xr smsc 4 ,
.Xr tm121temp 4 ,
.Xr ug 4 ,
.Xr viaenv 4
.Sh HISTORY
.Nm
appeared in
.Nx 1.5 .
It was completely rewritten from scratch for
.Nx 5.0 .
.Sh AUTHORS
.An -nosplit
The
.Nm
utility that appeared in
.Nx 5.0
was written by
.An Juan Romero Pardines .
The previous version was written by
.An Bill Squier .