xref: /netbsd-src/share/man/man9/powerhook_establish.9 (revision 8b0f9554ff8762542c4defc4f70e1eb76fb508fa)
1.\"	$NetBSD: powerhook_establish.9,v 1.8 2006/09/24 07:27:57 dogcow Exp $
2.\"
3.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Lennart Augustsson.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\" 3. All advertising materials mentioning features or use of this software
18.\"    must display the following acknowledgement:
19.\"        This product includes software developed by the NetBSD
20.\"        Foundation, Inc. and its contributors.
21.\" 4. Neither the name of The NetBSD Foundation nor the names of its
22.\"    contributors may be used to endorse or promote products derived
23.\"    from this software without specific prior written permission.
24.\"
25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35.\" POSSIBILITY OF SUCH DAMAGE.
36.\"
37.Dd September 24, 2006
38.Dt POWERHOOK_ESTABLISH 9
39.Os
40.Sh NAME
41.Nm powerhook_establish ,
42.Nm powerhook_disestablish
43.Nd add or remove a power change hook
44.Sh SYNOPSIS
45.Ft void *
46.Fn powerhook_establish "const char *name" "void (*fn)(int why, void *a)" \
47"void *arg"
48.Ft void
49.Fn powerhook_disestablish "void *cookie"
50.Sh DESCRIPTION
51The
52.Fn powerhook_establish
53function adds
54.Fa fn
55of the list of hooks invoked by
56.Xr dopowerhooks 9
57at power change.
58When invoked, the hook function
59.Fa fn
60will be passed the new power state as the first argument and
61.Fa arg
62as its second argument.
63.Pp
64The
65.Fn powerhook_disestablish
66function removes the hook described by the opaque pointer
67.Fa cookie
68from the list of hooks to be invoked at power change.
69If
70.Fa cookie
71is invalid, the result of
72.Fn powerhook_disestablish
73is undefined.
74.Pp
75Power hooks should be used to perform activities
76that must happen when the power situation to the computer changes.
77Because of the environment in which they are run, power hooks cannot
78rely on many system services (including file systems, and timeouts
79and other interrupt-driven services).
80The power hooks are typically executed from an interrupt context.
81.Pp
82The different reasons for calling the power hooks are: suspend, standby, and
83resume.
84The reason is reflected in the
85.Fa why
86argument and the values
87.Dv PWR_SOFTSUSPEND ,
88.Dv PWR_SUSPEND ,
89.Dv PWR_SOFTSTANDBY ,
90.Dv PWR_STANDBY ,
91.Dv PWR_SOFTRESUME ,
92and
93.Dv PWR_RESUME .
94It calls with PWR_SOFTxxx in the normal priority level while the other
95callings are protected with
96.Xr splhigh 9 .
97At suspend the system is going to lose (almost) all power, standby retains
98some power (e.g., minimal power to USB devices), and at resume power is
99back to normal.
100.Sh RETURN VALUES
101If successful,
102.Fn powerhook_establish
103returns an opaque pointer describing the newly-established
104power hook.
105Otherwise, it returns NULL.
106.Sh SEE ALSO
107.Xr dopowerhooks 9
108