usr.sbin/apmd/apmd.8

   1 .\" Copyright (c) 1999 Mitsuru IWASAKI <iwasaki@FreeBSD.org>
   2 .\" Copyright (c) 1999 KOIE Hidetaka <koie@suri.co.jp>
   3 .\" Copyright (c) 1999 Yoshihiko SARUMARU Aq <mistral@imasy.or.jp>
   4 .\" Copyright (c) 1999 Norihiro Kumagai <kuma@nk.rim.or.jp>
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)apmd.8      1.1 (FreeBSD) 6/28/99
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd June 28, 1999
  32 .Dt APMD 8 i386
  33 .Os
  34 .Sh NAME
  35 .Nm apmd
  36 .Nd Advanced Power Management monitor daemon
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Fl d
  40 .Op Fl f file
  41 .Op Fl s
  42 .Op Fl v
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 utility
  47 monitors the occurrence of the specified Advanced Power Management
  48 .Pq Tn APM
  49 events and, if one of the events occurs, it executes the sequence of
  50 commands corresponding to the event.
  51 Only the events specified in the
  52 configuration file are notified to
  53 .Nm ;
  54 all other events are ignored.
  55 For each event posted by the APM BIOS,
  56 .Nm
  57 invokes the sequence of commands specified in the configuration file.
  58 When
  59 .Nm
  60 is running with monitoring suspend/standby requests,
  61 the kernel will not process those requests.
  62 Therefore, if you wish action to be taken when these events
  63 occur, you need to explicitly configure the appropriate commands or
  64 built-in functions in the configuration file.
  65 .Pp
  66 The
  67 .Nm
  68 utility recognizes the following runtime options:
  69 .Bl -tag -width -f_file
  70 .It Fl d
  71 Starts in debug mode.
  72 This causes
  73 .Nm
  74 to execute in the foreground instead of in daemon mode.
  75 .It Fl f Ar file
  76 Specifies a different configuration file
  77 .Ar file
  78 to be used in place of the default
  79 .Pa /etc/apmd.conf .
  80 .It Fl s
  81 Causes
  82 .Nm
  83 to simulate a POWERSTATECHANGE event when a power state change is detected
  84 (AC_POWER_STATE) but the bios of the laptop does not report it.
  85 This enables you to do things like dimming the LCD backlight when you unplug
  86 the power cord.
  87 .It Fl v
  88 Verbose mode.
  89 .El
  90 .Pp
  91 When
  92 .Nm
  93 starts, it reads the configuration file
  94 .Pa ( /etc/apmd.conf
  95 as default)
  96 and notifies the set of events to be monitored to the APM device driver.
  97 When it terminates, the APM device driver automatically cancels
  98 monitored events.
  99 .Pp
 100 If the
 101 .Nm
 102 process receives a
 103 .Dv SIGHUP ,
 104 it will reread its configuration file and
 105 notify the APM device driver of any changes to its configuration.
 106 .Pp
 107 The
 108 .Nm
 109 utility uses the device
 110 .Pa /dev/apmctl
 111 to issue
 112 .Xr ioctl 2
 113 requests for monitoring events and for controlling the APM system.
 114 This device file is opened exclusively, so only a single
 115 .Nm
 116 process can be running at any time.
 117 .Pp
 118 When
 119 .Nm
 120 receives an APM event, it forks a child process to execute the
 121 commands specified in the configuration file and then continues
 122 listening for more events.
 123 The child process executes the commands
 124 specified, one at a time and in the order that they are listed.
 125 .Pp
 126 While
 127 .Nm
 128 is processing the command list for SUSPEND/STANDBY requests, the APM kernel
 129 device driver issues notifications to APM BIOS once per second so that the
 130 BIOS knows that there are still some commands pending, and that it should not
 131 complete the request just yet.
 132 .Pp
 133 The
 134 .Nm
 135 utility creates the file
 136 .Pa /var/run/apmd.pid ,
 137 and stores its process
 138 id there.
 139 This can be used to kill or reconfigure
 140 .Nm .
 141 .Sh CONFIGURATION FILE
 142 The structure of the
 143 .Nm
 144 configuration file is quite simple.
 145 For example:
 146 .Pp
 147 .Bd -literal
 148 apm_event SUSPENDREQ {
 149        exec "sync && sync && sync";
 150        exec "sleep 1";
 151        exec "zzz";
 152 }
 153 .Ed
 154 .Pp
 155 will cause
 156 .Nm
 157 to receive the APM event
 158 .Ql SUSPENDREQ
 159 (which may be posted by an LCD close), run the
 160 .Ql sync
 161 command 3 times and wait for a while, then execute
 162 .Nm zzz ( Ns Nm apm Fl z )
 163 to put the system in the suspend state.
 164 .Pp
 165 .Bl -bullet
 166 .It
 167 The apm_event keyword
 168 .Bd -ragged -offset indent
 169 .Ql apm_event
 170 is the keyword which indicates the start of configuration for
 171 each event.
 172 .Ed
 173 .It
 174 APM events
 175 .Bd -ragged -offset indent
 176 If you wish to execute the same commands for different events, the
 177 event names should be delimited by a comma.
 178 The following are
 179 valid event names:
 180 .Bl -item
 181 .It
 182 - Events ignored by the kernel if
 183 .Nm
 184 is running:
 185 .Pp
 186 .Bl -tag -width USERSUSPENDREQ -compact -offset indent
 187 .It STANDBYREQ
 188 .It USERSTANDBYREQ
 189 .It SUSPENDREQ
 190 should include sync in the command list,
 191 .It USERSUSPENDREQ
 192 should include sync in the command list,
 193 .It BATTERYLOW
 194 only zzz should be specified in the command list.
 195 .El
 196 .It
 197 - Events passed to
 198 .Nm
 199 after kernel handling:
 200 .Pp
 201 .Bl -tag -width USERSUSPENDREQ -compact -offset indent
 202 .It NORMRESUME
 203 .It CRITRESUME
 204 .It STANDBYRESUME
 205 .It POWERSTATECHANGE
 206 .It UPDATETIME
 207 .It CAPABILITIESCHANGE
 208 .El
 209 .Pp
 210 Other events will not be sent to
 211 .Nm .
 212 .El
 213 .Ed
 214 .It
 215 command line syntax
 216 .Bd -ragged -offset indent
 217 In the example above, the three lines beginning with
 218 .Ql exec
 219 are commands for the event.
 220 Each line should be terminated with a semicolon.
 221 The command list for the event should be enclosed by
 222 .Ql {
 223 and
 224 .Ql } .
 225 The
 226 .Nm
 227 utility uses
 228 .Pa /bin/sh
 229 for double-quotation enclosed command execution, just as with
 230 .Xr system 3 .
 231 Each command is executed in order until the end of
 232 the list is reached or a command finishes with a non-zero status code.
 233 The
 234 .Nm
 235 utility will report any failed command's status code via
 236 .Xr syslog 3
 237 and will then reject the request event posted by the APM BIOS.
 238 .Ed
 239 .It
 240 Built-in functions
 241 .Bd -ragged -offset indent
 242 You can also specify
 243 .Nm
 244 built-in functions instead of command lines.
 245 A built-in function name should be terminated with a semicolon,
 246 just as with a command line.
 247 The following built-in functions are currently supported:
 248 .Bl -item
 249 .It
 250 - reject:
 251 .Bd -ragged -offset indent
 252 Reject last request posted by APM BIOS.
 253 This can be used to reject
 254 a SUSPEND request when the LCD is closed and put the system in a
 255 STANDBY state instead.
 256 .Ed
 257 .El
 258 .Ed
 259 .El
 260 .Sh FILES
 261 .Bl -tag -width /etc/apmd.conf -compact
 262 .It Pa /etc/apmd.conf
 263 .It Pa /dev/apmctl
 264 .It Pa /var/run/apmd.pid
 265 .El
 266 .Sh EXAMPLES
 267 Sample configuration commands include:
 268 .Bd -literal
 269 apm_event SUSPENDREQ {
 270         exec "/etc/rc.suspend apm suspend";
 271 }
 272
 273 apm_event USERSUSPENDREQ {
 274         exec "sync && sync && sync";
 275         exec "sleep 1";
 276         exec "apm -z";
 277 }
 278
 279 apm_event NORMRESUME {
 280         exec "/etc/rc.resume apm suspend";
 281 }
 282
 283 apm_event STANDBYRESUME {
 284         exec "/etc/rc.resume apm standby";
 285 }
 286
 287 # resume event configuration for serial mouse users by
 288 # reinitializing a moused(8) connected to a serial port.
 289 #
 290 #apm_event NORMRESUME {
 291 #       exec "kill -HUP `cat /var/run/moused.pid`";
 292 #}
 293 #
 294 # suspend request event configuration for ATA HDD users:
 295 # execute standby instead of suspend.
 296 #
 297 #apm_event SUSPENDREQ {
 298 #       reject;
 299 #       exec "sync && sync && sync";
 300 #       exec "sleep 1";
 301 #       exec "apm -Z";
 302 #}
 303 .Ed
 304 .Sh SEE ALSO
 305 .Xr apm 4 ,
 306 .Xr apm 8
 307 .Sh HISTORY
 308 The
 309 .Nm
 310 utility appeared in
 311 .Fx 3.3 .
 312 .Sh AUTHORS
 313 .An Mitsuru IWASAKI Aq iwasaki@FreeBSD.org
 314 .An KOIE Hidetaka Aq koie@suri.co.jp
 315 .Pp
 316 .An -nosplit
 317 Some contributions made by
 318 .An Warner Losh Aq imp@FreeBSD.org ,
 319 .An Hiroshi Yamashita Aq bluemoon@msj.biglobe.ne.jp ,
 320 .An Yoshihiko SARUMARU Aq mistral@imasy.or.jp ,
 321 .An Norihiro Kumagai Aq kuma@nk.rim.or.jp ,
 322 .An NAKAGAWA Yoshihisa Aq nakagawa@jp.FreeBSD.org ,
 323 and
 324 .An Nick Hilliard Aq nick@foobar.org .