NetBSD/usr.sbin/apmd/apmd.8

.\"	$NetBSD: apmd.8,v 1.18 2004/05/16 10:54:12 wiz Exp $
.\"
.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by John Kohl.
.\"
.\" 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 May 16, 2004
.Dt APMD 8
.Os
.Sh NAME
.Nm apmd
.Nd Advanced Power Management monitor daemon
.Sh SYNOPSIS
.Nm
.Op Fl adlqsv
.Bk -words
.Op Fl t Ar rate
.Ek
.Bk -words
.Op Fl S Ar sockname
.Ek
.Bk -words
.Op Fl m Ar sockmode
.Ek
.Bk -words
.Op Fl o Ar sockowner:sockgroup
.Ek
.Bk -words
.Op Fl f Ar devname
.Ek
.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
utility.
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 mode.
When resuming after suspend or standby,
.Nm
runs the appropriate configuration utility (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
.Nm
announces the transition to standby mode with a single high tone on the
speaker (using the
.Pa /dev/speaker
device).
Suspends are announced with two high tones.
.Pp
.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.
.Pp
.Nm
supports the following options:
.Bl -tag -width Fl
.It Fl a
Any 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 d
Enter debug mode, log to facility
.Dv LOG_LOCAL1
and stay in the foreground on the controlling terminal.
.It Fl f Ar devname
Specify an alternate device file name.
.It Fl l
A low-battery event causes a suspend request to occur.
.It Fl m Ar sockmode
Use
.Ar sockmode
instead of
.Sq 0660
for the mode of
.Pa /var/run/apmdev .
.It Fl o Ar sockowner:sockgroup
Use
.Ar sockowner:sockgroup
instead of
.Sq `0:0'
for the owner/group of
.Pa /var/run/apmdev .
.It Fl q
Do not announce suspend and standby requests on the speaker.
.It Fl s
The current battery statistics are reported via
.Xr syslog 3
and exit without monitoring the APM status.
.It Fl S Ar sockname
Specify an alternate socket name (used by
.Xr apm 8
to communicate with
.Nm ) .
.It Fl t Ar rate
Change the polling rate from 600 seconds to
.Ar rate
seconds.
.It Fl v
Periodically log the power status via
.Xr syslog 3 .
.El
.Pp
When a client requests a suspend or stand-by mode,
.Nm
does not wait for positive confirmation that the requested
mode 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 mode after running the configuration script and
flushing the buffer cache.
.Pp
Actions can be configured for the five transitions:
.Cm suspend ,
.Cm standby ,
.Cm resume ,
.Cm line
or
.Cm battery .
The suspend and standby actions are run prior to
.Nm
performing any other actions (such as disk syncs) and entering the new
mode.
The resume program is run after resuming from a stand-by or suspended state.
.Pp
The line and battery actions are run after switching power sources to
AC (line) or battery, respectively.
The appropriate line or battery action
is also run upon the startup of apmd based on the current power source.
.Sh FILES
.Bl -tag -width /etc/apm/suspend -compact
.It Pa /etc/apm/suspend
.It Pa /etc/apm/standby
.It Pa /etc/apm/resume
.It Pa /etc/apm/line
.It Pa /etc/apm/battery
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 line
or
.Ar battery .
See
.Pa /usr/share/examples/apm/script
for such an example script.
.Pp
.It Pa /var/run/apmdev
The default UNIX-domain socket used for communication with
.Xr apm 8 .
The socket is protected by default to mode 0660, UID 0, GID 0.
.Pp
.It Pa /dev/apmctl
The default device used to control the APM kernel driver.
.El
.Sh SEE ALSO
.Xr execve 2 ,
.Xr syslog 3 ,
.Xr apm 4 ,
.Xr speaker 4 ,
.Xr apm 8 ,
.Xr syslogd 8
.Sh REFERENCES
Advanced Power Management (APM) BIOS Interface Specification (revision
1.1), Intel Corporation and Microsoft Corporation.
.Sh HISTORY
The
.Nm
command appeared in
.Nx 1.3 .