git: b7caa912f9df - main - kern_reboot(9): document shutdown_nice()

The branch main has been updated by mhorne:

URL: https://cgit.FreeBSD.org/src/commit/?id=b7caa912f9df5f76f189be18afc949a775c8e0fe

commit b7caa912f9df5f76f189be18afc949a775c8e0fe
Author:     Mitchell Horne <mhorne@FreeBSD.org>
AuthorDate: 2023-03-20 19:58:16 +0000
Commit:     Mitchell Horne <mhorne@FreeBSD.org>
CommitDate: 2023-03-20 20:12:12 +0000

    kern_reboot(9): document shutdown_nice()
    
    Reviewed by:    markj, Pau Amma <pauamma@gundo.com>
    MFC after:      1 week
    Sponsored by:   The FreeBSD Foundation
    Differential Revision:  https://reviews.freebsd.org/D39134
---
 share/man/man9/Makefile      |  3 ++-
 share/man/man9/kern_reboot.9 | 35 ++++++++++++++++++++++++++++++++++-
 2 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index b03993b57860..3bfc72b69dc6 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1335,7 +1335,8 @@ MLINKS+=intr_event.9 intr_event_add_handler.9 \
 	intr_event.9 intr_event_remove_handler.9 \
 	intr_event.9 intr_priority.9
 MLINKS+=KASSERT.9 MPASS.9
-MLINKS+=kern_reboot.9 reboot.9
+MLINKS+=kern_reboot.9 reboot.9 \
+	kern_reboot.9 shutdown_nice.9
 MLINKS+=kern_yield.9 maybe_yield.9 \
 	kern_yield.9 should_yield.9
 MLINKS+=kernacc.9 useracc.9
diff --git a/share/man/man9/kern_reboot.9 b/share/man/man9/kern_reboot.9
index e88574cce0d1..d120a437c521 100644
--- a/share/man/man9/kern_reboot.9
+++ b/share/man/man9/kern_reboot.9
@@ -45,7 +45,8 @@
 .Dt REBOOT 9
 .Os
 .Sh NAME
-.Nm kern_reboot
+.Nm kern_reboot ,
+.Nm shutdown_nice
 .Nd reboot, halt, or power off the system
 .Sh SYNOPSIS
 .In sys/types.h
@@ -54,6 +55,8 @@
 .Vt extern int rebooting;
 .Ft void
 .Fn kern_reboot "int howto"
+.Ft void
+.Fn shutdown_nice "int howto"
 .In sys/eventhandler.h
 .Fn EVENTHANDLER_REGISTER "shutdown_pre_sync" "shutdown_fn" "private" "priority"
 .Fn EVENTHANDLER_REGISTER "shutdown_post_sync" "shutdown_fn" "private" "priority"
@@ -147,12 +150,42 @@ the
 section of the
 .Xr panic 9
 man page.
+.Pp
+The
+.Fn 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
+.Xr init 8
+process, instructing it to perform a shutdown.
+When
+.Xr init 8
+has cleanly terminated its children, it will perform the
+.Xr reboot 2
+system call, which in turn calls
+.Fn kern_reboot .
+.Pp
+If
+.Fn shutdown_nice
+is called before the
+.Xr init 8
+process has been spawned, or if the system has panicked or otherwise halted,
+.Fn kern_reboot
+will be called directly.
 .Sh RETURN VALUES
 The
 .Fn kern_reboot
 function does not return.
+.Pp
+The
+.Fn 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.
 .Sh SEE ALSO
 .Xr reboot 2 ,
+.Xr init 8 ,
 .Xr EVENTHANDLER 9 ,
 .Xr panic 9 ,
 .Xr vfs_unmountall 9