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