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