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
  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 v
  42 .Sh DESCRIPTION
  43 .Nm Apmd
  44 monitors the occurrence of the specified Advanced Power Management
  45 .Pq APM
  46 events and, if one of the events occurs, it executes the sequence of
  47 commands corresponding to the event.  Only the events specified in the
  48 configuration file are notified to
  49 .Nm ;
  50 all other events are ignored.  For each event posted by the APM BIOS,
  51 .Nm
  52 invokes the sequence of commands specified in the configuration file.
  53 When
  54 .Nm
  55 is running with monitoring suspend/standby requests,
  56 the kernel will not process those requests.
  57 Therefore, if you wish action to be taken when these events
  58 occur, you need to explicitly configure the appropriate commands or
  59 built-in functions in the configuration file.
  60 .Pp
  61 .Nm Apmd
  62 recognizes the following runtime options:
  63 .Bl -tag -width -f_file
  64 .It Fl d
  65 Starts in debug mode.  This causes
  66 .Nm
  67 to execute in the foreground instead of in daemon mode.
  68 .It Fl f Ar file
  69 Specifies a different configuration file
  70 .Ar file
  71 to be used in place of the default
  72 .Pa /etc/apmd.conf .
  73 .It Fl v
  74 Verbose mode.
  75 .El
  76 .Pp
  77 When
  78 .Nm
  79 starts, it reads the configuration file
  80 .Po
  81 .Pa /etc/apmd.conf
  82 as default
  83 .Pc
  84 and notifies the set of events to be monitored to the APM device driver.
  85 When it terminates, the APM device driver automatically cancels
  86 monitored events.
  87 .Pp
  88 If the
  89 .Nm
  90 process receives a SIGHUP, it will reread its configuration file and
  91 notify the APM device driver of any changes to its configuration.
  92 .Pp
  93 .Nm Apmd
  94 uses the device
  95 .Pa /dev/apmctl
  96 to issue
  97 .Xr ioctl 2
  98 requests for monitoring events and for controlling the APM system.
  99 This device file is opened exclusively, so only a single
 100 .Nm
 101 process can be running at any time.
 102 .Pp
 103 When
 104 .Nm
 105 receives an APM event, it forks a child process to execute the
 106 commands specified in the configuration file and then continues
 107 listening for more events.  The child process executes the commands
 108 specified, one at a time and in the order that they are listed.
 109 .Pp
 110 While
 111 .Nm
 112 is processing the command list for SUSPEND/STANDBY requests, the APM kernel
 113 device driver issues notifications to APM BIOS once per second so that the
 114 BIOS knows that there are still some commands pending, and that it should not
 115 complete the request just yet.
 116 .Pp
 117 The
 118 .Nm
 119 daemon creates the file
 120 .Pa /var/run/apmd.pid ,
 121 and stores its process
 122 id there.
 123 This can be used to kill or reconfigure
 124 .Nm .
 125 .Sh CONFIGURATION FILE
 126 The structure of the
 127 .Nm
 128 configuration file is quite simple.  For example:
 129 .Pp
 130 .Bd -literal
 131 apm_event SUSPENDREQ {
 132        exec "sync && sync && sync";
 133        exec "sleep 1";
 134        exec "zzz";
 135 }
 136 .Ed
 137 .Pp
 138 will cause
 139 .Nm
 140 to receive the APM event
 141 .Ql SUSPENDREQ
 142 (which may be posted by an LCD close), run the
 143 .Ql sync
 144 command 3 times and wait for a while, then execute
 145 .Nm zzz ( Ns Nm apm Fl z )
 146 to put the system in the suspend state.
 147 .Pp
 148 .Bl -bullet
 149 .It
 150 The  apm_event keyword
 151 .Bd -ragged -offset indent
 152 .Ql apm_event
 153 is the keyword which indicates the start of configuration for
 154 each events.
 155 .Ed
 156 .It
 157 APM events
 158 .Bd -ragged -offset indent
 159 If you wish to execute the same commands for different events, the
 160 event names should be delimited by a comma.  The following are
 161 valid event names:
 162 .Bl -item
 163 .It
 164 - Events ignored by the kernel if
 165 .Nm
 166 is running:
 167 .Pp
 168 .Bl -tag -width USERSUSPENDREQ -compact -offset indent
 169 .It STANDBYREQ
 170 .It USERSTANDBYREQ
 171 .It SUSPENDREQ
 172 should include sync in the command list,
 173 .It USERSUSPENDREQ
 174 should include sync in the command list,
 175 .It BATTERYLOW
 176 only zzz should be specified in the command list.
 177 .El
 178 .It
 179 - Events passed to
 180 .Nm
 181 after kernel handling:
 182 .Pp
 183 .Bl -tag -width USERSUSPENDREQ -compact -offset indent
 184 .It NORMRESUME
 185 .It CRITRESUME
 186 .It STANDBYRESUME
 187 .It POWERSTATECHANGE
 188 .It UPDATETIME
 189 .It CAPABILITIESCHANGE
 190 .El
 191 .Pp
 192 Other events will not be sent to
 193 .Nm .
 194 .El
 195 .Ed
 196 .It
 197 command line syntax
 198 .Bd -ragged -offset indent
 199 In the example above, the three lines begining with
 200 .Ql exec
 201 are commands for the event.
 202 Each line should be terminated with a semicolon.
 203 The command list for the event should be enclosed by
 204 .Ql {
 205 and
 206 .Ql } .
 207 .Nm
 208 uses
 209 .Pa /bin/sh
 210 for double-quotation enclosed command execution, just as with
 211 .Xr system 3 .
 212 Each command is executed in order until the end of
 213 the list is reached or a command finishes with a non-zero status code.
 214 .Nm
 215 will report any failed command's status code via
 216 .Xr syslog 3
 217 and will then reject the request event posted by the APM BIOS.
 218 .Ed
 219 .It
 220 Built-in functions
 221 .Bd -ragged -offset indent
 222 You can also specify
 223 .Nm
 224 built-in functions instead of command lines.
 225 A built-in function name should be terminated with a semicolon,
 226 just as with a command line.
 227 The following built-in functions are currently supported:
 228 .Bl -item
 229 .It
 230 - reject:
 231 .Bd -ragged -offset indent
 232 Reject last request posted by APM BIOS.  This can be used to reject
 233 a SUSPEND request when the LCD is closed and put the system in a
 234 STANDBY state instead.
 235 .Ed
 236 .El
 237 .Ed
 238 .El
 239 .Sh EXAMPLES
 240 Sample configuration commands include:
 241 .Bd -literal
 242 apm_event SUSPENDREQ {
 243         exec "/etc/rc.suspend";
 244 }
 245
 246 apm_event USERSUSPENDREQ {
 247         exec "sync && sync && sync";
 248         exec "sleep 1";
 249         exec "apm -z";
 250 }
 251
 252 apm_event NORMRESUME, STANDBYRESUME {
 253         exec "/etc/rc.resume";
 254 }
 255
 256 # resume event configuration for serial mouse users by
 257 # reinitializing a moused(8) connected to a serial port.
 258 #
 259 #apm_event NORMRESUME {
 260 #       exec "kill -HUP `cat /var/run/moused.pid`";
 261 #}
 262 #
 263 # suspend request event configuration for ATA HDD users:
 264 # execute standby instead of suspend.
 265 #
 266 #apm_event SUSPENDREQ {
 267 #       reject;
 268 #       exec "sync && sync && sync";
 269 #       exec "sleep 1";
 270 #       exec "apm -Z";
 271 #}
 272 .Ed
 273 .Sh FILES
 274 .Bl -tag -width /etc/apmd.conf -compact
 275 .It Pa /etc/apmd.conf
 276 .It Pa /dev/apmctl
 277 .It Pa /var/run/apmd.pid
 278 .El
 279 .Sh SEE ALSO
 280 .Xr apm 4 ,
 281 .Xr apm 8
 282 .Sh AUTHORS
 283 .An Mitsuru IWASAKI Aq iwasaki@FreeBSD.org
 284 .An KOIE Hidetaka Aq koie@suri.co.jp
 285 .Pp
 286 Some contributions made by
 287 .An Warner Losh Aq imp@FreeBSD.org ,
 288 .An Hiroshi Yamashita Aq bluemoon@msj.biglobe.ne.jp ,
 289 .An Yoshihiko SARUMARU Aq mistral@imasy.or.jp ,
 290 .An Norihiro Kumagai Aq kuma@nk.rim.or.jp ,
 291 .An NAKAGAWA Yoshihisa Aq nakagawa@jp.FreeBSD.org ,
 292 and
 293 .An Nick Hilliard Aq nick@foobar.org .
 294 .Sh HISTORY
 295 The
 296 .Nm
 297 command appeared in
 298 .Fx 3.3 .