.\" apmd.8 -- 
.\" Created: Wed Jan 10 15:07:25 1996 by faith@acm.org
.\" Revised: Fri Dec 26 20:34:52 1997 by faith@acm.org
.\" Revised: Wed Jun  2 18:47:02 1999 by db@post.harvard.edu
.\" Copyright 1996, 1997 Rickard E. Faith (faith@acm.org)
.\" Copyright 1999 David Brownell (db@post.harvard.edu)
.\" Modified Feb 2002 Chris Hanson 
.\" Modified Feb 2002 Thomas Hood jdthood_AT_yahoo.co.uk
.\" 
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\" 
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\" 
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\" 
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" 
.TH APMD 8 "26 Feb 2002" "" "Linux Programmer's Manual"
.SH NAME
apmd \- Advanced Power Management (APM) daemon
.SH SYNOPSIS
.BI "apmd"
.BI "[ \-qVvW ]"
.BI "[ \-c " check_seconds " ]
.BI "[ \-P " proxy_cmd " ]"
.BI "[ \-p " percent_to_log " ]"
.BI "[ \-w " warn_percent " ]
.BI "[ \-? ]"
.SH DESCRIPTION
.B apmd
is an APM monitoring daemon.  It works in conjunction with the
Advanced Power Management subsystem,
consisting of power-management hardware, firmware usually
called the "APM BIOS", and a driver in the kernel of your operating system.
The daemon can execute a command (normally a shell script) when certain
events are reported by the APM subsystem, and will log, via
.BR syslogd (8),
certain changes in power status.  When the available battery power becomes
very low it can alert all users on the system.
.PP
When the APM subsystem notifies the daemon of
a pending suspend or standby request,
.B apmd
will invoke the approprate command,
log the event, 
.BR sync (2)
data to the disk
and then tell the APM subsystem to continue its operation.
For "critical" suspends (indicating an emergency shutdown)
only the last step (telling the driver to continue) is performed.
.PP
Power management event handling is implemented, for the most part, in the
.I proxy
program.
The name of this program is
.I /etc/apm/apmd_proxy
by default, but it can be specified using the -P option.
The proxy program is invoked with one or two arguments:
.TP
.B start
Invoked when the daemon starts.
.TP
.B stop
Invoked when the daemon stops.
.TP
.B standby "[ system | user ]"
Invoked when the APM subsystem reports that standby has been initiated.
The second parameter indicates whether the APM BIOS ("system") or the OS
("user") was the originator of the event.
.sp
The "standby" mode conserves power but leaves the
machine able to respond almost immediately to user activity.
Most laptops can't stay in standby mode on battery power for even a day.
Normally, nothing special needs to be done to prepare for "standing by".
.TP
.B suspend "[ system | user ]"
Invoked when the APM subsystem reports that suspension has been initiated.
The second parameter indicates whether the APM BIOS ("system") or the OS
("user") was the originator of the event.
.sp
The "suspend" mode aggressively conserves power.  Usually it involves
shutting off power to all devices except the CPU core and memory, which are kept
in a very low power mode.  Most laptops can stay suspended, using battery power
alone, for several days.  ("Hibernation" is a kind of super-suspend, where all
that state is written to disk and the machine uses no power.  Hibernation is
treated as a suspend by the APM subsystem.)
.sp
PCMCIA devices may need to be disabled using
.BR cardctl (8),
and some modular device drivers may need to be unloaded.
.TP
.B resume "[ suspend | standby | critical ]"
Invoked when the APM subsystem reports that computer has resumed normal operation.
The second parameter indicates which mode it has resumed from.
.sp
(A "critical" suspend is a suspension that the APM subsystem performs
in an emergency.  The daemon does not run the proxy program for a critical suspend.)
.sp
PCMCIA devices may need to be re-enabled using
.BR cardctl (8),
and some modular drivers may need to be reloaded or otherwise reinitialized.
Note that in the case of a critical suspend, the system state may not have been
completely saved.
.TP
.B change power
Invoked when the APM subsystem reports a change in power status, such
as a switch from AC to battery power.
.ig
.TP
.B change time
Invoked when the APM subsystem reports a time change.
..
.TP
.B change battery
Invoked when the APM subsystem reports that the strength of one or more
batteries is "low".  A few minutes of battery power may remain.
.TP
.B change capability
Invoked when the APM subsystem reports some change in power management capabilities.
It may have been caused by operation of a setup utility, or by the installation
or removal of devices.
.PP
This daemon issues a number of different log messages, most of which are
self explanatory.
Battery status log entries contain three fields, separated by commas. 
The first field indicates how full the battery is as a percentage of its
capacity.
The second field indicates whether the battery is charging, not charging, or discharging.
(This information is provided by the APM subsystem.)
When possible, apmd adds in parentheses its estimate of the rate of charging
or discharging.
The third field indicates how much time the battery can or could be used
to power the computer.
When possible, apmd adds in parentheses an estimate of the battery life
(if discharging) or of the time required to charge the battery fully 
(if charging).
.SH OPTIONS
.TP
.BR "\-c " seconds, " \-\-check " seconds
Controls how many seconds to block on the \fI/dev/apm_bios\fR device.  Normally
the daemon blocks until the APM driver reports an event; this number may be
changed to cause battery charge or discharge rates to be checked more often.
.TP
.BR "\-P " proxy_cmd, " \-\-apmd_proxy " proxy_cmd
Identifies the command to invoke when certain APM driver events are reported.
See above for information about the arguments to this script.
.TP
.BR "\-T " seconds, " \-\-apmd_proxy_timeout " seconds
Sets a timeout for the proxy; if the proxy process doesn't finish in this many
seconds, it is killed.  The default is 30 seconds.
.TP
.BR "\-p " percent_change, " \--percentage " percent_change
Controls how often the battery status is logged.  A status line is printed
each time the battery content changes by
.IR percent_change
if logging is enabled.  The default is 5.  Use a value greater than 100
to disable this feature.
.TP
.B \-V, \-\-version
Print the daemon's version and exit.
.TP
.B \-v, \-\-verbose
Enables verbose mode, where each event reported by the APM driver is logged.
.TP
.B \-W, \-\-wall
In addition to logging low battery status (as determined either by
the \fB-w\fR level or by the APM BIOS) using
.BR syslog (2),
also use
.BR wall (1)
to alert all users.  This is most useful if
.BR syslogd (8)
is not set up to write ALERT messages to all users.  If both methods are
used, more warnings will be made during the critical time period.
.TP
.BR "\-w " warn_percent, " \--warn " warn_percent
When the battery is not being charged and the percentage of available power
drops below
.IR warn_percent ,
log a warning at the ALERT level to
.BR syslog (2).
If the
.B \-W
or
.B \-\-wall
flag was given, the daemon will also use
.BR wall (1)
to alert all users of impending doom.
The default is 10.  Use a negative value to disable this feature.
.TP
.B \-q, \-\-quiet
Disables the warnings identified by the 
.B -W
and
.B -w
options.  (The APM BIOS on many machines will provide an audible warning
when power is about to be used up, so extra warnings may not be needed.)
.TP
.B \-?, \-\-help
Prints a usage message and exits.

.SH BUGS
This daemon supports all APM events described in the APM BIOS specification
version 1.2; however it fails to support some of the advanced features
of APM 1.2, such as multiple batteries.
(Multiple batteries are currently treated as if they were just one large one.)
.PP
Estimates of charge and discharge rates and times can be very inaccurate.
.PP
There is no interaction yet with ACPI support as found in newer PC hardware.
.SH FILES
.I /dev/apm_bios
.br
.I /proc/apm
.br
.I /etc/apmd/apmd_proxy
.SH AUTHOR
This program was written by Rik Faith (faith@cs.unc.edu) and may be freely
distributed under the terms of the GNU General Public License.  There is
ABSOLUTELY NO WARRANTY for this program.  The current maintainer is Avery
Pennarun (apenwarr@worldvisions.ca).
.SH "SEE ALSO"
.BR apm "(1), " xapm "(1), " cardctl "(8), " syslogd "(8)"