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