.\"	$OpenBSD: apmd.8,v 1.36 2007/05/31 19:20:22 jmc Exp $
.\"
.\" Copyright (c) 1995 John T. Kohl
.\" All rights reserved.
.\"
.\" 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. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR `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 AUTHOR 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 $Mdocdate: May 31 2007 $
.Dt APMD 8
.Os
.Sh NAME
.Nm apmd
.Nd Advanced Power Management monitor daemon
.Sh SYNOPSIS
.Nm apmd
.Op Fl AaCdeHLmps
.Op Fl f Ar devname
.Op Fl S Ar sockname
.Op Fl t Ar seconds
.Sh DESCRIPTION
.Nm
monitors the advanced power management (APM) pseudo-device, acting on
signaled events and upon user requests as sent by the
.Xr apm 8
program.
For suspend and standby request events delivered by the BIOS, or via
.Xr apm 8 ,
.Nm
runs the appropriate configuration program (if one exists),
syncs the buffer cache to disk and initiates the requested state.
When resuming after suspend or standby,
.Nm
runs the appropriate configuration program (if one exists).
For power status change events,
.Nm
fetches the current status and reports it via
.Xr syslog 3
with logging facility
.Dv LOG_DAEMON .
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl A
Start
.Nm
in automatic performance adjustment mode.
In this mode, when CPU idle time falls below 10%,
or if the AC power is connected and the battery is more than 15% charged,
.Nm
raises
.Va hw.setperf
as much as possible.
Otherwise, when the CPU idle time
is above 30% and the system is running on battery power,
.Nm
lowers
.Va hw.setperf
as much as possible to reduce power consumption.
.It Fl a
BIOS-initiated suspend or standby requests are
ignored if the system is connected to line current and not running from
batteries (user requests are still honored).
.It Fl C
Start
.Nm
in cool running performance adjustment mode.
In this mode, when CPU idle time falls below
10%,
.Nm
raises
.Va hw.setperf
as much as necessary.
Otherwise, when idle time is above 30%
.Nm
reduces
.Va hw.setperf
as much as possible to reduce heat, noise, and power consumption.
.It Fl d
.Nm
enters debug mode, logging to facility
.Dv LOG_LOCAL1 ,
and stays in the foreground on the controlling terminal.
.It Fl e
Re-enable APM driver power status messages.
.Nm
exits immediately after setting this option.
Use of this flag unconditionally enables power status messages.
.It Fl f Ar devname
Specify an alternate device file name,
.Ar devname .
.It Fl H
Start
.Nm
in manual performance adjustment mode, initialising
.Va hw.setperf
to 100.
.It Fl L
Start
.Nm
in manual performance adjustment mode, initialising
.Va hw.setperf
to 0.
.It Fl m
Do not disable power status messages issued by the APM driver.
In normal operation these status messages are disabled as they are
the same as the information collected by this daemon and reported via
.Xr syslog 3 .
.It Fl p
Re-enable APM driver power status messages.
.Nm
exits immediately after setting this option.
Use of this flag causes power status messages to be displayed only when the
battery life expectancy changes.
This minimizes message output
for those devices that are constantly updating the estimated time
remaining based upon current processor load.
However, in no case
will power status messages be displayed until the battery life
goes below the percentage in the
.Xr sysctl 8
state variable
.Va machdep.apmwarn .
Setting
.Va machdep.apmwarn
to zero disables all warnings.
.It Fl S Ar sockname
Specify an alternate socket name,
.Ar sockname .
The socket is protected to mode 0660, UID 0, GID 0; this protects access
to suspend requests to authorized users only.
.It Fl s
Current battery statistics are reported via
.Xr syslog 3
and
.Nm
exits without monitoring the APM status.
.It Fl t Ar seconds
.Nm
periodically polls the APM driver for the current power state.
If the battery charge level changes substantially or the external power
status changes, the new status is logged.
The polling rate defaults to
once per 10 minutes, but may be specified using the
.Fl t
command-line flag.
.El
.Pp
When a client requests a suspend or stand-by state,
.Nm
does not wait for positive confirmation that the requested
state has been entered before replying to the client; to do so would mean
the client does not get a reply until the system resumes from its sleep state.
Rather,
.Nm
replies with the intended state to the client and then places the system
in the requested state after running the configuration script and
flushing the buffer cache.
.Pp
Actions can be configured for the following five transitions:
.Cm suspend ,
.Cm standby ,
.Cm resume ,
.Cm powerup
and
.Cm powerdown .
The suspend and standby actions are run prior to
.Nm
performing any other actions (such as disk syncs) and entering the new
state.
The resume program is run after resuming from a stand-by or
suspended state.
The powerup and powerdown programs are run after the power status (AC
connected or not) changes, as well as after a resume (if the power
status changed in the mean time).
.Sh FILES
.Bl -tag -width "/etc/apm/powerdownXX" -compact
.It /dev/apmctl
Default device used to control the APM kernel driver.
.Pp
.It /etc/apm/suspend
.It /etc/apm/standby
.It /etc/apm/resume
.It /etc/apm/powerup
.It /etc/apm/powerdown
These files contain the host's customized actions.
Each file must be an executable binary or shell script suitable
for execution by the
.Xr execve 2
function.
If you wish to have the same program or script control all transitions,
it may determine which transition is in progress by examining its
.Va argv[0] ,
which is set to one of
.Ar suspend ,
.Ar standby ,
.Ar resume ,
.Ar powerup ,
or
.Ar powerdown .
.Pp
.It /var/run/apmdev
Default UNIX-domain socket used for communication with
.Xr apm 8 .
.El
.Sh SEE ALSO
.Xr execve 2 ,
.Xr syslog 3 ,
.Xr apm 4 ,
.Xr apm 8 ,
.Xr sysctl 8 ,
.Xr syslogd 8
.Pp
Advanced Power Management (APM) BIOS Interface Specification
(revision 1.2),
Intel Corporation and Microsoft Corporation.
.Sh HISTORY
The
.Nm
command first appeared in
.Nx 1.3 .
.Ox
support was added in
.Ox 1.2 .