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