usr/src/man/man2/uadmin.2

   1 '\" te
   2 .\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   5 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
   6 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH UADMIN 2 "Mar 25, 2009"
   8 .SH NAME
   9 uadmin \- administrative control
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/uadmin.h>
  14
  15 \fBint\fR \fBuadmin\fR(\fBint\fR \fIcmd\fR, \fBint\fR \fIfcn\fR, \fBuintptr_t\fR \fImdep\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBuadmin()\fR function provides control for basic administrative
  22 functions. This function is tightly coupled to the system administrative
  23 procedures and is not intended for general use. The argument \fImdep\fR is
  24 provided for machine-dependent use and is not defined here. It should be
  25 initialized to \fINULL\fR if not used.
  26 .sp
  27 .LP
  28 As specified by \fIcmd\fR, the following commands are available:
  29 .sp
  30 .ne 2
  31 .na
  32 \fB\fBA_SHUTDOWN\fR\fR
  33 .ad
  34 .RS 14n
  35 The system is shut down. All user processes are killed, the buffer cache is
  36 flushed, and the root file system is unmounted. The action to be taken after
  37 the system has been shut down is specified by \fIfcn\fR. The functions are
  38 generic; the hardware capabilities vary on  specific machines.
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fBAD_HALT\fR\fR
  43 .ad
  44 .RS 17n
  45 Halt the processor(s).
  46 .RE
  47
  48 .sp
  49 .ne 2
  50 .na
  51 \fB\fBAD_POWEROFF\fR\fR
  52 .ad
  53 .RS 17n
  54 Halt the processor(s) and turn off the power.
  55 .RE
  56
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fBAD_BOOT\fR\fR
  61 .ad
  62 .RS 17n
  63 Reboot the system, using the kernel file.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fBAD_IBOOT\fR\fR
  70 .ad
  71 .RS 17n
  72 Interactive reboot; user is prompted for bootable program name.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBAD_FASTREBOOT\fR\fR
  79 .ad
  80 .RS 17n
  81 Bypass BIOS and boot loader
  82 .RE
  83
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBA_REBOOT\fR\fR
  90 .ad
  91 .RS 14n
  92 The system stops immediately without any further processing. The action to be
  93 taken next is specified by \fIfcn\fR as above.
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBA_DUMP\fR\fR
 100 .ad
 101 .RS 14n
 102 The system is forced to panic immediately without any further processing and a
 103 crash dump is written to the dump device (see \fBdumpadm\fR(1M)).  The action
 104 to be taken next is specified by \fIfcn\fR, as above.
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBA_REMOUNT\fR\fR
 111 .ad
 112 .RS 14n
 113 The root file system is mounted again after having been fixed. This should be
 114 used only during the startup process.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBA_FREEZE\fR\fR
 121 .ad
 122 .RS 14n
 123 Suspend the whole system.  The system state is preserved in the state file. The
 124 following subcommands, specified by \fIfcn\fR, are available.
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fBAD_SUSPEND_TO_DISK\fR\fR
 129 .ad
 130 .sp .6
 131 .RS 4n
 132 Save the system state to the state file. This subcommand is equivalent to ACPI
 133 state S4.
 134 .RE
 135
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fBAD_CHECK_SUSPEND_TO_DISK\fR\fR
 140 .ad
 141 .sp .6
 142 .RS 4n
 143 Check if your system supports suspend to disk. Without performing a system
 144 suspend/resume, this subcommand checks if this feature is currently available
 145 on your system.
 146 .RE
 147
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fBAD_SUSPEND_TO_RAM\fR\fR
 152 .ad
 153 .sp .6
 154 .RS 4n
 155 Save the system state to memory This subcommand is equivalent to ACPI state S3.
 156 .RE
 157
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fBAD_CHECK_SUSPEND_TO_RAM\fR\fR
 162 .ad
 163 .sp .6
 164 .RS 4n
 165 Check if your system supports suspend to memory. Without performing a system
 166 suspend/resume, this subcommand checks if this feature is currently available
 167 on your system.
 168 .RE
 169
 170 The following subcommands, specified by \fIfcn\fR, are obsolete and might be
 171 removed in a subsequent release:
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fBAD_COMPRESS\fR\fR
 176 .ad
 177 .sp .6
 178 .RS 4n
 179 Save the system state to the state file with compression of data. This
 180 subcommand has been replaced by \fBAD_SUSPEND_TO_DISK\fR, which should be used
 181 instead.
 182 .RE
 183
 184 .sp
 185 .ne 2
 186 .na
 187 \fB\fBAD_CHECK\fR\fR
 188 .ad
 189 .sp .6
 190 .RS 4n
 191 Check if your system supports suspend and resume.  Without performing a  system
 192 suspend/resume, this command checks if this feature is currently available on
 193 your system. This subcommand has been replaced by
 194 \fBAD_CHECK_SUSPEND_TO_DISK\fR, which should be used instead.
 195 .RE
 196
 197 .sp
 198 .ne 2
 199 .na
 200 \fB\fBAD_FORCE\fR\fR
 201 .ad
 202 .sp .6
 203 .RS 4n
 204 Force \fBAD_COMPRESS\fR even when threads of user applications are not
 205 suspendable. This subcommand should never be used, as it might result in
 206 undefined behavior.
 207 .RE
 208
 209 .RE
 210
 211 .SH RETURN VALUES
 212 .sp
 213 .LP
 214 Upon successful completion, the value returned depends on \fIcmd\fR as follows:
 215 .sp
 216 .ne 2
 217 .na
 218 \fB\fBA_SHUTDOWN\fR\fR
 219 .ad
 220 .RS 14n
 221 Never returns.
 222 .RE
 223
 224 .sp
 225 .ne 2
 226 .na
 227 \fB\fBA_REBOOT\fR\fR
 228 .ad
 229 .RS 14n
 230 Never returns.
 231 .RE
 232
 233 .sp
 234 .ne 2
 235 .na
 236 \fB\fBA_FREEZE\fR\fR
 237 .ad
 238 .RS 14n
 239 \fB0\fR upon resume.
 240 .RE
 241
 242 .sp
 243 .ne 2
 244 .na
 245 \fB\fBA_REMOUNT\fR\fR
 246 .ad
 247 .RS 14n
 248 \fB0\fR.
 249 .RE
 250
 251 .sp
 252 .LP
 253 Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the
 254 error.
 255 .SH ERRORS
 256 .sp
 257 .LP
 258 The \fBuadmin()\fR function will fail if:
 259 .sp
 260 .ne 2
 261 .na
 262 \fB\fBEBUSY\fR\fR
 263 .ad
 264 .RS 11n
 265 Suspend is already in progress.
 266 .RE
 267
 268 .sp
 269 .ne 2
 270 .na
 271 \fB\fBEINVAL\fR\fR
 272 .ad
 273 .RS 11n
 274 The \fIcmd\fR argument is invalid.
 275 .RE
 276
 277 .sp
 278 .ne 2
 279 .na
 280 \fB\fBENOMEM\fR\fR
 281 .ad
 282 .RS 11n
 283 Suspend/resume ran out of physical memory.
 284 .RE
 285
 286 .sp
 287 .ne 2
 288 .na
 289 \fB\fBENOSPC\fR\fR
 290 .ad
 291 .RS 11n
 292 Suspend/resume could not allocate enough space on the root file system to store
 293 system information.
 294 .RE
 295
 296 .sp
 297 .ne 2
 298 .na
 299 \fB\fBENOTSUP\fR\fR
 300 .ad
 301 .RS 11n
 302 Suspend/resume is not supported on this platform or the command specified by
 303 \fIcmd\fR is not allowed.
 304 .RE
 305
 306 .sp
 307 .ne 2
 308 .na
 309 \fB\fBENXIO\fR\fR
 310 .ad
 311 .RS 11n
 312 Unable to successfully suspend system.
 313 .RE
 314
 315 .sp
 316 .ne 2
 317 .na
 318 \fB\fBEPERM\fR\fR
 319 .ad
 320 .RS 11n
 321 The {\fBPRIV_SYS_CONFIG\fR} privilege is not asserted in the effective set of
 322 the calling process.
 323 .RE
 324
 325 .SH ATTRIBUTES
 326 .sp
 327 .LP
 328 See \fBattributes\fR(5) for descriptions of the following attributes:
 329 .sp
 330
 331 .sp
 332 .TS
 333 box;
 334 c | c
 335 l | l .
 336 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 337 _
 338 Interface Stability     See below.
 339 .TE
 340
 341 .sp
 342 .LP
 343 The \fBA_FREEZE\fR command and its subcommands are Committed.
 344 .SH SEE ALSO
 345 .sp
 346 .LP
 347 \fBdumpadm\fR(1M), \fBhalt\fR(1M), \fBkernel\fR(1M), \fBreboot\fR(1M),
 348 \fBuadmin\fR(1M), \fBattributes\fR(5), \fBprivileges\fR(5)
 349 .SH WARNINGS
 350 .sp
 351 .LP
 352 Shutting down or halting the system by means of \fBuadmin\fR(1M) does not
 353 update the  boot  archive.  Avoid  using  this command after
 354 .RS +4
 355 .TP
 356 .ie t \(bu
 357 .el o
 358 editing of files such as \fB/etc/system\fR
 359 .RE
 360 .RS +4
 361 .TP
 362 .ie t \(bu
 363 .el o
 364 installing new driver binaries or kernel binaries
 365 .RE
 366 .RS +4
 367 .TP
 368 .ie t \(bu
 369 .el o
 370 updating existing driver binaries or kernel binaries.
 371 .RE
 372 .sp
 373 .LP
 374 Use \fBreboot\fR(1M) or \fBhalt\fR(1M) instead.