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