--- /dev/null
+# $NetBSD: Makefile,v 1.1 1995/11/25 21:24:47 perry Exp $
+
+# Makefile for section 9 (kernel function and variable) manual pages.
+
+MAN= boot.9 doshutdownhooks.9 inittodr.9 resettodr.9 \
+ shutdownhook_establish.9 time.9
+MLINKS+=shutdownhook_establish.9 shutdownhook_disestablish.9
+MLINKS+=time.9 boottime.9 time.9 mono_time.9 time.9 runtime.9
+
+.include <bsd.prog.mk>
--- /dev/null
+.\" $NetBSD: boot.9,v 1.1 1995/11/25 21:24:48 perry Exp $
+.\"
+.\" Copyright (c) 1994 Christopher G. Demetriou
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed by Christopher G. Demetriou
+.\" for the NetBSD Project.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\" derived from this software without specific prior written permission
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd November 13, 1995
+.Dt BOOT 9
+.Os NetBSD
+.Sh NAME
+.Nm boot
+.Nd halt or reboot the system
+.Sh SYNOPSIS
+.Fd #include <sys/reboot.h>
+.Ft void
+.Fn boot "int howto"
+.Sh DESCRIPTION
+The
+.Fn boot
+function handles final system shutdown, and either halts or reboots
+the system. The exact action to be taken is determined by the
+flags passed in
+.Fa howto
+and by whether or not the system has finished autoconfiguration.
+.Pp
+If the system has finished autoconfiguration,
+.Fn boot
+does the following:
+.Bl -enum -offset indent
+.It
+Sets the
+.Va boothowto
+system variable from the
+.Fa howto
+argument.
+.It
+If this is the first invocation of
+.Fn boot
+and the
+.Dv RB_NOSYNC
+flag is not set in
+.Fa howto ,
+syncs and unmounts the system disks by calling
+.Xr vfs_shutdown 9
+and sets the time of day clock by calling
+.Xr resettodr 9 .
+.It
+Disables interrupts.
+.It
+If rebooting after a crash (i.e. if
+.Dv RB_DUMP
+is set in
+.Fa howto ,
+but
+.Dv RB_HALT
+is not), saves a system crash dump.
+.It
+Runs any shutdown hooks by calling
+.Xr doshutdownhooks 9 .
+.It
+Prints a message indicating that the system is about to be halted
+or rebooted.
+.It
+If
+.Dv RB_HALT
+is set in
+.Fa howto ,
+halts the system.
+Otherwise, reboots the system.
+.El
+.Pp
+If the system has not finished autoconfiguration,
+.Fn boot
+runs any shutdown hooks by calling
+.Xr doshutdownhooks 9 ,
+prints a message, and halts the system.
+.Sh SEE ALSO
+.Xr doshutdownhooks 9 ,
+.Xr resettodr 9 ,
+.Xr vfs_shutdown 9
--- /dev/null
+.\" $NetBSD: doshutdownhooks.9,v 1.1 1995/11/25 21:24:49 perry Exp $
+.\"
+.\" Copyright (c) 1994 Christopher G. Demetriou
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed by Christopher G. Demetriou
+.\" for the NetBSD Project.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\" derived from this software without specific prior written permission
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd November 13, 1995
+.Dt DOSHUTDOWNHOOKS 9
+.Os NetBSD
+.Sh NAME
+.Nm doshutdownhooks
+.Nd run all shutdown hooks
+.Sh SYNOPSIS
+.Ft void
+.Fn doshutdownhooks "void"
+.Sh DESCRIPTION
+The
+.Fn doshutdownhooks
+function invokes all shutdown hooks established using the
+.Xr shutdownhook_establish 9
+function. Shutdown hooks are called in reverse order, i.e.
+the shutdown hook established last will be called first.
+.Pp
+This function is called from
+.Xr boot 9
+with interrupts turned off.
+It is called immediately before the system is halted or rebooted,
+after file systems have been unmounted, after the clock has been updated,
+and after a system dump has been done (if necessary).
+.Sh SEE ALSO
+.Xr boot 9 ,
+.Xr shutdownhook_establish 9
--- /dev/null
+.\" $NetBSD: inittodr.9,v 1.1 1995/11/25 21:24:50 perry Exp $
+.\"
+.\" Copyright (c) 1994 Christopher G. Demetriou
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed by Christopher G. Demetriou
+.\" for the NetBSD Project.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\" derived from this software without specific prior written permission
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd November 13, 1995
+.Dt INITTODR 9
+.Os NetBSD
+.Sh NAME
+.Nm inittodr
+.Nd initialize system time
+.Sh SYNOPSIS
+.Ft void
+.Fn inittodr "time_t base"
+.Sh DESCRIPTION
+The
+.Fn inittodr
+function determines the time and sets the system clock.
+It tries to pick the correct time using a set of heuristics that examine
+the system's battery backed clock and the time reported by the file
+system, as given in
+.Fa base .
+Those heuristics include:
+.Bl -bullet
+.It
+If the battery-backed clock has a valid time, it is used.
+.It
+If the battery-backed clock does not have a valid time, and the
+the time provided in
+.Fa base
+is within reason,
+.Fa base
+is used as the current time.
+.It
+If the battery-backed clock appears invalid, and
+.Fa base
+appears non-sensical or was not provided (was given as zero),
+a arbitrary base (typically some time in the late 1970s)
+will be used.
+.El
+.Pp
+Once a system time has been determined, it is stored in the
+.Va time
+variable.
+.Sh DIAGNOSTICS
+The
+.Fn inittodr
+function prints diagnostic messages if it has trouble figuring
+out the system time. Conditions that can cause diagnostic
+messages to be printed include:
+.Bl -bullet
+.It
+The battery-backed clock's time appears nonsensical.
+.It
+The
+.Fa base
+time appears nonsensical.
+.It
+The
+.Fa base
+time and the battery-backed clock's time differ by a large amount.
+.El
+.Sh SEE ALSO
+.Xr resettodr 9 ,
+.Xr time 9
+.Sh BUGS
+On many systems,
+.Fn inittodr
+has to convert from
+a time expressed in terms of year, month, day, hours, minutes,
+and seconds to
+.Va time ,
+expressed in seconds. Many of the implementations could share code,
+but do not.
+.Pp
+Each system's heuristics for picking the correct time are slightly
+different.
--- /dev/null
+.\" $NetBSD: resettodr.9,v 1.1 1995/11/25 21:24:51 perry Exp $
+.\"
+.\" Copyright (c) 1994 Christopher G. Demetriou
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed by Christopher G. Demetriou
+.\" for the NetBSD Project.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\" derived from this software without specific prior written permission
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd November 13, 1995
+.Dt RESETTODR 9
+.Os NetBSD
+.Sh NAME
+.Nm resettodr
+.Nd set battery-backed clock from system time
+.Sh SYNOPSIS
+.Ft void
+.Fn resettodr "void"
+.Sh DESCRIPTION
+The
+.Fn resettodr
+function sets the system's battery backed clock based on the contents
+of the system
+.Va time
+variable.
+.Sh SEE ALSO
+.Xr inittodr 9 ,
+.Xr time 9
+.Sh BUGS
+On many systems,
+.Fn resettodr
+has to convert from
+.Va time
+to a time expressed in terms of year, month, day, hours, minutes,
+and seconds. Many of the implementations could share code, but do not.
--- /dev/null
+.\" $NetBSD: shutdownhook_establish.9,v 1.1 1995/11/25 21:24:52 perry Exp $
+.\"
+.\" Copyright (c) 1994 Christopher G. Demetriou
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed by Christopher G. Demetriou
+.\" for the NetBSD Project.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\" derived from this software without specific prior written permission
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd November 13, 1995
+.Dt SHUTDOWNHOOK_ESTABLISH 9
+.Os NetBSD
+.Sh NAME
+.Nm shutdownhook_establish ,
+.Nm shutdownhook_disestablish
+.Nd add or remove a shutdown hook
+.Sh SYNOPSIS
+.Ft void *
+.Fn shutdownhook_establish "void (*fn)(void *)" "void *arg"
+.Ft void
+.Fn shutdownhook_disestablish "void *cookie"
+.Sh DESCRIPTION
+The
+.Fn shutdownhook_establish
+function adds
+.Fa fn
+to the list of hooks invoked by
+.Xr doshutdownhooks 9
+at shutdown. When invoked, the hook function
+.Fa fn
+will be passed
+.Fa arg
+as its only argument.
+.Pp
+The
+.Fn shutdownhook_disestablish
+function removes the hook described by the opaque pointer
+.Fa cookie
+from the list of hooks to be invoked at shutdown. If
+.Fa cookie
+is invalid, the result of
+.Fn shutdownhook_disestablish
+is undefined.
+.Pp
+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, and timeouts
+and other interrupt-driven services), or even basic system
+integrity (because the system could be rebooting after a crash).
+.Sh RETURN VALUES
+If successful,
+.Fn shutdownhook_establish
+returns an opaque pointer describing the newly-established
+shutdown hook. Otherwise, it returns NULL.
+.Sh EXAMPLES
+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.
+.Pp
+It may be appropriate to use a shutdown hook to
+inform watchdog timer hardware that the operating system
+is no longer running.
+.Sh SEE ALSO
+.Xr doshutdownhooks 9
+.Sh BUGS
+The names are clumsy, at best.
--- /dev/null
+.\" $NetBSD: time.9,v 1.1 1995/11/25 21:24:53 perry Exp $
+.\"
+.\" Copyright (c) 1994 Christopher G. Demetriou
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed by Christopher G. Demetriou
+.\" for the NetBSD Project.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\" derived from this software without specific prior written permission
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd November 13, 1995
+.Dt TIME 9
+.Os NetBSD
+.Sh NAME
+.Nm boottime ,
+.Nm mono_time ,
+.Nm runtime ,
+.Nm time
+.Nd system time variables
+.Sh SYNOPSIS
+.Va extern struct timeval boottime;
+.br
+.Va extern volatile struct timeval mono_time;
+.br
+.Va extern struct timeval runtime;
+.br
+.Va extern volatile struct timeval time;
+.Sh DESCRIPTION
+The
+.Va time
+variable is the system's
+.Dq wall time
+clock.
+It is set at boot by
+.Xr inittodr 9 ,
+and is updated by the
+.Xr settimeofday 2
+system call and by periodic clock interrupts.
+.Pp
+The
+.Va boottime
+variable holds the system boot time. It is set from
+.Va time
+at system boot, and is updated when the system time is adjusted
+with
+.Xr settimeofday 2 .
+.Pp
+The
+.Va runtime
+variable holds the time that the system switched to the
+current process.
+It is set after each context switch,
+and is updated when the system time is adjusted with
+.Xr settimeofday 2 .
+Because
+.Va runtime
+is used for system accounting, it is set with the high-resolution
+.Xr microtime 9
+function, rather than being copied from
+.Va time .
+.Pp
+The
+.Va mono_time
+variable is a monotonically increasing system clock. It is set
+from
+.Va time
+at boot, and is updated by the periodic timer interrupt. (It is
+not updated by
+.Xr settimeofday 2 .)
+.Pp
+All of these variables contain times
+expressed in seconds and microseconds since midnight (0 hour),
+January 1, 1970.
+.Pp
+Clock interrupts should be blocked
+when reading or writing
+.Va time
+or
+.Va mono_time ,
+because those variables are updated by
+.Fn hardclock .
+.Va Boottime
+and
+.Va runtime
+may be read and written without special precautions.
+.Sh SEE ALSO
+.Xr hz 9 ,
+.Xr hardclock 9 ,
+.Xr inittodr 9 ,
+.Xr microtime 9 ,
+.Xr settimeofday 2
+.Sh BUGS
+.Va Runtime
+should not be updated when the system time is
+changed with
+.Xr settimeofday ,
+because it is used for resource accounting.
+.Pp
+The notion of having a single
+.Va runtime
+variable obviously won't be appropriate in multiprocessor systems.
projects / openbsd / commitdiff