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