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