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

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