1.\" $NetBSD: shutdownhook_establish.9,v 1.7 2002/10/14 13:43:32 wiz Exp $
2.\"
3.\" Copyright (c) 1994 Christopher G. Demetriou
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. All advertising materials mentioning features or use of this software
15.\"    must display the following acknowledgement:
16.\"          This product includes software developed for the
17.\"          NetBSD Project.  See http://www.netbsd.org/ for
18.\"          information about NetBSD.
19.\" 4. The name of the author may not be used to endorse or promote products
20.\"    derived from this software without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
23.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
24.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
25.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
26.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
27.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
31.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32.\"
33.\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>>
34.\"
35.Dd November 13, 1995
36.Dt SHUTDOWNHOOK_ESTABLISH 9
37.Os
38.Sh NAME
39.Nm shutdownhook_establish ,
40.Nm shutdownhook_disestablish
41.Nd add or remove a shutdown hook
42.Sh SYNOPSIS
43.Ft void *
44.Fn shutdownhook_establish "void (*fn)(void *)" "void *arg"
45.Ft void
46.Fn shutdownhook_disestablish "void *cookie"
47.Sh DESCRIPTION
48The
49.Fn shutdownhook_establish
50function adds
51.Fa fn
52to the list of hooks invoked by
53.Xr doshutdownhooks 9
54at shutdown.
55When invoked, the hook function
56.Fa fn
57will be passed
58.Fa arg
59as its only argument.
60.Pp
61The
62.Fn shutdownhook_disestablish
63function removes the hook described by the opaque pointer
64.Fa cookie
65from the list of hooks to be invoked at shutdown.
66If
67.Fa cookie
68is invalid, the result of
69.Fn shutdownhook_disestablish
70is undefined.
71.Pp
72Shutdown hooks should be used to perform one-time activities
73that must happen immediately before the kernel exits.
74Because of the environment in which they are run, shutdown hooks cannot
75rely on many system services (including file systems, and timeouts
76and other interrupt-driven services), or even basic system
77integrity (because the system could be rebooting after a crash).
78.Sh RETURN VALUES
79If successful,
80.Fn shutdownhook_establish
81returns an opaque pointer describing the newly-established
82shutdown hook.
83Otherwise, it returns NULL.
84.Sh EXAMPLES
85It may be appropriate to use a shutdown hook to
86disable a device that does direct memory access, so that
87the device will not try to access memory while the system
88is rebooting.
89.Pp
90It may be appropriate to use a shutdown hook to
91inform watchdog timer hardware that the operating system
92is no longer running.
93.Sh SEE ALSO
94.Xr doshutdownhooks 9
95.Sh BUGS
96The names are clumsy, at best.
97