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