--- name: "kern_reboot" section: "9" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/kern_reboot" --- # kern\_reboot(9) reboot, halt, or power off the system ## NAME **kern\_reboot**, **shutdown\_nice** – reboot, halt, or power off the system ## SYNOPSIS **#include \** **#include \** **#include \** *extern* *int* *rebooting;* *void*\ **kern\_reboot**(*int howto*); *void*\ **shutdown\_nice**(*int howto*); **#include \** **EVENTHANDLER\_REGISTER**(*shutdown\_pre\_sync*, *shutdown\_fn*, *private*, *priority*); **EVENTHANDLER\_REGISTER**(*shutdown\_post\_sync*, *shutdown\_fn*, *private*, *priority*); **EVENTHANDLER\_REGISTER**(*shutdown\_final*, *shutdown\_fn*, *private*, *priority*); ## DESCRIPTION The **kern\_reboot**() function handles final system shutdown, and either halts, reboots, or powers down the system. The exact action to be taken is determined by the flags passed in *howto*. The relevant flags are: - RB\_HALT Halt the system in-place rather than restarting. - RB\_POWEROFF Power down the system rather than restarting. - RB\_POWERCYCLE Request a power-cycle in addition to restarting. - RB\_NOSYNC Do not sync filesystems during shutdown. - RB\_DUMP Dump kernel memory during shutdown. The *howto* field, and its full list of flags are described in additional detail by [reboot(2)](/reboot/2.md). **kern\_reboot**() performs the following actions: 1. Set the *rebooting* variable to 1, indicating that the reboot process has begun and cannot be stopped. 2. Unless the RB\_NOSYNC flag is set in *howto*, sync and unmount the system's disks by calling [vfs\_unmountall(9)](/vfs_unmountall/9.md). 3. If rebooting after a panic( RB\_DUMP is set in *howto*, but RB\_HALT is not set), initiate a system crash dump via **doadump**(). 4. Print a message indicating that the system is about to be halted or rebooted, and a report of the total system uptime. 5. Execute all registered shutdown hooks. See SHUTDOWN HOOKS below. 6. As a last resort, if none of the shutdown hooks handled the reboot, call the machine-dependent **cpu\_reset**() function. In the unlikely case that this is not supported, **kern\_reboot**() will loop forever at the end of the function. This requires a manual reset of the system. **kern\_reboot**() may be called from a typical kernel execution context, when the system is running normally. It may also be called as the final step of a kernel panic, or from the kernel debugger. Therefore, the code in this function is subject to restrictions described by the EXECUTION CONTEXT section of the [panic(9)](/panic/9.md) man page. The **shutdown\_nice**() function is the intended path for performing a clean reboot or shutdown when the system is operating under normal conditions. Calling this function will send a signal to the [init(8)](/init/8.md) process, instructing it to perform a shutdown. When [init(8)](/init/8.md) has cleanly terminated its children, it will perform the [reboot(2)](/reboot/2.md) system call, which in turn calls **kern\_reboot**(). If **shutdown\_nice**() is called before the [init(8)](/init/8.md) process has been spawned, or if the system has panicked or otherwise halted, **kern\_reboot**() will be called directly. ## SHUTDOWN HOOKS The system defines three separate [EVENTHANDLER(9)](/EVENTHANDLER/9.md) events, which are invoked successively during the shutdown procedure. These are *shutdown\_pre\_sync*, *shutdown\_post\_sync*, and *shutdown\_final*. They will be executed unconditionally in the listed order. Handler functions registered to any of these events will receive the value of *howto* as their second argument, which may be used to decide what action to take. The *shutdown\_pre\_sync* event is invoked before syncing filesystems to disk. It enables any action or state transition that must happen before this point to take place. The *shutdown\_post\_sync* event is invoked at the point immediately after the filesystem sync has finished. It enables, for example, disk drivers to complete the sync by flushing their cache to disk. Note that this event still takes place before the optional kernel core dump. The *shutdown\_final* event is invoked as the very last step of **kern\_reboot**(). Drivers and subsystems such as [acpi(4)](/acpi/4.md) can register handlers to this event that will perform the actual reboot, power-off, or halt. Notably, the *shutdown\_final* event is also the point at which all kernel modules will have their shutdown( MOD\_SHUTDOWN) hooks executed, and when the [DEVICE\_SHUTDOWN(9)](/DEVICE_SHUTDOWN/9.md) method will be executed recursively on all devices. All event handlers, like **kern\_reboot**() itself, may be run in either normal shutdown context or a kernel panic or debugger context. Handler functions are expected to take care not to trigger recursive panics. ## RETURN VALUES The **kern\_reboot**() function does not return. The **shutdown\_nice**() function will usually return to its caller, having initiated the asynchronous system shutdown. It will not return when called from a panic or debugger context, or during early boot. ## EXAMPLES A hypothetical driver, foo(4), defines a *shutdown\_final* event handler that can handle system power-off by writing to a device register, but it does not handle halt or reset. ``` void foo_poweroff_handler(struct void *arg, int howto) { struct foo_softc *sc = arg; uint32_t reg; if ((howto & RB_POWEROFF) != 0) { reg = FOO_POWEROFF; WRITE4(sc, FOO_POWEROFF_REG, reg); } } ``` The handler is then registered in the device attach routine: ``` int foo_attach(device_t dev) { struct foo_softc *sc; ... /* Pass the device's software context as the private arg. */ EVENTHANDLER_REGISTER(shutdown_final, foo_poweroff_handler, sc, SHUTDOWN_PRI_DEFAULT); ... } ``` This *shutdown\_final* handler uses the RB\_NOSYNC flag to detect that a panic or other unusual condition has occurred, and returns early: ``` void bar_shutdown_final(struct void *arg, int howto) { if ((howto & RB_NOSYNC) != 0) return; /* Some code that is not panic-safe. */ ... } ``` ## SEE ALSO [reboot(2)](/reboot/2.md), [init(8)](/init/8.md), [DEVICE\_SHUTDOWN(9)](/DEVICE_SHUTDOWN/9.md), [EVENTHANDLER(9)](/EVENTHANDLER/9.md), [module(9)](/module/9.md), [panic(9)](/panic/9.md), [vfs\_unmountall(9)](/vfs_unmountall/9.md)