1 files changed, 107 insertions, 0 deletions
diff --git a/static/netbsd/man9/powerhook_establish.9 b/static/netbsd/man9/powerhook_establish.9
new file mode 100644
index 00000000..a921bceb
--- /dev/null
+++ b/static/netbsd/man9/powerhook_establish.9
@@ -0,0 +1,107 @@
+.\"	$NetBSD: powerhook_establish.9,v 1.15 2025/01/04 17:21:41 riastradh Exp $
+.\"
+.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Lennart Augustsson.
+.\"
+.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
+.\"
+.Dd December 30, 2024
+.Dt POWERHOOK_ESTABLISH 9
+.Os
+.Sh NAME
+.Nm powerhook_establish ,
+.Nm powerhook_disestablish
+.Nd add or remove a power change hook
+.Sh SYNOPSIS
+.Ft void *
+.Fn powerhook_establish "const char *name" "void (*fn)(int why, void *a)" \
+"void *arg"
+.Ft void
+.Fn powerhook_disestablish "void *cookie"
+.Sh DESCRIPTION
+.Em The
+.Nm
+.Em API is deprecated.
+See
+.Xr pmf 9
+for replacement functionality.
+.Pp
+The
+.Fn powerhook_establish
+function adds
+.Fa fn
+to the list of hooks invoked by
+.Xr dopowerhooks 9
+at power change.
+When invoked, the hook function
+.Fa fn
+will be passed the new power state as the first argument and
+.Fa arg
+as its second argument.
+.Pp
+The
+.Fn powerhook_disestablish
+function removes the hook described by the opaque pointer
+.Fa cookie
+from the list of hooks to be invoked at power change.
+If
+.Fa cookie
+is invalid, the result of
+.Fn powerhook_disestablish
+is undefined.
+.Pp
+Power hooks should be used to perform activities
+that must happen when the power situation to the computer changes.
+Because of the environment in which they are run, power hooks cannot
+rely on many system services (including file systems, and timeouts
+and other interrupt-driven services).
+The power hooks are typically executed from an interrupt context.
+.Pp
+The different reasons for calling the power hooks are: suspend, standby, and
+resume.
+The reason is reflected in the
+.Fa why
+argument and the values
+.Dv PWR_SOFTSUSPEND ,
+.Dv PWR_SUSPEND ,
+.Dv PWR_SOFTSTANDBY ,
+.Dv PWR_STANDBY ,
+.Dv PWR_SOFTRESUME ,
+and
+.Dv PWR_RESUME .
+It calls with PWR_SOFTxxx in the normal priority level while the other
+callings are protected with
+.Xr splhigh 9 .
+At suspend the system is going to lose (almost) all power, standby retains
+some power (e.g., minimal power to USB devices), and at resume power is
+back to normal.
+.Sh RETURN VALUES
+If successful,
+.Fn powerhook_establish
+returns an opaque pointer describing the newly-established
+power hook.
+Otherwise, it returns NULL.
+.Sh SEE ALSO
+.Xr dopowerhooks 9