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