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