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