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