summaryrefslogtreecommitdiffstats
path: root/usr.sbin/apmd/apmd.8
blob: 048bf38b0f57b98eec4159d4da0944ccddcb1f5c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
.\" Copyright (c) 1999 Mitsuru IWASAKI <iwasaki@FreeBSD.org>
.\" Copyright (c) 1999 KOIE Hidetaka <koie@suri.co.jp>
.\" Copyright (c) 1999 Yoshihiko SARUMARU Aq <mistral@imasy.or.jp>
.\" Copyright (c) 1999 Norihiro Kumagai <kuma@nk.rim.or.jp>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)apmd.8	1.1 (FreeBSD) 6/28/99
.\" $FreeBSD$
.\"
.Dd June 28, 1999
.Dt APMD 8 i386
.Os
.Sh NAME
.Nm apmd
.Nd Advanced Power Management monitor daemon
.Sh SYNOPSIS
.Nm
.Op Fl d
.Op Fl f file
.Op Fl s
.Op Fl v
.Sh DESCRIPTION
The
.Nm
utility
monitors the occurrence of the specified Advanced Power Management
.Pq Tn APM
events and, if one of the events occurs, it executes the sequence of
commands corresponding to the event.
Only the events specified in the
configuration file are notified to
.Nm ;
all other events are ignored.
For each event posted by the APM BIOS,
.Nm
invokes the sequence of commands specified in the configuration file.
When
.Nm
is running with monitoring suspend/standby requests,
the kernel will not process those requests.
Therefore, if you wish action to be taken when these events
occur, you need to explicitly configure the appropriate commands or
built-in functions in the configuration file.
.Pp
The
.Nm
utility recognizes the following runtime options:
.Bl -tag -width -f_file
.It Fl d
Starts in debug mode.
This causes
.Nm
to execute in the foreground instead of in daemon mode.
.It Fl f Ar file
Specifies a different configuration file
.Ar file
to be used in place of the default
.Pa /etc/apmd.conf .
.It Fl s
Causes
.Nm
to simulate a POWERSTATECHANGE event when a power state change is detected
(AC_POWER_STATE) but the bios of the laptop doesn't report it.
This enables you to do things like dimming the LCD backlight when you unplug
the power cord.
.It Fl v
Verbose mode.
.El
.Pp
When
.Nm
starts, it reads the configuration file
.Pa ( /etc/apmd.conf
as default)
and notifies the set of events to be monitored to the APM device driver.
When it terminates, the APM device driver automatically cancels
monitored events.
.Pp
If the
.Nm
process receives a SIGHUP, it will reread its configuration file and
notify the APM device driver of any changes to its configuration.
.Pp
The
.Nm
utility uses the device
.Pa /dev/apmctl
to issue
.Xr ioctl 2
requests for monitoring events and for controlling the APM system.
This device file is opened exclusively, so only a single
.Nm
process can be running at any time.
.Pp
When
.Nm
receives an APM event, it forks a child process to execute the
commands specified in the configuration file and then continues
listening for more events.
The child process executes the commands
specified, one at a time and in the order that they are listed.
.Pp
While
.Nm
is processing the command list for SUSPEND/STANDBY requests, the APM kernel
device driver issues notifications to APM BIOS once per second so that the
BIOS knows that there are still some commands pending, and that it should not
complete the request just yet.
.Pp
The
.Nm
utility creates the file
.Pa /var/run/apmd.pid ,
and stores its process
id there.
This can be used to kill or reconfigure
.Nm .
.Sh CONFIGURATION FILE
The structure of the
.Nm
configuration file is quite simple.
For example:
.Pp
.Bd -literal
apm_event SUSPENDREQ {
       exec "sync && sync && sync";
       exec "sleep 1";
       exec "zzz";
}
.Ed
.Pp
will cause
.Nm
to receive the APM event
.Ql SUSPENDREQ
(which may be posted by an LCD close), run the
.Ql sync
command 3 times and wait for a while, then execute
.Nm zzz ( Ns Nm apm Fl z )
to put the system in the suspend state.
.Pp
.Bl -bullet
.It
The apm_event keyword
.Bd -ragged -offset indent
.Ql apm_event
is the keyword which indicates the start of configuration for
each events.
.Ed
.It
APM events
.Bd -ragged -offset indent
If you wish to execute the same commands for different events, the
event names should be delimited by a comma.
The following are
valid event names:
.Bl -item
.It
- Events ignored by the kernel if
.Nm
is running:
.Pp
.Bl -tag -width USERSUSPENDREQ -compact -offset indent
.It STANDBYREQ
.It USERSTANDBYREQ
.It SUSPENDREQ
should include sync in the command list,
.It USERSUSPENDREQ
should include sync in the command list,
.It BATTERYLOW
only zzz should be specified in the command list.
.El
.It
- Events passed to
.Nm
after kernel handling:
.Pp
.Bl -tag -width USERSUSPENDREQ -compact -offset indent
.It NORMRESUME
.It CRITRESUME
.It STANDBYRESUME
.It POWERSTATECHANGE
.It UPDATETIME
.It CAPABILITIESCHANGE
.El
.Pp
Other events will not be sent to
.Nm .
.El
.Ed
.It
command line syntax
.Bd -ragged -offset indent
In the example above, the three lines beginning with
.Ql exec
are commands for the event.
Each line should be terminated with a semicolon.
The command list for the event should be enclosed by
.Ql {
and
.Ql } .
The
.Nm
utility uses
.Pa /bin/sh
for double-quotation enclosed command execution, just as with
.Xr system 3 .
Each command is executed in order until the end of
the list is reached or a command finishes with a non-zero status code.
The
.Nm
utility will report any failed command's status code via
.Xr syslog 3
and will then reject the request event posted by the APM BIOS.
.Ed
.It
Built-in functions
.Bd -ragged -offset indent
You can also specify
.Nm
built-in functions instead of command lines.
A built-in function name should be terminated with a semicolon,
just as with a command line.
The following built-in functions are currently supported:
.Bl -item
.It
- reject:
.Bd -ragged -offset indent
Reject last request posted by APM BIOS.
This can be used to reject
a SUSPEND request when the LCD is closed and put the system in a
STANDBY state instead.
.Ed
.El
.Ed
.El
.Sh EXAMPLES
Sample configuration commands include:
.Bd -literal
apm_event SUSPENDREQ {
        exec "/etc/rc.suspend apm suspend";
}

apm_event USERSUSPENDREQ {
        exec "sync && sync && sync";
        exec "sleep 1";
        exec "apm -z";
}

apm_event NORMRESUME {
        exec "/etc/rc.resume apm suspend";
}

apm_event STANDBYRESUME {
        exec "/etc/rc.resume apm standby";
}

# resume event configuration for serial mouse users by
# reinitializing a moused(8) connected to a serial port.
#
#apm_event NORMRESUME {
#       exec "kill -HUP `cat /var/run/moused.pid`";
#}
#
# suspend request event configuration for ATA HDD users:
# execute standby instead of suspend.
#
#apm_event SUSPENDREQ {
#       reject;
#       exec "sync && sync && sync";
#       exec "sleep 1";
#       exec "apm -Z";
#}
.Ed
.Sh FILES
.Bl -tag -width /etc/apmd.conf -compact
.It Pa /etc/apmd.conf
.It Pa /dev/apmctl
.It Pa /var/run/apmd.pid
.El
.Sh SEE ALSO
.Xr apm 4 ,
.Xr apm 8
.Sh AUTHORS
.An Mitsuru IWASAKI Aq iwasaki@FreeBSD.org
.An KOIE Hidetaka Aq koie@suri.co.jp
.Pp
Some contributions made by
.An Warner Losh Aq imp@FreeBSD.org ,
.An Hiroshi Yamashita Aq bluemoon@msj.biglobe.ne.jp ,
.An Yoshihiko SARUMARU Aq mistral@imasy.or.jp ,
.An Norihiro Kumagai Aq kuma@nk.rim.or.jp ,
.An NAKAGAWA Yoshihisa Aq nakagawa@jp.FreeBSD.org ,
and
.An Nick Hilliard Aq nick@foobar.org .
.Sh HISTORY
The
.Nm
utility appeared in
.Fx 3.3 .
OpenPOWER on IntegriCloud