usr.sbin/apmd/apmd.8

   1 .\"     $NetBSD: apmd.8,v 1.19 2008/04/30 13:11:01 martin Exp $
   2 .\"
   3 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by John Kohl.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd May 16, 2004
  31 .Dt APMD 8
  32 .Os
  33 .Sh NAME
  34 .Nm apmd
  35 .Nd Advanced Power Management monitor daemon
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Op Fl adlqsv
  39 .Bk -words
  40 .Op Fl t Ar rate
  41 .Ek
  42 .Bk -words
  43 .Op Fl S Ar sockname
  44 .Ek
  45 .Bk -words
  46 .Op Fl m Ar sockmode
  47 .Ek
  48 .Bk -words
  49 .Op Fl o Ar sockowner:sockgroup
  50 .Ek
  51 .Bk -words
  52 .Op Fl f Ar devname
  53 .Ek
  54 .Sh DESCRIPTION
  55 .Nm
  56 monitors the advanced power management (APM) pseudo-device, acting on
  57 signaled events and upon user requests as sent by the
  58 .Xr apm 8
  59 utility.
  60 The
  61 .Nm
  62 daemon is only installed on supported platforms.
  63 .Pp
  64 For suspend and standby request events delivered by the BIOS, or via
  65 .Xr apm 8 ,
  66 .Nm
  67 runs the appropriate configuration program (if one exists),
  68 syncs the buffer cache to disk and initiates the requested mode.
  69 When resuming after suspend or standby,
  70 .Nm
  71 runs the appropriate configuration utility (if one exists).
  72 For power status change events,
  73 .Nm
  74 fetches the current status and reports it via
  75 .Xr syslog 3
  76 with logging facility
  77 .Dv LOG_DAEMON .
  78 .Pp
  79 .Nm
  80 announces the transition to standby mode with a single high tone on the
  81 speaker (using the
  82 .Pa /dev/speaker
  83 device).
  84 Suspends are announced with two high tones.
  85 .Pp
  86 .Nm
  87 periodically polls the APM driver for the current power state.
  88 If the battery charge level changes substantially or the external power
  89 status changes, the new status is logged.
  90 The polling rate defaults to
  91 once per 10 minutes, but may be specified using the
  92 .Fl t
  93 command-line flag.
  94 .Pp
  95 .Nm
  96 supports the following options:
  97 .Bl -tag -width Fl
  98 .It Fl a
  99 Any BIOS-initiated suspend or standby requests are
 100 ignored if the system is connected to line current and not running from
 101 batteries (user requests are still honored).
 102 .It Fl d
 103 Enter debug mode, log to facility
 104 .Dv LOG_LOCAL1
 105 and stay in the foreground on the controlling terminal.
 106 .It Fl f Ar devname
 107 Specify an alternate device file name.
 108 .It Fl l
 109 A low-battery event causes a suspend request to occur.
 110 .It Fl m Ar sockmode
 111 Use
 112 .Ar sockmode
 113 instead of
 114 .Sq 0660
 115 for the mode of
 116 .Pa /var/run/apmdev .
 117 .It Fl o Ar sockowner:sockgroup
 118 Use
 119 .Ar sockowner:sockgroup
 120 instead of
 121 .Sq `0:0'
 122 for the owner/group of
 123 .Pa /var/run/apmdev .
 124 .It Fl q
 125 Do not announce suspend and standby requests on the speaker.
 126 .It Fl s
 127 The current battery statistics are reported via
 128 .Xr syslog 3
 129 and exit without monitoring the APM status.
 130 .It Fl S Ar sockname
 131 Specify an alternate socket name (used by
 132 .Xr apm 8
 133 to communicate with
 134 .Nm ) .
 135 .It Fl t Ar rate
 136 Change the polling rate from 600 seconds to
 137 .Ar rate
 138 seconds.
 139 .It Fl v
 140 Periodically log the power status via
 141 .Xr syslog 3 .
 142 .El
 143 .Pp
 144 When a client requests a suspend or stand-by mode,
 145 .Nm
 146 does not wait for positive confirmation that the requested
 147 mode has been entered before replying to the client; to do so would mean
 148 the client does not get a reply until the system resumes from its sleep state.
 149 Rather,
 150 .Nm
 151 replies with the intended state to the client and then places the system
 152 in the requested mode after running the configuration script and
 153 flushing the buffer cache.
 154 .Pp
 155 Actions can be configured for the five transitions:
 156 .Cm suspend ,
 157 .Cm standby ,
 158 .Cm resume ,
 159 .Cm line
 160 or
 161 .Cm battery .
 162 The suspend and standby actions are run prior to
 163 .Nm
 164 performing any other actions (such as disk syncs) and entering the new
 165 mode.
 166 The resume program is run after resuming from a stand-by or suspended state.
 167 .Pp
 168 The line and battery actions are run after switching power sources to
 169 AC (line) or battery, respectively.
 170 The appropriate line or battery action
 171 is also run upon the startup of apmd based on the current power source.
 172 .Sh FILES
 173 .Bl -tag -width /etc/apm/suspend -compact
 174 .It Pa /etc/apm/suspend
 175 .It Pa /etc/apm/standby
 176 .It Pa /etc/apm/resume
 177 .It Pa /etc/apm/line
 178 .It Pa /etc/apm/battery
 179 Contain the host's customized actions.
 180 Each file must be an executable binary or shell script suitable
 181 for execution by the
 182 .Xr execve 2
 183 function.
 184 If you wish to have the same program or script control all transitions, it
 185 may determine which transition is in progress by examining its
 186 .Va argv[0]
 187 which is set to one of
 188 .Ar suspend ,
 189 .Ar standby ,
 190 .Ar resume ,
 191 .Ar line
 192 or
 193 .Ar battery .
 194 See
 195 .Pa /usr/share/examples/apm/script
 196 for such an example script.
 197 .Pp
 198 .It Pa /var/run/apmdev
 199 The default UNIX-domain socket used for communication with
 200 .Xr apm 8 .
 201 The socket is protected by default to mode 0660, UID 0, GID 0.
 202 .Pp
 203 .It Pa /dev/apmctl
 204 The default device used to control the APM kernel driver.
 205 .El
 206 .Sh SEE ALSO
 207 .Xr execve 2 ,
 208 .Xr syslog 3 ,
 209 .Xr apm 4 ,
 210 .Xr speaker 4 ,
 211 .Xr apm 8 ,
 212 .Xr syslogd 8
 213 .Sh REFERENCES
 214 Advanced Power Management (APM) BIOS Interface Specification (revision
 215 1.1), Intel Corporation and Microsoft Corporation.
 216 .Sh HISTORY
 217 The
 218 .Nm
 219 command appeared in
 220 .Nx 1.3 .