asapm(1) asapm(1)
NAME
asapm - the AfterStep APM monitor
SYNOPSIS
asapm [-h] [-H] [-V]
[-rc resource file]
[-iconic] [-withdrawn] [-standout]
[-position [+|-]x[+|-]y]
[-syslevels] [-systime]
[-dev device] [-fail]
[-u update rate]
[-display display]
[-status color]
[-green color]
[-yellow color]
[-red color]
[-lower color]
[-upper color]
DESCRIPTION
The asapm is a X11 application that acts as an Advanced
Power Management system monitor for laptop and notebook
PCs running Linux, FreeBSD, or NetBSD. The asapm provides
a distinctive Afterstep window manager look and feel and
features multiple options to allow the customization.
Basically, the tool shows you the following:
- The bar-like indicator of the charge left in the battery
which appears on the left side and is battery-shaped.
The bottom part shows the charge left in the battery.
The colors may be customized.
- The top line works as a pair of indicators. You see
there a battery outline which is "green" when the
battery status is high, "yellow" when the battery status
is low, and "red" when the battery status is critical.
The colors may be customized. The definition of the
high, low, critical status may be mine :-) or APM
daemon's - you can choose. The AC plug outline is black
while you run the computer on the battery and it turns
"green" when your computer is connected to the mains.
The plug will turn red while the battery is charging
and return back to green when the battery is full.
- The second line is the charge left in the battery in
percent. If the APM daemon does not return a good value
for it, the display is disabled.
- The third line is the estimate of the time left before
the complete discharge of the battery. This estimate is
either provided by the APM daemon or is calculated by
this tool itself. When there is no estimate available
the display is disabled.
Version 2.9 25 Nov 1999 1
asapm(1) asapm(1)
Not all APM systems support the estimation of the lifetime
of the battery. If it is supported it is shown. Otherwise
the asapm tool will try to do its best to estimate the
time by itself. This will work only when the computer is
running on the battery. If the computer is connected to
the mains the display is disabled. When the asapm starts
in such a situation, it will disable the display for the
time until the first change in the battery charge is
detected. Then the tool will calculate the elapsed time
and try to predict how long it will take before the bat
tery goes flat. The value displayed is not precise so
don't rely too much on this. And if you do not like it you
can switch it off with the -systime option.
The resource files may specify some of the command-line
options. The logic of asapm is simple: first it parses the
resource file at the default location (~/.asapmrc) if it
exists and then goes to parse the command line parsing.
Therefore any options on the command line override the
corresponding options in the resource file. Unfortunately
there is no complete correspondence between what you can
specify on the command line and in the configuration file.
When one of the parameters on the command line is -rc
which specifies an alternative location for the resource
file, asapm resets all options and goes to parse that
resource file. After parsing it, asapm returns and re-
parses the command line.
CONFIGURATION OPTIONS
-h or -H
prints a short description and usage message.
-V
Version control. Prints out the version of the pro
gram.
-rc resource file
Specifies the alternative location for the resource
file. The default location is ~/.asapmrc. If the
alternative file is specified, the default location
is parsed first, then the defaults are restored for
everything except the reactions and the alternative
file is read. I know this is weird - care to
change?
-position [+|-]x[+|-]y
Displays the window at the specified location on
the screen. This works as standard X Windows geome
try option.
-iconic
Starts the asapm application in the iconized mode.
The icon has the same appearance with the main
Version 2.9 25 Nov 1999 2
asapm(1) asapm(1)
window. When this option is given, the -position
refers to the position of the icon window as well
as the main window.
-withdrawn
Starts the asapm application in the withdrawn mode.
This option is necessary to be able to dock the
asapm in the WindowMaker dock. When this option is
given, the -position refers to the position of the
icon window as well as the main window. asapm
ignores the -iconic option when started in with
drawn mode.
-standout
This changes the appearance of the asapm display
from "pushed-in" to "popped-out". The first is the
default look. The "popped-out" look is also a bit
darker then the "pushed-in" and according to some
looks much better in WindowMaker's dock. Give it a
try in any case.
-syslevels
This will make asapm to pay attention to what the
APM daemon says about high/low/critical state of
the battery and reflect those levels by changing
the labels to the appropriate color.
By default, asapm would consider levels of power
below 40% as low and below 20% as critical because
I personally like it that way :-). I want to notice
well in advance that the power is running low and
not only when the APM daemon starts wall'ing you
about it. On my machine I get beeps, the hardware
battery indicator starts flashing and APM daemon
sends messages to all windows when the power status
changes to "low". You know, all the bells and
whistles are on and now you want the tool to change
the indicator to yellow. What's the point? Anyway,
if you really want it - this is the option.
There is a good application to this option though.
When APM reports the status of the battery being
something inconsistent with the percent charge
reported you may use it to get a better picture of
what is going on. I can imagine that by some
glitch APM reports the charge of the battery 100%
but the battery state being critical. Then this
option will allow asapm to reflect this status. It
may be possible that your APM does not report the
charge percentage but does report the status of the
battery too. This option allows you to see the sta
tus of the battery again.
Version 2.9 25 Nov 1999 3
asapm(1) asapm(1)
-systime
Some APM daemons/BIOSes do not supply the time left
until the complete discharge of the battery. Mine
is one of those. By default, asapm detects that the
APM daemon does not return a good value and tries
to estimate the time itself. It is an estimation
based on the time that passed between the two last
changes of the power status.
You can use this option to make asapm use the time
only if it is supplied by the daemon and not
attempt any calculations itself. The display for
the time left will be disabled all the time if the
feature is not supported by the daemon then.
This option does not change the behaviour of asapm
if the APM daemon and BIOS support the notion of
time left until the complete discharge of the bat
tery.
-dev <device>
Using this option you can specify the location of
the file that serves the APM information on your
system. The default location of the APM device on
Linux systems is /proc/apm and on FreeBSD and
NetBSD systems it is /dev/apm device.
-fail
By default asapm does not quit if an error happens
during reading the APM device file. It prints a
warning and continues. Most of the time all display
parts will be disabled too. This option tells asapm
to quit immediately if an error was encountered. I
recommend specifying this option when you run from
AfterStep Wharf because the output of asapm can
fill up your log file if troubles happen and you
probably want notice it.
However, if you experience occasional glitches in
the working of APM daemon (unheard of) or you want
to see what APM looks like while not having APM on
your machine this option will help.
-u <update rate>
Changes the polling rate for accessing the APM
data. The update rate is specified in seconds. The
value of 1 is the minimum. Default value is 1 sec
ond.
-status <color>
Changes the color of the time-left and percentile
indicators for asapm. The default color is also
LightSeaGreen.
Version 2.9 25 Nov 1999 4
asapm(1) asapm(1)
-green <color>
Changes the color of the "green" image of the bat
tery and power plug when those are in "green" con
dition. By default the "green" condition is when
the charge of the battery is above 40%. The
default color is LightSeaGreen.
-yellow <color>
Changes the color of the "yellow" image of the bat
tery. The "yellow" image corresponds to low charge
left state and by default is when the charge of the
battery is above 20% but below 40%. The default is
DarkGold.
-red <color>
Changes the color of the "red" image of the bat
tery. The "red" image corresponds to critical bat
tery charge state and by default is when the charge
of the battery is below 20%. The default is a kind
of red.
-lower <color>
Changes the color of the bottom side of the indica
tor that indicates the battery charge left. The
indicator is the battery-shaped image on the left.
The default is a kind of blue.
-upper <color>
Changes the color of the top side of the battery
indicator that indicates, well, you know, the used
up part of the battery charge. The default is a
kind of red.
-display <name>
The name of the display to start the window in. It
works just as X Windows display option.
RESOURCE FILE SYNTAX
fail
Force the tool to quit when an error is detected
while accessing the APM device. Equivalent to the
command line "-fail" option.
nofail
The opposite of "fail". This is the default
behaviour.
device <name>
Use the alternative APM device to read the informa
tion. Equivalent to the "-dev" command-line
option.
SysLevels
Use the information the APM daemon provides
Version 2.9 25 Nov 1999 5
asapm(1) asapm(1)
concerning the level of the power being
high/low/critical. Equivalent to the "-syslevels"
command line option.
NoSysLevels
Use my own definition of the low/critical levels of
power as being less or equal to 40%/20% respec
tively.
SysTime
Don't attempt to calculate the time to live for the
battery even if the APM daemon does not supply any
value. Equivalent to the -systime command line
option.
NoSysTime
Opposite of "SysTime". Calculate our own values for
the remaining time on the battery power when APM
daemon does not supply any value.
ColorDepth 8/16
Force the given color depth. Specify 16 or 8. asapm
does automagically detect the display's color depth
and will run in the correct mode but this is handy
if you want to force it run with different look
than the default for your color depth. asapm uses
more than 32 colors in 16bpp and around 12 in 8bpp.
This is the equivalent of the command line "-bpp"
option.
ACOn <command>
Execute the given command when the APM daemon
reports the AC power being switched on. You may
want to execute here things that make your computer
consume more power.
ACOff <command>
Execute the specified command when the APM daemon
says the AC was switched off (= we are running on
some kind of battery). You may want to execute
commands here that make your computer more power-
conscious and save some power.
PowerDown <command>
This command is executed every time the battery
power level decreases. Nothing really useful.
PowerUp <command>
This command is executed every time the battery
power level increases. Not really useful.
DownTo <percent> <command>
Execute the given command when the power level
drops to the given level. The level must be exact,
Version 2.9 25 Nov 1999 6
asapm(1) asapm(1)
the command is not executed on the "lower or equal"
basis. This is the option I wanted. I make it sus
pend my computer when the power drops to 10%. Now
I can forget to switch it off ;-) These commands
may be given multiple times in the rc file.
UpTo <percent> <command>
Executes the command when the power level reaches
up to the given level. I cannot think of any useful
application for this. These commands may be given
multiple times in the rc file.
Status <color>
The color for the time-left and percentile indica
tors for battery strength. The equivalent of the
"-status" command line option.
Green <color>
The color for the battery symbol when the power
level is reasonably high. The equivalent of the
"-green" command line option.
Yellow <color>
The color for the battery symbol when the power
level is low. The equivalent of the "-yellow" com
mand line option.
Red <color>
The color for the battery symbol when the power
level is critical. The equivalent of the "-red"
command line option.
Lower <color>
The color for the power left indicator. This is the
equivalent of the "-lower" command line option.
Upper <color>
The color for the "empty" part of the battery indi
cator. This is the equivalent for the "-upper" com
mand line option.
INVOCATION
asapm can be called in different ways. The most common
invocation is the command line:
user@host[1]% asapm -u 2 -left green -right yellow &
Another way to call asapm is from the window manager:
*Wharf "asapm" nil Swallow "asapm" /usr/local/bin/asapm -fail &
This line, when placed in the wharf file in the users
Afterstep configuration directory will cause asapm to be a
button on the Wharf (1) button bar under the afterstep (1)
Version 2.9 25 Nov 1999 7
asapm(1) asapm(1)
window manager.
If you run WindowMaker then you should use the "-with
drawn" option:
user@host[1]% asapm -withdrawn -standout &
and then drag the icon to the dock.
BUGS
My programs do not have bugs, they just develop random
features ;-)
Well, there are limitations. All the strings for the color
names, display name, and the geometry have the length
limit of 50 characters (terminating zero included). The
string copying routine cuts the names that are longer.
The limit on the APM device name is 256 characters.
The number of hours I can show for the lifetime of the
battery left is limited by the space. The maximum is 99:59
and that is what it shows when the time left is even more.
I doubt that you have a battery that survives longer
though :-)
The total number of reactions specified with the "UpTo"
and "DownTo" resource file switches is limited to ten.
FILES
/proc/apm /dev/apm
SEE ALSO
apm(1),apmd(8)
COPYRIGHTS
Copyright (c) 1998-99 Albert Dorofeev
<Albert@mail.dma.be>
Distributed under GNU General Public License v2 ; see
LICENSE file for more informations.
AUTHORS
Albert "Tigr" Dorofeev <Albert@mail.dma.be>
See the README file for credits.
Version 2.9 25 Nov 1999 8
Man(1) output converted with
man2html