usr/src/man/man2/pset_create.2

   1 '\" te
   2 .\" Copyright (c) 2008, 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 PSET_CREATE 2 "Feb 22, 2008"
   7 .SH NAME
   8 pset_create, pset_destroy, pset_assign \- manage sets of processors
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/pset.h>
  13
  14 \fBint\fR \fBpset_create\fR(\fBpsetid_t *\fR\fInewpset\fR);
  15 .fi
  16
  17 .LP
  18 .nf
  19 \fBint\fR \fBpset_destroy\fR(\fBpsetid_t\fR \fIpset\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBint\fR \fBpset_assign\fR(\fBpsetid_t\fR \fIpset\fR, \fBprocessorid_t\fR \fIcpu\fR, \fBpsetid_t *\fR\fIopset\fR);
  25 .fi
  26
  27 .SH DESCRIPTION
  28 .sp
  29 .LP
  30 These functions control the creation and management of sets of processors.
  31 Processor sets allow a subset of the system's processors to be set aside for
  32 exclusive use by specified \fBLWP\fRs and processes. The binding of \fBLWP\fRs
  33 and processes to processor sets is controlled by \fBpset_bind\fR(2).
  34 .sp
  35 .LP
  36 The \fBpset_create()\fR function creates an empty processor set that contains
  37 no processors.  On successful return, \fInewpset\fR will contain the \fBID\fR
  38 of the new processor set.
  39 .sp
  40 .LP
  41 The \fBpset_destroy()\fR function destroys the processor set \fIpset\fR,
  42 releasing its constituent processors and processes. If \fIpset\fR is
  43 \fBPS_MYID\fR, the processor set to which the caller is bound is destroyed.
  44 .sp
  45 .LP
  46 The \fBpset_assign()\fR function assigns the processor \fIcpu\fR to the
  47 processor set \fIpset\fR. A processor that has been assigned to a processor set
  48 will run only \fBLWP\fRs and processes that have been explicitly bound to that
  49 processor set, unless another \fBLWP\fR requires a resource that is only
  50 available on that processor.
  51 .sp
  52 .LP
  53 On successful return, if \fIopset\fR is non-null, \fIopset\fR will contain the
  54 processor set \fBID\fR of the former processor set of the processor.
  55 .sp
  56 .LP
  57 If \fIpset\fR is \fBPS_NONE\fR, \fBpset_assign()\fR releases processor
  58 \fIcpu\fR from its current processor set.
  59 .sp
  60 .LP
  61 If \fIpset\fR is \fBPS_QUERY\fR, \fBpset_assign()\fR makes no change to
  62 processor sets, but returns the current processor set \fBID\fR of processor
  63 \fIcpu\fR in \fIopset\fR.
  64 .sp
  65 .LP
  66 If \fIpset\fR is \fBPS_MYID\fR, processor \fIcpu\fR is assigned to the
  67 processor set to which the caller belongs. If the caller does not belong to a
  68 processor set, processor \fIcpu\fR is released from its current processor set.
  69 .sp
  70 .LP
  71 These functions are restricted to privileged processes, except for
  72 \fBpset_assign()\fR when \fIpset\fR is \fBPS_QUERY\fR.
  73 .SH RETURN VALUES
  74 .sp
  75 .LP
  76 Upon successful completion, these functions return \fB0\fR. Otherwise,
  77 \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error.
  78 .SH ERRORS
  79 .sp
  80 .LP
  81 These functions will fail if:
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fBEBUSY\fR\fR
  86 .ad
  87 .RS 11n
  88 The processor could not be moved to the specified processor set.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fBEFAULT\fR\fR
  95 .ad
  96 .RS 11n
  97 The location pointed to by \fInewpset\fR was not writable by the user, or the
  98 location pointed to by \fIopset\fR was not \fINULL\fR and not writable by the
  99 user.
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fBEINVAL\fR\fR
 106 .ad
 107 .RS 11n
 108 The specified processor does not exist, the specified processor  is not
 109 on-line, or an invalid processor set was specified.
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBENOMEM\fR\fR
 116 .ad
 117 .RS 11n
 118 There was insufficient space for \fBpset_create\fR to create a new processor
 119 set.
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fBENOTSUP\fR\fR
 126 .ad
 127 .RS 11n
 128 The pools facility is active. See \fBpooladm\fR(1M) and
 129 \fBpool_set_status\fR(3POOL) for information about enabling and disabling the
 130 pools facility.
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBEPERM\fR\fR
 137 .ad
 138 .RS 11n
 139 The {\fBPRIV_SYS_RES_CONFIG\fR} privilege is not asserted in the effective set
 140 of the calling process.
 141 .RE
 142
 143 .SH ATTRIBUTES
 144 .sp
 145 .LP
 146 See \fBattributes\fR(5) for descriptions of the following attributes:
 147 .sp
 148
 149 .sp
 150 .TS
 151 box;
 152 c | c
 153 l | l .
 154 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 155 _
 156 Interface Stability     Committed
 157 _
 158 MT-Level        Async-Signal-Safe
 159 .TE
 160
 161 .SH SEE ALSO
 162 .sp
 163 .LP
 164 \fBpooladm\fR(1M), \fBpsradm\fR(1M), \fBpsrinfo\fR(1M), \fBpsrset\fR(1M),
 165 \fBp_online\fR(2), \fBprocessor_bind\fR(2), \fBpset_bind\fR(2),
 166 \fBpset_info\fR(2), \fBpool_set_status\fR(3POOL), \fBpset_getloadavg\fR(3C),
 167 \fBattributes\fR(5), \fBprivileges\fR(5)
 168 .SH NOTES
 169 .sp
 170 .LP
 171 The processor set type of \fBPS_SYSTEM\fR is no longer supported.
 172 .sp
 173 .LP
 174 Processors with \fBLWP\fRs bound to them using \fBprocessor_bind\fR(2) cannot
 175 be assigned to a new processor set. If  this is attempted, \fBpset_assign()\fR
 176 will fail and set \fBerrno\fR to \fBEBUSY\fR.