1.\" $NetBSD: shutdownhook_establish.9,v 1.6 2001/09/04 02:51:16 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. When invoked, the hook function 55.Fa fn 56will be passed 57.Fa arg 58as its only argument. 59.Pp 60The 61.Fn shutdownhook_disestablish 62function removes the hook described by the opaque pointer 63.Fa cookie 64from the list of hooks to be invoked at shutdown. If 65.Fa cookie 66is invalid, the result of 67.Fn shutdownhook_disestablish 68is undefined. 69.Pp 70Shutdown hooks should be used to perform one-time activities 71that must happen immediately before the kernel exits. Because 72of the environment in which they are run, shutdown hooks cannot 73rely on many system services (including file systems, and timeouts 74and other interrupt-driven services), or even basic system 75integrity (because the system could be rebooting after a crash). 76.Sh RETURN VALUES 77If successful, 78.Fn shutdownhook_establish 79returns an opaque pointer describing the newly-established 80shutdown hook. Otherwise, it returns NULL. 81.Sh EXAMPLES 82It may be appropriate to use a shutdown hook to 83disable a device that does direct memory access, so that 84the device will not try to access memory while the system 85is rebooting. 86.Pp 87It may be appropriate to use a shutdown hook to 88inform watchdog timer hardware that the operating system 89is no longer running. 90.Sh SEE ALSO 91.Xr doshutdownhooks 9 92.Sh BUGS 93The names are clumsy, at best. 94