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 <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.Bd -literal 147apm_event SUSPENDREQ { 148 exec "sync && sync && sync"; 149 exec "sleep 1"; 150 exec "zzz"; 151} 152.Ed 153.Pp 154will cause 155.Nm 156to receive the APM event 157.Ql SUSPENDREQ 158(which may be posted by an LCD close), run the 159.Ql sync 160command 3 times and wait for a while, then execute 161.Nm zzz ( Ns Nm apm Fl z ) 162to put the system in the suspend state. 163.Bl -bullet 164.It 165The apm_event keyword 166.Bd -ragged -offset indent 167.Ql apm_event 168is the keyword which indicates the start of configuration for 169each event. 170.Ed 171.It 172APM events 173.Bd -ragged -offset indent 174If you wish to execute the same commands for different events, the 175event names should be delimited by a comma. 176The following are 177valid event names: 178.Bl -item 179.It 180- Events ignored by the kernel if 181.Nm 182is running: 183.Pp 184.Bl -tag -width USERSUSPENDREQ -compact -offset indent 185.It STANDBYREQ 186.It USERSTANDBYREQ 187.It SUSPENDREQ 188should include sync in the command list, 189.It USERSUSPENDREQ 190should include sync in the command list, 191.It BATTERYLOW 192only zzz should be specified in the command list. 193.El 194.It 195- Events passed to 196.Nm 197after kernel handling: 198.Pp 199.Bl -tag -width USERSUSPENDREQ -compact -offset indent 200.It NORMRESUME 201.It CRITRESUME 202.It STANDBYRESUME 203.It POWERSTATECHANGE 204.It UPDATETIME 205.It CAPABILITIESCHANGE 206.El 207.Pp 208Other events will not be sent to 209.Nm . 210.El 211.Ed 212.It 213command line syntax 214.Bd -ragged -offset indent 215In the example above, the three lines beginning with 216.Ql exec 217are commands for the event. 218Each line should be terminated with a semicolon. 219The command list for the event should be enclosed by 220.Ql { 221and 222.Ql } . 223The 224.Nm 225utility uses 226.Pa /bin/sh 227for double-quotation enclosed command execution, just as with 228.Xr system 3 . 229Each command is executed in order until the end of 230the list is reached or a command finishes with a non-zero status code. 231The 232.Nm 233utility will report any failed command's status code via 234.Xr syslog 3 235and will then reject the request event posted by the APM BIOS. 236.Ed 237.It 238Built-in functions 239.Bd -ragged -offset indent 240You can also specify 241.Nm 242built-in functions instead of command lines. 243A built-in function name should be terminated with a semicolon, 244just as with a command line. 245The following built-in functions are currently supported: 246.Bl -item 247.It 248.Bl -tag -width ".It - reject" 249.It - reject 250Reject last request posted by APM BIOS. 251This can be used to reject 252a SUSPEND request when the LCD is closed and put the system in a 253STANDBY state instead. 254.El 255.El 256.Ed 257.El 258.Sh FILES 259.Bl -tag -width /etc/apmd.conf -compact 260.It Pa /etc/apmd.conf 261.It Pa /dev/apmctl 262.It Pa /var/run/apmd.pid 263.El 264.Sh EXAMPLES 265Sample configuration commands include: 266.Bd -literal 267apm_event SUSPENDREQ { 268 exec "/etc/rc.suspend apm suspend"; 269} 270 271apm_event USERSUSPENDREQ { 272 exec "sync && sync && sync"; 273 exec "sleep 1"; 274 exec "apm -z"; 275} 276 277apm_event NORMRESUME { 278 exec "/etc/rc.resume apm suspend"; 279} 280 281apm_event STANDBYRESUME { 282 exec "/etc/rc.resume apm standby"; 283} 284 285# resume event configuration for serial mouse users by 286# reinitializing a moused(8) connected to a serial port. 287# 288#apm_event NORMRESUME { 289# exec "kill -HUP `cat /var/run/moused.pid`"; 290#} 291# 292# suspend request event configuration for ATA HDD users: 293# execute standby instead of suspend. 294# 295#apm_event SUSPENDREQ { 296# reject; 297# exec "sync && sync && sync"; 298# exec "sleep 1"; 299# exec "apm -Z"; 300#} 301.Ed 302.Sh SEE ALSO 303.Xr apm 4 , 304.Xr apm 8 305.Sh HISTORY 306The 307.Nm 308utility appeared in 309.Fx 3.3 . 310.Sh AUTHORS 311.An Mitsuru IWASAKI Aq Mt iwasaki@FreeBSD.org 312.An KOIE Hidetaka Aq Mt koie@suri.co.jp 313.Pp 314.An -nosplit 315Some contributions made by 316.An Warner Losh Aq Mt imp@FreeBSD.org , 317.An Hiroshi Yamashita Aq Mt bluemoon@msj.biglobe.ne.jp , 318.An Yoshihiko SARUMARU Aq Mt mistral@imasy.or.jp , 319.An Norihiro Kumagai Aq Mt kuma@nk.rim.or.jp , 320.An NAKAGAWA Yoshihisa Aq Mt nakagawa@jp.FreeBSD.org , 321and 322.An Nick Hilliard Aq Mt nick@foobar.org . 323