[apple/xnu.git] / bsd / man / man2 / reboot.2

.\"   $OpenBSD: reboot.2,v 1.2 1996/10/08 01:20:13 michaels Exp $
.\"	$NetBSD: reboot.2,v 1.5 1995/02/27 12:36:02 cgd Exp $
.\"
.\" Copyright (c) 1980, 1991, 1993
.\"	The Regents of the University of California.  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 the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.
.\"
.\"     @(#)reboot.2	8.1 (Berkeley) 6/4/93
.\"
.Dd June 4, 1993
.Dt REBOOT 2
.Os BSD 4
.Sh NAME
.Nm reboot
.Nd reboot system or halt processor
.Sh SYNOPSIS
.Fd #include <unistd.h>
.Fd #include <sys/reboot.h>
.Ft int
.Fn reboot "int howto"
.Sh DESCRIPTION
.Fn Reboot
reboots the system.  Only the super-user may reboot a machine on demand.
However, a reboot may be invoked automatically in the event of
unrecoverable system failures.  Programs other than
.Xr reboot 8
should not call
.Fn reboot .
.Xr Shutdown 8
or a higher-level API will shut the system down cleanly.
.Pp
.Fa Howto
is a mask of options; the system call interface allows the following
options, defined in the include file
.Aq Pa sys/reboot.h ,
to be passed
to the new kernel or the new bootstrap and init programs.
.Bl -tag -width RB_INITNAMEA
.It Dv RB_AUTOBOOT
The default, causing the system to reboot in its usual fashion.
.It Dv RB_ASKNAME
Interpreted by the bootstrap program itself, causing it to
prompt on the console as to what file should be booted.
Normally, the system is booted from the file
.Dq Em xx Ns No (0,0)bsd ,
where
.Em xx
is the default disk name,
without prompting for the file name.
.It Dv RB_DFLTROOT
Use the compiled in root device.
Normally, the system uses the device from which it was booted
as the root device if possible.
(The default behavior is dependent on the ability of the bootstrap program
to determine the drive from which it was loaded, which is not possible
on all systems.)
.It Dv RB_DUMP
Dump kernel memory before rebooting; see
.Xr savecore 8
for more information.
.It Dv RB_HALT
the processor is simply halted; no reboot takes place.
This option should be used with caution.
.It Dv RB_INITNAME
An option allowing the specification of an init program (see
.Xr init 8 )
other than
.Pa /sbin/init
to be run when the system reboots.
This switch is not currently available.
.It Dv RB_KDB
Load the symbol table and enable a built-in debugger in the system.
This option will have no useful function if the kernel is not configured
for debugging.
Several other options have different meaning if combined
with this option, although their use may not be possible
via the
.Fn reboot
call.
See
.Xr kadb 4
for more information.
.It Dv RB_NOSYNC
Normally, the disks are sync'd (see
.Xr sync 8 )
before the processor is halted or rebooted.
This option may be useful if file system changes have been made manually
or if the processor is on fire.
.It Dv RB_RDONLY
Initially mount the root file system read-only.
This is currently the default, and this option has been deprecated.
.It Dv RB_SINGLE
Normally, the reboot procedure involves an automatic disk consistency
check and then multi-user operations.
.Dv RB_SINGLE
prevents this, booting the system with a single-user shell
on the console.
.Dv RB_SINGLE
is actually interpreted by the
.Xr init 8
program in the newly booted system.
.Pp
When no options are given (i.e.,
.Dv RB_AUTOBOOT
is used), the system is
rebooted from file ``bsd'' in the root file system of unit 0
of a disk chosen in a processor specific way.
An automatic consistency check of the disks is normally performed
(see
.Xr fsck 8 ) .
.El
.Sh RETURN VALUES
If successful, this call never returns.
Otherwise, a -1 is returned and an error is returned in the global
variable
.Va errno .
.Sh ERRORS
.Bl -tag -width Er
.It Bq Er EPERM
The caller is not the super-user.
.El
.Sh SEE ALSO
.Xr shutdown 8 ,
.Xr halt 8 ,
.Xr launchd 8 ,
.Xr reboot 8
.Sh BUGS
The HP300 implementation supports neither
.Dv RB_DFLTROOT
nor
.Dv RB_KDB .
.Sh HISTORY
The
.Fn reboot
function call appeared in
.Bx 4.0 .
Commit	Line	Data
9bccf70c A	1	.\" $OpenBSD: reboot.2,v 1.2 1996/10/08 01:20:13 michaels Exp $
	2	.\" $NetBSD: reboot.2,v 1.5 1995/02/27 12:36:02 cgd Exp $
	3	.\"
	4	.\" Copyright (c) 1980, 1991, 1993
	5	.\" The Regents of the University of California. All rights reserved.
	6	.\"
	7	.\" Redistribution and use in source and binary forms, with or without
	8	.\" modification, are permitted provided that the following conditions
	9	.\" are met:
	10	.\" 1. Redistributions of source code must retain the above copyright
	11	.\" notice, this list of conditions and the following disclaimer.
	12	.\" 2. Redistributions in binary form must reproduce the above copyright
	13	.\" notice, this list of conditions and the following disclaimer in the
	14	.\" documentation and/or other materials provided with the distribution.
	15	.\" 3. All advertising materials mentioning features or use of this software
	16	.\" must display the following acknowledgement:
	17	.\" This product includes software developed by the University of
	18	.\" California, Berkeley and its contributors.
	19	.\" 4. Neither the name of the University nor the names of its contributors
	20	.\" may be used to endorse or promote products derived from this software
	21	.\" without specific prior written permission.
	22	.\"
	23	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	24	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	25	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	26	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	27	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	28	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	29	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	30	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	31	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	32	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	33	.\" SUCH DAMAGE.
	34	.\"
	35	.\" @(#)reboot.2 8.1 (Berkeley) 6/4/93
	36	.\"
	37	.Dd June 4, 1993
	38	.Dt REBOOT 2
	39	.Os BSD 4
	40	.Sh NAME
	41	.Nm reboot
	42	.Nd reboot system or halt processor
	43	.Sh SYNOPSIS
	44	.Fd #include <unistd.h>
	45	.Fd #include <sys/reboot.h>
	46	.Ft int
	47	.Fn reboot "int howto"
	48	.Sh DESCRIPTION
	49	.Fn Reboot
2d21ac55 A	50	reboots the system. Only the super-user may reboot a machine on demand.
	51	However, a reboot may be invoked automatically in the event of
	52	unrecoverable system failures. Programs other than
	53	.Xr reboot 8
	54	should not call
	55	.Fn reboot .
	56	.Xr Shutdown 8
	57	or a higher-level API will shut the system down cleanly.
9bccf70c A	58	.Pp
	59	.Fa Howto
	60	is a mask of options; the system call interface allows the following
	61	options, defined in the include file
	62	.Aq Pa sys/reboot.h ,
	63	to be passed
	64	to the new kernel or the new bootstrap and init programs.
	65	.Bl -tag -width RB_INITNAMEA
	66	.It Dv RB_AUTOBOOT
	67	The default, causing the system to reboot in its usual fashion.
	68	.It Dv RB_ASKNAME
	69	Interpreted by the bootstrap program itself, causing it to
	70	prompt on the console as to what file should be booted.
	71	Normally, the system is booted from the file
	72	.Dq Em xx Ns No (0,0)bsd ,
	73	where
	74	.Em xx
	75	is the default disk name,
	76	without prompting for the file name.
	77	.It Dv RB_DFLTROOT
	78	Use the compiled in root device.
	79	Normally, the system uses the device from which it was booted
	80	as the root device if possible.
	81	(The default behavior is dependent on the ability of the bootstrap program
	82	to determine the drive from which it was loaded, which is not possible
	83	on all systems.)
	84	.It Dv RB_DUMP
	85	Dump kernel memory before rebooting; see
	86	.Xr savecore 8
	87	for more information.
	88	.It Dv RB_HALT
	89	the processor is simply halted; no reboot takes place.
	90	This option should be used with caution.
	91	.It Dv RB_INITNAME
	92	An option allowing the specification of an init program (see
	93	.Xr init 8 )
	94	other than
	95	.Pa /sbin/init
	96	to be run when the system reboots.
	97	This switch is not currently available.
	98	.It Dv RB_KDB
	99	Load the symbol table and enable a built-in debugger in the system.
	100	This option will have no useful function if the kernel is not configured
	101	for debugging.
	102	Several other options have different meaning if combined
	103	with this option, although their use may not be possible
	104	via the
	105	.Fn reboot
	106	call.
	107	See
	108	.Xr kadb 4
	109	for more information.
	110	.It Dv RB_NOSYNC
	111	Normally, the disks are sync'd (see
	112	.Xr sync 8 )
	113	before the processor is halted or rebooted.
	114	This option may be useful if file system changes have been made manually
	115	or if the processor is on fire.
	116	.It Dv RB_RDONLY
	117	Initially mount the root file system read-only.
	118	This is currently the default, and this option has been deprecated.
	119	.It Dv RB_SINGLE
	120	Normally, the reboot procedure involves an automatic disk consistency
	121	check and then multi-user operations.
122	.Dv RB_SINGLE
123	prevents this, booting the system with a single-user shell
124	on the console.
125	.Dv RB_SINGLE
126	is actually interpreted by the
127	.Xr init 8
128	program in the newly booted system.
129	.Pp
130	When no options are given (i.e.,
131	.Dv RB_AUTOBOOT
132	is used), the system is
133	rebooted from file ``bsd'' in the root file system of unit 0
134	of a disk chosen in a processor specific way.
135	An automatic consistency check of the disks is normally performed
136	(see
137	.Xr fsck 8 ) .
138	.El
139	.Sh RETURN VALUES
140	If successful, this call never returns.
141	Otherwise, a -1 is returned and an error is returned in the global
142	variable
143	.Va errno .
144	.Sh ERRORS
145	.Bl -tag -width Er
146	.It Bq Er EPERM
147	The caller is not the super-user.
148	.El
149	.Sh SEE ALSO
2d21ac55	150	.Xr shutdown 8 ,
9bccf70c	151	.Xr halt 8 ,
2d21ac55 A	152	.Xr launchd 8 ,
2d21ac55 A	153	.Xr reboot 8
9bccf70c A	154	.Sh BUGS
	155	The HP300 implementation supports neither
	156	.Dv RB_DFLTROOT
	157	nor
	158	.Dv RB_KDB .
	159	.Sh HISTORY
	160	The
	161	.Fn reboot
	162	function call appeared in
	163	.Bx 4.0 .