usr/src/man/man1/plgrp.1

   1 '\" te
   2 .\" Copyright (c) 2006, 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 PLGRP 1 "Sep 8, 2006"
   7 .SH NAME
   8 plgrp \- observe and affect home lgroup and lgroup affinities of threads
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBplgrp\fR [\fB-F\fR] [\fB-h\fR] \fIpid\fR |\fI core\fR [/\fIlwps\fR] ...
  13 .fi
  14
  15 .LP
  16 .nf
  17 \fBplgrp\fR [\fB-F\fR] \fB-a\fR \fIlgroup_list\fR \fIpid\fR[/\fIlwps\fR] ...
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBplgrp\fR [\fB-F\fR] \fB-H\fR \fIlgroup_list\fR \fIpid\fR[/\fIlwps\fR] ...
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBplgrp\fR [\fB-F\fR] \fB-A\fR \fIlgroup_list\fR/\fInone\fR | \fIweak\fR |\fIstrong\fR [,...] \fIpid\fR
  28      [/\fIlwps\fR] ...
  29 .fi
  30
  31 .SH DESCRIPTION
  32 .sp
  33 .LP
  34 \fBplgrp\fR displays or sets the home \fBlgroup\fR and \fBlgroup\fR affinities
  35 for one or more processes, threads, or LWPs.
  36 .sp
  37 .LP
  38 An \fBlgroup\fR represents the set of CPU and memory-like hardware devices that
  39 are at most some distance (latency) apart from each other. Each \fBlgroup\fR in
  40 the system is identified by a unique \fBlgroup\fR ID. The \fBlgroups\fR are
  41 organized into a hierarchy to facilitate finding the nearest resources (see
  42 lgrpinfo(1) for more about \fBlgroups\fR and the \fBlgroup\fR hierarchy).
  43 .sp
  44 .LP
  45 By default, each thread is assigned a home \fBlgroup\fR upon creation. When the
  46 system needs to allocate a CPU or memory resource for a thread, it searches the
  47 lgroup hierarchy from the thread's home \fBlgroup\fR for the nearest available
  48 resources to the thread's home.
  49 .sp
  50 .LP
  51 Typically, the home \fBlgroup\fR for a thread is the lgroup for which the
  52 thread has the most affinity. Initially, the system chooses a home \fBlgroup\fR
  53 for each thread, but leaves the thread's affinity for that \fBlgroup\fR set to
  54 \fBnone\fR. If a thread sets a stronger affinity for an lgroup in its processor
  55 set other than its home, the thread is rehomed to that lgroup as long as the
  56 thread is not bound to a CPU. The thread can be re-homed to the \fBlgroup\fR in
  57 its processor set with the next highest affinity when the affinity (if any) for
  58 its home \fBlgroup\fR is removed (set to \fBnone\fR).
  59 .sp
  60 .LP
  61 The different levels of lgroup affinities and their semantics are fully
  62 described in \fBlgrp_affinity_set\fR(3LGRP).
  63 .SH USAGE
  64 .SS "Specifying lgroups"
  65 .sp
  66 .LP
  67 \fIlgroup_list\fR is a comma separated list of one or more of the following:
  68 .sp
  69 .in +2
  70 .nf
  71 - \fIlgroup_ID\fR
  72 - Range of \fIlgroup_ID\fRs specified as
  73  <start \fIlgroup_ID\fR>-<end \fIlgroup_ID\fR>
  74 - all
  75 - root
  76 - leaves
  77 .fi
  78 .in -2
  79 .sp
  80
  81 .sp
  82 .LP
  83 The \fBall\fR keyword represents all lgroup IDs in the system. The \fBroot\fR
  84 keyword represents the ID of the root \fBlgroup\fR. The \fBleaves\fR keyword
  85 represents the IDs of all \fBleaf\fR \fBlgroups\fR, that is, lgroups which do
  86 not have any children.
  87 .SS "Specifying Processes and Threads"
  88 .sp
  89 .LP
  90 \fBplgrp\fR takes one or more space separated processes or threads as
  91 arguments. Processes and threads can be specified in a manner similiar to the
  92 \fBproc\fR(1) tools. A process ID may be specified as an integer \fIpid\fR or
  93 \fB/proc/\fR\fIpid\fR. Shell expansions can be used to specify processes when
  94 \fB/proc/\fR\fIpid\fR is used. For example, \fB/proc/*\fR can be used to
  95 specify all the processes in the system. If a process ID is given alone, then
  96 all the threads of the process are included as arguments to \fBplgrp\fR.
  97 .sp
  98 .LP
  99 A thread can be explicitly specified with its process ID and thread ID given
 100 together as \fIpid\fR\fB/\fR\fIlwpid\fR. Multiple threads of a process can be
 101 selected at once by using the hyphen (\fB-\fR) and comma(\fB,\fR). For example,
 102 \fIpid\fR\fB/1,2,7-9\fR specifies threads 1, 2, 7, 8, and 9 of the process with
 103 \fIpid\fR as its process ID.
 104 .SH OPTIONS
 105 .sp
 106 .LP
 107 The following options are supported:
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fB-a\fR \fIlgroup_list\fR\fR
 112 .ad
 113 .sp .6
 114 .RS 4n
 115 Display \fBlgroup\fR affinities of specified processes or threads for the
 116 specified \fIlgroup_list\fR.
 117 .RE
 118
 119 .sp
 120 .ne 2
 121 .na
 122 \fB\fB-A\fR \fIlgroup_list\fR\fB/\fR\fInone\fR\fB|\fR\fIweak\fR\fB|\fR\fIstrong
 123 \fR\fB[,...]\fR\fR
 124 .ad
 125 .sp .6
 126 .RS 4n
 127 Set affinity of specified processes or threads for the specified
 128 \fIlgroup_list\fR.
 129 .sp
 130 A comma separated list of \fIlgroups\fR\fB/\fR\fIaffinity\fR assignments can be
 131 given to set several affinities at once.
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fB-F\fR\fR
 138 .ad
 139 .sp .6
 140 .RS 4n
 141 Force by grabbing the target process even if another process has control.
 142 Caution should be exercised when using the \fB-F\fR flag. Imposing two
 143 controlling processes on one victim process can lead to chaos. Safety is
 144 assured only when the primary controlling process (typically a debugger) has
 145 stopped the victim process, but isn't doing anything during the application of
 146 this proc tool. See \fBWARNINGS\fR for more details.
 147 .RE
 148
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fB-h\fR\fR
 153 .ad
 154 .sp .6
 155 .RS 4n
 156 Get home \fBlgroup\fR of specified processes and/or threads. If no options are
 157 specified, this is the default.
 158 .RE
 159
 160 .sp
 161 .ne 2
 162 .na
 163 \fB\fB-H\fR \fIlgroup_list\fR\fR
 164 .ad
 165 .sp .6
 166 .RS 4n
 167 Set home \fBlgroup\fR of specified processes and threads.
 168 .sp
 169 This sets a strong affinity for the desired lgroup to rehome the threads. If
 170 more than one \fBlgroup\fR is specified, \fBplgrp\fR tries to home the threads
 171 to the \fBlgroups\fR in a round robin fashion.
 172 .RE
 173
 174 .SH OPERANDS
 175 .sp
 176 .LP
 177 The following operands are supported:
 178 .sp
 179 .ne 2
 180 .na
 181 \fB\fIlwps\fR\fR
 182 .ad
 183 .RS 8n
 184 Specifies thread. See \fBUSAGE\fR.
 185 .RE
 186
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fIpid\fR\fR
 191 .ad
 192 .RS 8n
 193 Specifies process ID. See \fBUSAGE\fR.
 194 .RE
 195
 196 .SH EXAMPLES
 197 .LP
 198 \fBExample 1 \fRGetting the Home \fBlgroup\fR for the Shell
 199 .sp
 200 .LP
 201 The following example gets the home \fBlgroup\fR for the shell:
 202
 203 .sp
 204 .in +2
 205 .nf
 206 % plgrp $$
 207 PID/LWPID    HOME
 208 3401/1        1
 209 .fi
 210 .in -2
 211 .sp
 212
 213 .LP
 214 \fBExample 2 \fRSetting the Home \fBlgroup\fR of Multiple Threads to the Root
 215 \fBlgroup\fR
 216 .sp
 217 .LP
 218 The following example sets the home \fBlgroup\fR of multiple threads to the
 219 root \fBlgroup\fR:
 220
 221 .sp
 222 .in +2
 223 .nf
 224 % plgrp -H root `pgrep firefox`
 225      PID/LWPID    HOME
 226      918/1        1 => 0
 227      934/1        2 => 0
 228      934/2        1 => 0
 229      934/3        2 => 0
 230      934/625      1 => 0
 231      934/626      2 => 0
 232      934/624      2 => 0
 233      934/623      2 => 0
 234      934/630      1 => 0
 235 .fi
 236 .in -2
 237 .sp
 238
 239 .LP
 240 \fBExample 3 \fRGetting Two Threads' Affinities for \fBlgroups 0-2\fR
 241 .sp
 242 .LP
 243 The following example gets two threads' affinities for \fBlgroups 1-2\fR:
 244
 245 .sp
 246 .in +2
 247 .nf
 248 % plgrp -a 0-2 101398/1 101337/1
 249 PID/LWPID    HOME  AFFINITY
 250 101398/1        1     0-2/none
 251 101337/1        1     0-2/none
 252 .fi
 253 .in -2
 254 .sp
 255
 256 .LP
 257 \fBExample 4 \fRSetting \fBlgroup\fR Affinities
 258 .sp
 259 .LP
 260 The following example sets lgroup affinities:
 261
 262 .sp
 263 .in +2
 264 .nf
 265 % plgrp -A 0/weak,1/none,2/strong 101398
 266 PID/LWPID    HOME       AFFINITY
 267 101398/1        1 => 2     0,2/none => 2/strong,0/weak
 268 .fi
 269 .in -2
 270 .sp
 271
 272 .SH EXIT STATUS
 273 .sp
 274 .LP
 275 The following exit values are returned:
 276 .sp
 277 .ne 2
 278 .na
 279 \fB\fB0\fR\fR
 280 .ad
 281 .RS 5n
 282 Successful completion.
 283 .RE
 284
 285 .sp
 286 .ne 2
 287 .na
 288 \fB\fB1\fR\fR
 289 .ad
 290 .RS 5n
 291 Syntax error. Nothing was changed.
 292 .RE
 293
 294 .sp
 295 .ne 2
 296 .na
 297 \fB\fB2\fR\fR
 298 .ad
 299 .RS 5n
 300 Non-fatal error or interrupt. Something might have changed.
 301 .RE
 302
 303 .SH ATTRIBUTES
 304 .sp
 305 .LP
 306 See \fBattributes\fR(5) for descriptions of the following attributes:
 307 .sp
 308
 309 .sp
 310 .TS
 311 box;
 312 c | c
 313 l | l .
 314 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 315 _
 316 Interface Stability     See below.
 317 .TE
 318
 319 .sp
 320 .LP
 321 The command syntax is Unstable. The output formats are Unstable.
 322 .SH SEE ALSO
 323 .sp
 324 .LP
 325 \fBlgrpinfo\fR(1), \fBmadv.so.1\fR(1), \fBpmadvise\fR(1), \fBpmap\fR(1),
 326 \fBproc\fR(1), \fBps\fR(1), \fBprstat\fR(1M), \fBlgrp_affinity_get\fR(3LGRP),
 327 \fBlgrp_affinity_set\fR(3LGRP), \fBlgrp_home\fR(3LGRP), \fBliblgrp\fR(3LIB),
 328 \fBproc\fR(4), \fBattributes\fR(5)
 329 .SH WARNINGS
 330 .sp
 331 .LP
 332 Like the \fBproc\fR(1) tools, the \fBplgrp\fR utility stops its target
 333 processes while inspecting them and reports the results when invoked with any
 334 option.
 335 .sp
 336 .LP
 337 There are conditions under which processes can deadlock. A process can do
 338 nothing while it is stopped. Stopping a heavily used process in a production
 339 environment (even for a short amount of time) can cause severe bottlenecks and
 340 even hangs of these processes, making them to be unavailable to users. Thus,
 341 stopping a UNIX process in a production environment should be avoided. See
 342 \fBproc\fR(1).
 343 .sp
 344 .LP
 345 A process that is stopped by this tool might be identified by issuing the
 346 following command:
 347 .sp
 348 .in +2
 349 .nf
 350 /usr/bin/ps -eflL
 351 .fi
 352 .in -2
 353 .sp
 354
 355 .sp
 356 .LP
 357 and looking for a \fBT\fR in the first column of the output. Certain processes,
 358 for example, \fBsched\fR, can show the \fBT\fR status by default most of the
 359 time.