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