man2/reboot.2

   1 .\" Copyright (c) 1998 Andries Brouwer (aeb@cwi.nl), 24 September 1998
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
   6 .\"     Added notes on capability requirements
   7 .\"
   8 .TH REBOOT 2 2021-03-22 "Linux" "Linux Programmer's Manual"
   9 .SH NAME
  10 reboot \- reboot or enable/disable Ctrl-Alt-Del
  11 .SH LIBRARY
  12 Standard C library
  13 .RI ( libc ", " \-lc )
  14 .SH SYNOPSIS
  15 .nf
  16 .RB "/* Since kernel version 2.1.30 there are symbolic names " LINUX_REBOOT_*
  17    for the constants and a fourth argument to the call: */
  18 .PP
  19 .BR "#include <linux/reboot.h>  " \
  20 "/* Definition of " LINUX_REBOOT_* " constants */"
  21 .BR "#include <sys/syscall.h>   " "/* Definition of " SYS_* " constants */"
  22 .B #include <unistd.h>
  23 .PP
  24 .BI "int syscall(SYS_reboot, int " magic ", int " magic2 ", int " cmd ", void *" arg );
  25 .PP
  26 /* Under glibc and most alternative libc's (including uclibc, dietlibc,
  27    musl and a few others), some of the constants involved have gotten
  28 .RB "   symbolic names " RB_* ", and the library call is a 1-argument"
  29    wrapper around the system call: */
  30 .PP
  31 .BR "#include <sys/reboot.h>    " "/* Definition of " RB_* " constants */"
  32 .B #include <unistd.h>
  33 .PP
  34 .BI "int reboot(int " cmd );
  35 .fi
  36 .SH DESCRIPTION
  37 The
  38 .BR reboot ()
  39 call reboots the system, or enables/disables the reboot keystroke
  40 (abbreviated CAD, since the default is Ctrl-Alt-Delete;
  41 it can be changed using
  42 .BR loadkeys (1)).
  43 .PP
  44 This system call fails (with the error
  45 .BR EINVAL )
  46 unless
  47 .I magic
  48 equals
  49 .B LINUX_REBOOT_MAGIC1
  50 (that is, 0xfee1dead) and
  51 .I magic2
  52 equals
  53 .B LINUX_REBOOT_MAGIC2
  54 (that is, 672274793).
  55 However, since 2.1.17 also
  56 .B LINUX_REBOOT_MAGIC2A
  57 (that is, 85072278)
  58 and since 2.1.97 also
  59 .B LINUX_REBOOT_MAGIC2B
  60 (that is, 369367448)
  61 and since 2.5.71 also
  62 .B LINUX_REBOOT_MAGIC2C
  63 (that is, 537993216)
  64 are permitted as values for
  65 .IR magic2 .
  66 (The hexadecimal values of these constants are meaningful.)
  67 .PP
  68 The
  69 .I cmd
  70 argument can have the following values:
  71 .TP
  72 .B LINUX_REBOOT_CMD_CAD_OFF
  73 .RB ( RB_DISABLE_CAD ,
  74 0).
  75 CAD is disabled.
  76 This means that the CAD keystroke will cause a
  77 .B SIGINT
  78 signal to be
  79 sent to init (process 1), whereupon this process may decide upon a
  80 proper action (maybe: kill all processes, sync, reboot).
  81 .TP
  82 .B LINUX_REBOOT_CMD_CAD_ON
  83 .RB ( RB_ENABLE_CAD ,
  84 0x89abcdef).
  85 CAD is enabled.
  86 This means that the CAD keystroke will immediately cause
  87 the action associated with
  88 .BR LINUX_REBOOT_CMD_RESTART .
  89 .TP
  90 .B LINUX_REBOOT_CMD_HALT
  91 .RB ( RB_HALT_SYSTEM ,
  92 0xcdef0123; since Linux 1.1.76).
  93 The message "System halted." is printed, and the system is halted.
  94 Control is given to the ROM monitor, if there is one.
  95 If not preceded by a
  96 .BR sync (2),
  97 data will be lost.
  98 .TP
  99 .B LINUX_REBOOT_CMD_KEXEC
 100 .RB ( RB_KEXEC ,
 101 0x45584543, since Linux 2.6.13).
 102 Execute a kernel that has been loaded earlier with
 103 .BR kexec_load (2).
 104 This option is available only if the kernel was configured with
 105 .BR CONFIG_KEXEC .
 106 .TP
 107 .B LINUX_REBOOT_CMD_POWER_OFF
 108 .RB ( RB_POWER_OFF ,
 109 0x4321fedc; since Linux 2.1.30).
 110 The message "Power down." is printed, the system is stopped,
 111 and all power is removed from the system, if possible.
 112 If not preceded by a
 113 .BR sync (2),
 114 data will be lost.
 115 .TP
 116 .B LINUX_REBOOT_CMD_RESTART
 117 .RB ( RB_AUTOBOOT ,
 118 0x1234567).
 119 The message "Restarting system." is printed, and a default
 120 restart is performed immediately.
 121 If not preceded by a
 122 .BR sync (2),
 123 data will be lost.
 124 .TP
 125 .B LINUX_REBOOT_CMD_RESTART2
 126 (0xa1b2c3d4; since Linux 2.1.30).
 127 The message "Restarting system with command \(aq%s\(aq" is printed,
 128 and a restart (using the command string given in
 129 .IR arg )
 130 is performed immediately.
 131 If not preceded by a
 132 .BR sync (2),
 133 data will be lost.
 134 .TP
 135 .B LINUX_REBOOT_CMD_SW_SUSPEND
 136 .RB ( RB_SW_SUSPEND ,
 137 0xd000fce1; since Linux 2.5.18).
 138 The system is suspended (hibernated) to disk.
 139 This option is available only if the kernel was configured with
 140 .BR CONFIG_HIBERNATION .
 141 .PP
 142 Only the superuser may call
 143 .BR reboot ().
 144 .PP
 145 The precise effect of the above actions depends on the architecture.
 146 For the i386 architecture, the additional argument does not do
 147 anything at present (2.1.122), but the type of reboot can be
 148 determined by kernel command-line arguments ("reboot=...") to be
 149 either warm or cold, and either hard or through the BIOS.
 150 .\"
 151 .SS Behavior inside PID namespaces
 152 .\" commit cf3f89214ef6a33fad60856bc5ffd7bb2fc4709b
 153 .\" see also commit 923c7538236564c46ee80c253a416705321f13e3
 154 Since Linux 3.4,
 155 if
 156 .BR reboot ()
 157 is called
 158 from a PID namespace other than the initial PID namespace
 159 with one of the
 160 .I cmd
 161 values listed below,
 162 it performs a "reboot" of that namespace:
 163 the "init" process of the PID namespace is immediately terminated,
 164 with the effects described in
 165 .BR pid_namespaces (7).
 166 .PP
 167 The values that can be supplied in
 168 .I cmd
 169 when calling
 170 .BR reboot ()
 171 in this case are as follows:
 172 .TP
 173 .BR LINUX_REBOOT_CMD_RESTART ", " LINUX_REBOOT_CMD_RESTART2
 174 The "init" process is terminated,
 175 and
 176 .BR wait (2)
 177 in the parent process reports that the child was killed with a
 178 .B SIGHUP
 179 signal.
 180 .TP
 181 .BR LINUX_REBOOT_CMD_POWER_OFF ", " LINUX_REBOOT_CMD_HALT
 182 The "init" process is terminated,
 183 and
 184 .BR wait (2)
 185 in the parent process reports that the child was killed with a
 186 .B SIGINT
 187 signal.
 188 .PP
 189 For the other
 190 .I cmd
 191 values,
 192 .BR reboot ()
 193 returns \-1 and
 194 .I errno
 195 is set to
 196 .BR EINVAL .
 197 .SH RETURN VALUE
 198 For the values of
 199 .I cmd
 200 that stop or restart the system,
 201 a successful call to
 202 .BR reboot ()
 203 does not return.
 204 For the other
 205 .I cmd
 206 values, zero is returned on success.
 207 In all cases, \-1 is returned on failure, and
 208 .I errno
 209 is set to indicate the error.
 210 .SH ERRORS
 211 .TP
 212 .B EFAULT
 213 Problem with getting user-space data under
 214 .BR LINUX_REBOOT_CMD_RESTART2 .
 215 .TP
 216 .B EINVAL
 217 Bad magic numbers or \fIcmd\fP.
 218 .TP
 219 .B EPERM
 220 The calling process has insufficient privilege to call
 221 .BR reboot ();
 222 the caller must have the
 223 .B CAP_SYS_BOOT
 224 inside its user namespace.
 225 .SH STANDARDS
 226 .BR reboot ()
 227 is Linux-specific,
 228 and should not be used in programs intended to be portable.
 229 .SH SEE ALSO
 230 .BR systemctl (1),
 231 .BR systemd (1),
 232 .BR kexec_load (2),
 233 .BR sync (2),
 234 .BR bootparam (7),
 235 .BR capabilities (7),
 236 .BR ctrlaltdel (8),
 237 .BR halt (8),
 238 .BR shutdown (8)