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