share/man/man2/p_online.2

   1 '\" te
   2 .\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" 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.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" 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 the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH P_ONLINE 2 "April 9, 2016"
   7 .SH NAME
   8 p_online \- return or change processor operational status
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/types.h>
  13 #include <sys/processor.h>
  14
  15 \fBint\fR \fBp_online\fR(\fBprocessorid_t\fR \fIprocessorid\fR, \fBint\fR \fIflag\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .LP
  20 The \fBp_online()\fR function changes or returns the operational status of
  21 processors. The state of the processor specified by the \fIprocessorid\fR
  22 argument is changed to the state represented by the \fIflag\fR argument.
  23 .sp
  24 .LP
  25 Legal values for \fIflag\fR are \fBP_STATUS\fR, \fBP_ONLINE\fR,
  26 \fBP_OFFLINE\fR, \fBP_NOINTR\fR, \fBP_FAULTED\fR, \fBP_SPARE\fR, and
  27 \fBP_FORCED\fR.
  28 .sp
  29 .LP
  30 When \fIflag\fR is \fBP_STATUS,\fR no processor status change occurs, but the
  31 current processor status is returned.
  32 .sp
  33 .LP
  34 The \fBP_ONLINE\fR, \fBP_OFFLINE\fR, \fBP_NOINTR\fR, \fBP_FAULTED\fR, and
  35 \fBP_SPARE\fR values for \fIflag\fR refer to valid processor states. The
  36 \fBP_OFFLINE\fR, \fBP_SPARE\fR,  and \fBP_FAULTED\fR processor states can be
  37 combined with the \fBP_FORCED\fR flag.
  38 .sp
  39 .LP
  40 A processor in the \fBP_ONLINE\fR state is allowed to process \fBLWPs\fR
  41 (lightweight processes) and perform system activities. The processor is also
  42 interruptible by I/O devices attached to the system.
  43 .sp
  44 .LP
  45 A processor in the \fBP_OFFLINE\fR state is not allowed to process \fBLWPs\fR.
  46 The processor is as inactive as possible. If the hardware supports such a
  47 feature, the processor is not interruptible by attached I/O devices.
  48 .sp
  49 .LP
  50 A processor in the \fBP_NOINTR\fR state is allowed to process \fBLWPs\fR, but
  51 it is not interruptible by attached I/O devices. Typically, interrupts, when
  52 they occur are routed to other processors in the system. Not all systems
  53 support putting a processor into the \fBP_NOINTR\fR state. It is not permitted
  54 to put all the processors of a system into the \fBP_NOINTR\fR state. At least
  55 one processor must always be available to service system clock interrupts.
  56 .sp
  57 .LP
  58 A processor in the \fBP_SPARE\fR state is not allowed to process LWPs. In many
  59 respects, the \fBP_SPARE\fR state is similar to the \fBP_OFFLINE\fR state, but
  60 describes a processor that is available for reactivation by management tools
  61 without administrator intervention.
  62 .sp
  63 .LP
  64 A processor in the \fBP_FAULTED\fR state is not allowed to process LWPs. In
  65 many respects, the \fBP_FAULTED\fR state is similar to the \fBP_OFFLINE\fR
  66 state, but describes a processor that has been diagnosed as faulty. The
  67 privileged caller can change the state of the processor from \fBP_FAULTED\fR to
  68 any of the other states, but since the processor might generate additional
  69 errors, electing to reactivate such a processor should be carefully considered.
  70 .sp
  71 .LP
  72 Forced processor state transition can be requested if a new processor state is
  73 specified with the bitwise-inclusive OR of the special \fBP_FORCED\fR flag.
  74 Forcing transition of a processor to the \fBP_OFFLINE\fR, \fBP_SPARE\fR, or
  75 \fBP_FAULTED\fR state revokes processor bindings for all threads that were
  76 previously bound to that processor with \fBprocessor_bind\fR(2). There is no
  77 guarantee that a forced processor state transition always succeeds.
  78 .sp
  79 .LP
  80 Processor numbers are integers, greater than or equal to 0, and are defined by
  81 the hardware platform.  Processor numbers are not necessarily contiguous, but
  82 "not too sparse."  Processor numbers should always be printed in decimal.
  83 .sp
  84 .LP
  85 The maximum possible \fIprocessorid\fR value can be determined by calling
  86 \fBsysconf(_SC_CPUID_MAX)\fR. The list of valid processor numbers can be
  87 determined by calling \fBp_online()\fR with \fIprocessorid\fR values from 0 to
  88 the maximum returned by \fBsysconf(_SC_CPUID_MAX)\fR. The \fBEINVAL\fR error is
  89 returned for invalid processor numbers.  See \fBEXAMPLES\fR below.
  90 .SH RETURN VALUES
  91 .LP
  92 On successful completion, the value returned is the previous state of the
  93 processor, \fBP_ONLINE\fR, \fBP_OFFLINE\fR, \fBP_NOINTR\fR, \fBP_FAULTED\fR,
  94 \fBP_SPARE\fR, or \fBP_POWEROFF\fR. Otherwise, \fB\(mi1\fR is returned, the CPU
  95 state remains unchanged, and  \fBerrno\fR is set to indicate the error.
  96 .SH ERRORS
  97 .LP
  98 The \fBp_online()\fR function will fail if:
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBEBUSY\fR\fR
 103 .ad
 104 .RS 11n
 105 The \fIflag\fR was \fBP_OFFLINE\fR or \fBP_SPARE\fR and the specified processor
 106 is the only on-line processor, there are currently  \fBLWPs\fR bound to the
 107 processor, or the processor performs some essential function that cannot be
 108 performed by another processor.
 109 .sp
 110 The \fIflag\fR was \fBP_NOINTR\fR and the specified processor is the only
 111 interruptible processor in the system, or it handles interrupts that cannot be
 112 handled by another processor.
 113 .sp
 114 The specified processor is powered off and cannot be powered on because some
 115 platform- specific resource is not available.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBEINVAL\fR\fR
 122 .ad
 123 .RS 11n
 124 A non-existent processor \fBID\fR was specified or  \fIflag\fR was invalid.
 125 .sp
 126 The caller is in a non-global zone, the pools facility is active, and the
 127 processor is not a member of the zone's pool's processor set.
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBENOTSUP\fR\fR
 134 .ad
 135 .RS 11n
 136 The specified processor is powered off, and the platform does not support power
 137 on of individual processors.
 138 .RE
 139
 140 .sp
 141 .ne 2
 142 .na
 143 \fB\fBEPERM\fR\fR
 144 .ad
 145 .RS 11n
 146 The flag was not \fBP_STATUS\fR and the {\fBPRIV_SYS_RES_CONFIG\fR} privilege
 147 is not asserted in the effective set of the calling process.
 148 .RE
 149
 150 .SH EXAMPLES
 151 .LP
 152 \fBExample 1 \fRList the legal processor numbers.
 153 .sp
 154 .LP
 155 The following code sample will list the legal processor numbers:
 156
 157 .sp
 158 .in +2
 159 .nf
 160 #include <sys/unistd.h>
 161 #include <sys/processor.h>
 162 #include <sys/types.h>
 163 #include <stdio.h>
 164 #include <unistd.h>
 165 #include <errno.h>
 166
 167 int
 168 main()
 169 {
 170         processorid_t i, cpuid_max;
 171         cpuid_max = sysconf(_SC_CPUID_MAX);
 172         for (i = 0; i <= cpuid_max; i++) {
 173               if (p_online(i, P_STATUS) != -1)
 174                         printf("processor %d present\en", i);
 175         }
 176         return (0);
 177 }
 178 .fi
 179 .in -2
 180
 181 .SH ATTRIBUTES
 182 .LP
 183 See \fBattributes\fR(5) for descriptions of the following attributes:
 184 .sp
 185
 186 .sp
 187 .TS
 188 box;
 189 c | c
 190 l | l .
 191 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 192 _
 193 MT-Level        MT-Safe
 194 .TE
 195
 196 .SH SEE ALSO
 197 .LP
 198 \fBpooladm\fR(8), \fBpsradm\fR(8), \fBpsrinfo\fR(8), \fBzoneadm\fR(8),
 199 \fBprocessor_bind\fR(2), \fBprocessor_info\fR(2), \fBpset_create\fR(2),
 200 \fBsysconf\fR(3C), \fBattributes\fR(5), \fBprivileges\fR(5)