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