usr/src/man/man1m/pbind.1m

   1 '\" te
   2 .\"  Copyright (c) 2008, Sun Microsystems, Inc.
   3 .\"  All Rights Reserved
   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.
   5 .\" 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.
   6 .\" 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]
   7 .TH PBIND 1M "Feb 25, 2008"
   8 .SH NAME
   9 pbind \- control and query bindings of processes or LWPs
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBpbind\fR \fB-b\fR \fIprocessor_id\fR \fIpid\fR [\fI/lwpid\fR]...
  14 .fi
  15
  16 .LP
  17 .nf
  18 \fBpbind\fR [\fB-q\fR] [\fIpid\fR [\fI/lwpid\fR]]...
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBpbind\fR \fB-Q\fR [\fIprocessor_id\fR]...
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBpbind\fR \fB-u\fR \fIpid\fR [\fI/lwpid\fR]...
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBpbind\fR \fB-U\fR [\fIprocessor_id\fR]...
  34 .fi
  35
  36 .SH DESCRIPTION
  37 .sp
  38 .LP
  39 \fBpbind\fR controls and queries bindings of processes and LWPs (lightweight
  40 processes) to processors. \fBpbind\fR can also remove processor bindings that
  41 were previously established.
  42 .sp
  43 .LP
  44 When an LWP is bound to a processor, it will be executed only by that processor
  45 except when the LWP requires a resource that is provided only by another
  46 processor. The binding is not exclusive, that is, the processor is free to
  47 execute other LWPs as well.
  48 .sp
  49 .LP
  50 Bindings are inherited, so new LWPs and processes created by a bound LWP will
  51 have the same binding. Binding an interactive shell to a processor, for
  52 example, binds all commands executed by the shell.
  53 .sp
  54 .LP
  55 Superusers may bind or unbind any process or LWP, while other users can bind or
  56 unbind any process or LWP for which they have permission to signal, that is,
  57 any process that has the same effective user ID as the user.
  58 .SH OPTIONS
  59 .sp
  60 .LP
  61 The following options are supported:
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fB-b\fR \fIprocessor_id\fR\fR
  66 .ad
  67 .sp .6
  68 .RS 4n
  69 Binds all or a subset of the LWPs of the specified processes to the processor
  70 \fIprocessor_id\fR. Specify \fIprocessor_id\fR as the processor \fBID\fR of the
  71 processor to be controlled or queried. \fIprocessor_id\fR must be present and
  72 on-line. Use the \fBpsrinfo\fR command to determine whether or not
  73 \fIprocessor_id\fR is present and on-line. See \fBpsrinfo\fR(1M).
  74 .RE
  75
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fB-q\fR\fR
  80 .ad
  81 .sp .6
  82 .RS 4n
  83 Displays the bindings of the specified processes or of all processes. If a
  84 process is composed of multiple LWPs which have different bindings and the LWPs
  85 are not explicitly specified, the bindings of only one of the bound LWPs will
  86 be displayed. The bindings of a subset of LWPs can be displayed by appending
  87 "/lwpids" to the process \fBID\fRs. Multiple LWPs may be selected using "-" and
  88 "," delimiters. See EXAMPLES.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fB-Q\fR\fR
  95 .ad
  96 .sp .6
  97 .RS 4n
  98 Displays the LWPs bound to the specified list of processors, or all LWPs with
  99 processor bindings. For processes composed of multiple LWPs, the bindings of
 100 individual LWPs will be displayed.
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fB-u\fR\fR
 107 .ad
 108 .sp .6
 109 .RS 4n
 110 Removes the bindings of all or a subset of the LWPs of the specified processes,
 111 allowing them to be executed on any on-line processor.
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fB-U\fR\fR
 118 .ad
 119 .sp .6
 120 .RS 4n
 121 Removes the bindings of all LWPs bound to the specified list of processors, or
 122 to any processor if no argument is specified.
 123 .RE
 124
 125 .SH OPERANDS
 126 .sp
 127 .LP
 128 The following operands are supported:
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fIpid\fR\fR
 133 .ad
 134 .sp .6
 135 .RS 4n
 136 The process \fBID\fR of the process to be controlled or queried.
 137 .RE
 138
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fIlwpid\fR\fR
 143 .ad
 144 .sp .6
 145 .RS 4n
 146 The set of LWP IDs of the specified process to be controlled or queried. The
 147 syntax for selecting \fBLWP\fR \fBID\fRs is as follows:
 148 .sp
 149 .in +2
 150 .nf
 151 2,3,4-8       LWP IDs 2, 3, and 4 through 8
 152 -4            LWPs whose IDs are 4 or below
 153 4-            LWPs whose IDs are 4 or above
 154 .fi
 155 .in -2
 156
 157 .RE
 158
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fIprocessor_id\fR\fR
 163 .ad
 164 .sp .6
 165 .RS 4n
 166 The processor \fBID\fR of the processor to be controlled or queried.
 167 .RE
 168
 169 .SH EXAMPLES
 170 .LP
 171 \fBExample 1 \fRBinding Processes
 172 .sp
 173 .LP
 174 The following example binds processes 204 and 223 to processor 2:
 175
 176 .sp
 177 .in +2
 178 .nf
 179 example% \fBpbind -b 2 204 223\fR
 180 process id 204: was 2, now 2
 181 process id 223: was 3, now 2
 182 .fi
 183 .in -2
 184 .sp
 185
 186 .LP
 187 \fBExample 2 \fRUnbinding a Process
 188 .sp
 189 .LP
 190 The following example unbinds process 204:
 191
 192 .sp
 193 .in +2
 194 .nf
 195 example% \fBpbind -u 204\fR
 196 .fi
 197 .in -2
 198 .sp
 199
 200 .LP
 201 \fBExample 3 \fRQuerying Bindings
 202 .sp
 203 .LP
 204 The following example queries bindings. It demonstrates that process 1 is bound
 205 to processor 0, process 149 has at least one LWP bound to CPU3, and process 101
 206 has no bound LWPs.
 207
 208 .sp
 209 .in +2
 210 .nf
 211 example% \fBpbind -q 1 149 101\fR
 212 process id 1: 0
 213 process id 149: 3
 214 process id 101: not bound
 215 .fi
 216 .in -2
 217 .sp
 218
 219 .LP
 220 \fBExample 4 \fRQuerying LWP Bindings
 221 .sp
 222 .LP
 223 The following example queries bindings of LWPs. It demonstrates that LWP 1 of
 224 process 149 is bound to CPU3, and LWP 2 of process 149 is not bound.
 225
 226 .sp
 227 .in +2
 228 .nf
 229 example% \fBpbind -q 149/1-2\fR
 230 lwp id 149/1: 3
 231 lwp id 149/2: not bound
 232 .fi
 233 .in -2
 234 .sp
 235
 236 .LP
 237 \fBExample 5 \fRQuerying LWP Bindings for Processor 2:
 238 .sp
 239 .LP
 240 The following example queries all LWPs bound to processor 2:
 241
 242 .sp
 243 .in +2
 244 .nf
 245 example% \fBpbind -Q 2\fR
 246 lwp id 149/4: 2
 247 lwp id 149/5: 2
 248 .fi
 249 .in -2
 250 .sp
 251
 252 .SH EXIT STATUS
 253 .sp
 254 .LP
 255 The following exit values are returned:
 256 .sp
 257 .ne 2
 258 .na
 259 \fB\fB0\fR\fR
 260 .ad
 261 .sp .6
 262 .RS 4n
 263 Successful completion.
 264 .RE
 265
 266 .sp
 267 .ne 2
 268 .na
 269 \fB\fB>0\fR\fR
 270 .ad
 271 .sp .6
 272 .RS 4n
 273 An error occurred.
 274 .RE
 275
 276 .SH SEE ALSO
 277 .sp
 278 .LP
 279 \fBpsradm\fR(1M), \fBpsrinfo\fR(1M), \fBpsrset\fR(1M), \fBprocessor_bind\fR(2),
 280 \fBprocessor_info\fR(2), \fBsysconf\fR(3C), \fBattributes\fR(5)
 281 .SH DIAGNOSTICS
 282 .sp
 283 .ne 2
 284 .na
 285 \fB\fBpbind: cannot query pid 31: No such process\fR\fR
 286 .ad
 287 .sp .6
 288 .RS 4n
 289 The process specified did not exist or has exited.
 290 .RE
 291
 292 .sp
 293 .ne 2
 294 .na
 295 \fB\fBpbind: cannot bind pid 31: Not owner\fR\fR
 296 .ad
 297 .sp .6
 298 .RS 4n
 299 The user does not have permission to bind the process.
 300 .RE
 301
 302 .sp
 303 .ne 2
 304 .na
 305 \fB\fBpbind: cannot bind pid 31: Invalid argument\fR\fR
 306 .ad
 307 .sp .6
 308 .RS 4n
 309 The specified processor is not on-line.
 310 .RE
 311