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