| blob | 94640046bb7445041747c2851d74608d09564969 |
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
41 The
42 .Nm
43 utility
44 monitors the occurrence of the specified Advanced Power Management
45 .Pq Tn APM
46 events and, if one of the events occurs, it executes the sequence of
47 commands corresponding to the event.
48 Only the events specified in the
49 configuration file are notified to
50 .Nm ;
51 all other events are ignored.
52 For each event posted by the APM BIOS,
53 .Nm
54 invokes the sequence of commands specified in the configuration file.
55 When
56 .Nm
57 is running with monitoring suspend/standby requests,
58 the kernel will not process those requests.
59 Therefore, if you wish action to be taken when these events
60 occur, you need to explicitly configure the appropriate commands or
61 built-in functions in the configuration file.
62 .Pp
63 The
64 .Nm
65 utility recognizes the following runtime options:
66 .Bl -tag -width f_file
67 .It Fl d
68 Starts in debug mode.
69 This causes
70 .Nm
71 to execute in the foreground instead of in daemon mode.
72 .It Fl f Ar file
73 Specifies a different configuration file
74 .Ar file
75 to be used in place of the default
76 .Pa /etc/apmd.conf .
77 .It Fl s
78 Causes
79 .Nm
80 to 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.
82 This enables you to do things like dimming the LCD backlight when you unplug
83 the power cord.
84 .It Fl v
85 Verbose mode.
86 .El
87 .Pp
88 When
89 .Nm
90 starts, it reads the configuration file
91 .Pa ( /etc/apmd.conf
92 as default)
93 and notifies the set of events to be monitored to the APM device driver.
94 When it terminates, the APM device driver automatically cancels
95 monitored events.
96 .Pp
97 If the
98 .Nm
99 process receives a
100 .Dv SIGHUP ,
101 it will reread its configuration file and
102 notify the APM device driver of any changes to its configuration.
103 .Pp
104 The
105 .Nm
106 utility uses the device
107 .Pa /dev/apmctl
108 to issue
109 .Xr ioctl 2
110 requests for monitoring events and for controlling the APM system.
111 This device file is opened exclusively, so only a single
112 .Nm
113 process can be running at any time.
114 .Pp
115 When
116 .Nm
117 receives an APM event, it forks a child process to execute the
118 commands specified in the configuration file and then continues
119 listening for more events.
120 The child process executes the commands
121 specified, one at a time and in the order that they are listed.
122 .Pp
123 While
124 .Nm
125 is processing the command list for SUSPEND/STANDBY requests, the APM kernel
126 device driver issues notifications to APM BIOS once per second so that the
127 BIOS knows that there are still some commands pending, and that it should not
128 complete the request just yet.
129 .Pp
130 The
131 .Nm
132 utility creates the file
133 .Pa /var/run/apmd.pid ,
134 and stores its process
135 id there.
136 This can be used to kill or reconfigure
137 .Nm .
138 .Sh CONFIGURATION FILE
139 The structure of the
140 .Nm
141 configuration file is quite simple.
142 For example:
143 .Bd -literal
144 apm_event SUSPENDREQ {
145 exec "sync && sync && sync";
146 exec "sleep 1";
147 exec "zzz";
148 }
149 .Ed
150 .Pp
151 will cause
152 .Nm
153 to receive the APM event
154 .Ql SUSPENDREQ
155 (which may be posted by an LCD close), run the
156 .Ql sync
157 command 3 times and wait for a while, then execute
158 .Nm zzz ( Ns Nm apm Fl z )
159 to put the system in the suspend state.
160 .Bl -bullet
161 .It
162 The apm_event keyword
163 .Bd -ragged -offset indent
164 .Ql apm_event
165 is the keyword which indicates the start of configuration for
166 each event.
167 .Ed
168 .It
169 APM events
170 .Bd -ragged -offset indent
171 If you wish to execute the same commands for different events, the
172 event names should be delimited by a comma.
173 The following are
174 valid event names:
175 .Bl -item
176 .It
177 - Events ignored by the kernel if
178 .Nm
179 is running:
180 .Pp
181 .Bl -tag -width USERSUSPENDREQ -compact -offset indent
182 .It STANDBYREQ
183 .It USERSTANDBYREQ
184 .It SUSPENDREQ
185 should include sync in the command list,
186 .It USERSUSPENDREQ
187 should include sync in the command list,
188 .It BATTERYLOW
189 only zzz should be specified in the command list.
190 .El
191 .It
192 - Events passed to
193 .Nm
194 after 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
205 Other events will not be sent to
206 .Nm .
207 .El
208 .Ed
209 .It
210 command line syntax
211 .Bd -ragged -offset indent
212 In the example above, the three lines beginning with
213 .Ql exec
214 are commands for the event.
215 Each line should be terminated with a semicolon.
216 The command list for the event should be enclosed by
217 .Ql {
218 and
219 .Ql } .
220 The
221 .Nm
222 utility uses
223 .Pa /bin/sh
224 for double-quotation enclosed command execution, just as with
225 .Xr system 3 .
226 Each command is executed in order until the end of
227 the list is reached or a command finishes with a non-zero status code.
228 The
229 .Nm
230 utility will report any failed command's status code via
231 .Xr syslog 3
232 and will then reject the request event posted by the APM BIOS.
233 .Ed
234 .It
235 Built-in functions
236 .Bd -ragged -offset indent
237 You can also specify
238 .Nm
239 built-in functions instead of command lines.
240 A built-in function name should be terminated with a semicolon,
241 just as with a command line.
242 The following built-in functions are currently supported:
243 .Bl -item
244 .It
245 .Bl -tag -width ".It - reject"
246 .It - reject
247 Reject last request posted by APM BIOS.
248 This can be used to reject
249 a SUSPEND request when the LCD is closed and put the system in a
250 STANDBY 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
262 Sample configuration commands include:
263 .Bd -literal
264 apm_event SUSPENDREQ {
265 exec "/etc/rc.suspend apm suspend";
266 }
268 apm_event USERSUSPENDREQ {
269 exec "sync && sync && sync";
270 exec "sleep 1";
271 exec "apm -z";
272 }
274 apm_event NORMRESUME {
275 exec "/etc/rc.resume apm suspend";
276 }
278 apm_event STANDBYRESUME {
279 exec "/etc/rc.resume apm standby";
280 }
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
303 The
304 .Nm
305 utility 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
312 Some 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 ,
318 and
319 .An Nick Hilliard Aq Mt nick@foobar.org .