SHUTDOWN

NAME    [Toc]    [Back]

     shutdownhook_establish, shutdownhook_disestablish -  add  or
remove a shutdown
 hook

SYNOPSIS    [Toc]    [Back]

     #include <sys/types.h>
     #include <sys/systm.h>

     void *
     shutdownhook_establish(void (*fn)(void *), void *arg);

     void
     shutdownhook_disestablish(void *cookie);

DESCRIPTION    [Toc]    [Back]

     The shutdownhook_establish() function adds fn to the list of
hooks invoked
 by doshutdownhooks(9) at shutdown.  When invoked,  the
hook function
     fn will be passed arg as its only argument.

     The  shutdownhook_disestablish()  function  removes the hook
described by
     the opaque pointer cookie from the list of hooks to  be  invoked at shutdown.
     If    cookie    is    invalid,   the   result   of
shutdownhook_disestablish() is
     undefined.

     Shutdown hooks should be used to perform one-time activities
that must
     happen  immediately before the kernel exits.  Because of the
environment
     in which they are run, shutdown hooks cannot  rely  on  many
system services
     (including file systems, timeouts, and other interrupt-driven services)
     or even basic system integrity (because the system could  be
rebooting after
 a crash).

     Shutdown  hooks are, like startup hooks, implemented via the
more general
     dohooks(9) API.

RETURN VALUES    [Toc]    [Back]

     If successful, shutdownhook_establish()  returns  an  opaque
pointer describing
 the newly established shutdown hook.  Otherwise, it
returns
     NULL.

EXAMPLES    [Toc]    [Back]

     It may be appropriate to use a shutdown hook  to  disable  a
device that
     does  direct  memory access, so that the device will not try
to access memory
 while the system is rebooting.

     It may be appropriate to  use  a  shutdown  hook  to  inform
watchdog timer
     hardware that the operating system is no longer running.

SEE ALSO    [Toc]    [Back]

     dohooks(9), doshutdownhooks(9), dostartuphooks(9)

CAVEATS    [Toc]    [Back]

     Shutdown  hooks  should  only  be used to do what's strictly
necessary to do
     to ensure a correct reboot.  Since shutdown  hooks  are  run
even after a
     panic,  a panic caused by a shutdown hook will automatically
cause the
     shutdown hook to be run again causing an endless  loop.   An
example of
     things  that  need  to  be  done in a shutdown hook could be
stopping DMA engines
 that might corrupt memory when rebooting.  An  example
of things
     that  shouldn't  be  done  in a shutdown hook is syncing the
file systems.
     Once again, since the system could be rebooting  because  of
an internal
     inconsistency, writing down anything to permanent storage or
trusting the
     internal state of the system is a very bad idea.

BUGS    [Toc]    [Back]

     The names are clumsy, at best.

OpenBSD     3.6                        November     13,      1995