Date: Mon, 20 Mar 2023 20:13:28 GMT From: Mitchell Horne <mhorne@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org Subject: git: b7caa912f9df - main - kern_reboot(9): document shutdown_nice() Message-ID: <202303202013.32KKDSkl033148@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202303202013.32KKDSkl033148>