p_online(2)                                                        System Calls                                                        p_online(2)

NAME

       p_online - return or change processor operational status

SYNOPSIS

       #include <sys/types.h>
       #include <sys/processor.h>

       int p_online(processorid_t processorid, int flag);

DESCRIPTION

       The  p_online()  function  changes or returns the operational status of processors. The state of the processor specified by the processorid
       argument is changed to the state represented by the flag argument.

       Legal values for flag are P_STATUS, P_ONLINE, P_OFFLINE, P_NOINTR, P_FAULTED, P_SPARE, and P_FORCED.

       When flag is P_STATUS, no processor status change occurs, but the current processor status is returned.

       The P_ONLINE, P_OFFLINE, P_NOINTR, P_FAULTED, and P_SPARE values for flag refer to valid processor states.  The  P_OFFLINE,  P_SPARE,   and
       P_FAULTED processor states can be combined with the P_FORCED flag.

       A  processor  in the P_ONLINE state is allowed to process LWPs (lightweight processes) and perform system activities. The processor is also
       interruptible by I/O devices attached to the system.

       A processor in the P_OFFLINE state is not allowed to process LWPs. The processor is as inactive as possible. If the hardware supports  such
       a feature, the processor is not interruptible by attached I/O devices.

       A  processor  in the P_NOINTR state is allowed to process LWPs, but it is not interruptible by attached I/O devices. Typically, interrupts,
       when they occur are routed to other processors in the system. Not all systems support putting a processor into the P_NOINTR  state.  It  is
       not  permitted  to  put  all the processors of a system into the P_NOINTR state. At least one processor must always be available to service
       system clock interrupts.

       A processor in the P_SPARE state is not allowed to process LWPs. In many respects the P_SPARE state is similiar to the P_OFFLINE state, but
       describes a processor that is available for reactivation by management tools without administrator intervention.

       A processor in the P_FAULTED state is not allowed to process LWPs. In many respects the P_FAULTED state is similiar to the P_OFFLINE state,
       but describes a processor that has been diagnosed as faulty. The privileged caller can change the state of the processor from P_FAULTED  to
       any  of the other states, but since the processor might generate additional errors, electing to reactivate such a processor should be care-
       fully considered.

       Forced processor state transition can be requested if a new processor state is specified with  the  bitwise-inclusive  OR  of  the  special
       P_FORCED  flag.  Forcing transition of a processor to the P_OFFLINE, P_SPARE, or P_FAULTED state revokes processor bindings for all threads
       that were previously bound to that processor with processor_bind(2). There is no guarantee that a forced processor state transition  always
       succeeds.

       Processor  numbers are integers, greater than or equal to 0, and are defined by the hardware platform.  Processor numbers are not necessar-
       ily contiguous, but "not too sparse."  Processor numbers should always be printed in decimal.

       The maximum possible processorid value can be determined by calling sysconf(_SC_CPUID_MAX). The list of  valid  processor  numbers  can  be
       determined  by  calling  p_online()  with  processorid values from 0 to the maximum returned by sysconf(_SC_CPUID_MAX). The EINVAL error is
       returned for invalid processor numbers.  See EXAMPLES below.

RETURN VALUES

       On successful completion, the value returned is the previous state of the processor, P_ONLINE, P_OFFLINE, P_NOINTR, P_FAULTED, P_SPARE,  or
       P_POWEROFF. Otherwise, -1 is returned, the CPU state remains unchanged, and  errno is set to indicate the error.

ERRORS

       The p_online() function will fail if:

       EBUSY           The  flag  was  P_OFFLINE  or  P_SPARE and the specified processor is the only on-line processor, there are currently  LWPs
                       bound to the processor, or the processor performs some essential function that cannot be performed by another processor.

                       The flag was P_NOINTR and the specified processor is the only interruptible processor in the system, or it  handles  inter-
                       rupts that cannot be handled by another processor.

                       The specified processor is powered off and cannot be powered on because some platform- specific resource is not available.

       EINVAL          A non-existent processor ID was specified or  flag was invalid.

                       The  caller  is  in a non-global zone, the pools facility is active, and the processor is not a member of the zone's pool's
                       processor set.

       ENOTSUP         The specified processor is powered off, and the platform does not support power on of individual processors.

       EPERM           The flag was not P_STATUS and the {PRIV_SYS_RES_CONFIG} privilege is not asserted in  the  effective  set  of  the  calling
                       process.

EXAMPLES

       Example 1: List the legal processor numbers.

       The following code sample will list the legal processor numbers:

       #include <sys/unistd.h>
       #include <sys/processor.h>
       #include <sys/types.h>
       #include <stdio.h>
       #include <errno.h>

       int
       main()
       {
               processorid_t i, cpuid_max;
               cpuid_max = sysconf(_SC_CPUID_MAX);
               for (i = 0; i <= cpuid_max; i++) {
                     if (p_online(i, P_STATUS) != -1)
                               printf("processor %d present
", i);
               }
               return(0);
       }

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE         |      ATTRIBUTE VALUE        |
       +-----------------------------+-----------------------------+
       |MT-Level                     |MT-Safe                      |
       +-----------------------------+-----------------------------+

SEE ALSO

       pooladm(1M), psradm(1M), psrinfo(1M), zoneadm(1M), processor_bind(2), processor_info(2), pset_create(2), sysconf(3C), attributes(5), privi-
       leges(5)

SunOS 5.10                                                          16 Aug 2004                                                        p_online(2)