Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

pbind(8)

Name

pbind - control and query bindings of processes or LWPs

Synopsis

pbind -b [-c | g | l | r] [target_list] [-n] [-s | w] [-xft] [-i 
idtype] [idlist]
pbind -b [-c | g | l | r] [target_list] [-n] [-s | w] [-xft] [-e 
command [argument(s)]]
pbind [-q] [-c | g | l | r] [-i idtype] [idlist]
pbind -Q [-c | g | l | r] [target_list]
pbind -U [-c | g | l | r] [target_list]
pbind -u [-i 
idtype] idlist

Description

pbind controls and queries bindings and affinities of processes and LWPs (lightweight processes) to CPU(s). This utility allows users to determine on which processor(s) one or more LWPs should be scheduled to run, whether such binding should be strongly or weakly enforced and how it should be inherited by child LWPs. pbind can also be used to execute a command with a specific binding.

With strong affinity the target LWP(s) will only run on the specified processors, while weak affinity results in a best effort attempt at executing the LWP(s) on such CPUs. The binding determined by pbind is not exclusive, that is, the processor is free to execute other LWPs as well. This in turn means that bound threads can be prevented from running if other, higher priority LWPs are occupying the same processors.

The target CPUs can be specified directly by their processor IDs or indirectly by their Processor Group (PG), Locality Group (lgroup) ID, or core ID. The user may also specify negative affinity, indicating that the specified CPUs should be avoided.

The init process (process ID 1) is a special case. In order for the pbind command to operate on the init process, the idtype must be pid and idlist must consist of only a 1.

When querying for bindings of specific LWPs, the user may request that the resulting set of CPUs be identified through their IDs, the Processor Groups or the Locality Groups that contain them. Similarly, when querying or removing all bindings of specific processors, the user may do so through their respective PG or lgroup IDs.

By default, bindings are inherited across exec(2), fork(2), and thr_create(3C), but the user can request that inheritance be broken across one or more of such actions.

It is important to note that the runtime behavior determined by pbind is subject to the continued online state of the specified CPUs and their affiliation to the same Processor Set as the target LWPs. If these underlying conditions change, a LWP will lose its affinity for a given CPU and will need to be reset once the conditions are restored.

Superusers may bind or unbind any process or LWP, while other users can bind or unbind any process or LWP for which they have permission to signal, that is, any process that has the same effective user ID as the user.

Options

The following options are supported:

–b

This option, along with one or more identifiers indicates which CPU(s), Processor Group(s) or Locality Group(s) are the target(s) of the requested binding.

The valid target types and their corresponding interpretations are as follows:

–c

CPU, or Processor ID (the default). All the given CPUs must be present and online. Use the psrinfo command to determine whether or not target_list is present and on-line. See psrinfo(8) for more information.

–r

Core ID.

–g

Processor Group ID. See pginfo(8) for more information.

–l

Locality Group ID. The specified lgroups must contain at least one online CPU for the operation to proceed. See lgrpinfo(8) for details.

–n

Indicates that the given target processors should be avoided.

–s

Indicates that the binding is to be strongly enforced (default) and the specified LWPs should only execute on the given processors.

–w

Indicates that the binding is to be weakly enforced, and the specified LWPs should preferably execute on the given processors but can run elsewhere if necessary.

–i idtype

This option, together with the idlist arguments specifies one or more processes or LWPs to which the binding will be applied. The interpretation of idlist depends on the value of idtype which, if omitted defaults to pid.

–i pid[/lwps]

idlist is a list of process IDs with each ID possibly followed by a forward slash (/) and a list of comma-separated LWP IDs. A range of LWP IDs can be indicated by a - separating start and end of the range.

–i ppid

idlist is a list of parent process IDs. The binding command applies to all processes whose parent process ID is in the list.

–i pgid

idlist is a list of process group IDs. The binding command applies to all processes in the specified process groups.

–i uid

idlist is a list of user IDs. The binding command applies to all processes with an effective user ID equal to an ID from the list.

–i gid

idlist is a list of group IDs. The binding command applies to all processes with an effective group ID equal to an ID from the list.

–i taskid

idlist is a list of task IDs. The binding command applies to all processes in the specified tasks.

–i projid

idlist is a list of project IDs. The binding command applies to all processes with an effective project ID equal to an ID from the list. Project names are also supported instead of project IDs.

–i zoneid

idlist is a list of zone IDs. The binding command applies to all processes with an effective zone ID equal to an ID from the list. Zone names are also supported instead of zone IDs.

Note that The P_MYID identifier can be used in conjunction with any of the ID types above to indicate that the desired ID is that of the calling LWP for the given type (for example, P_PID and P_MYID result in the process identifier of the caller LWP).

–x

Do not inherit affinities across exec(2).

–f

Do not inherit affinities across fork(2).

–t

Do not inherit affinities across thr_create(3C).

–e

Executes a command with the specified bindings.

–q

Displays the CPU bindings of the specified processes or of all processes. If a process is composed of multiple LWPs which have different bindings and the LWPs are not explicitly specified, the bindings of only one of the bound LWPs will be displayed. The bindings of a subset of LWPs can be displayed by appending "/lwpids" to the process IDs. Multiple LWPs may be selected using "-" and "," delimiters.

Additionally, the [–gl] options may be included to request that the report include which Processor Groups or Locality Groups contain the CPUs to which the specified LWPs are bound. By default, the processor IDs are always displayed.

–Q

Displays the LWPs bound to the specified list of CPUs, Processor Groups or Locality Groups, or all LWPs with processor bindings. For processes composed of multiple LWPs, the bindings of individual LWPs will be displayed.

–u

Removes the bindings of all or a subset of the LWPs of the specified processes, allowing them to be executed on any online processor.

–U

Removes the bindings of all LWPs bound to the specified list of processors, or to any processor if no argument is specified.

Return Values

pbind returns 0 upon successful completion. If an error occurs, a positive integer is returned indicating the resulting error number.

Errors

The pbind command will fail if:

ESRCH

None of the specified processes or LWPs exist.

ERANGE

One or more target CPU, Processor Group or Locality Group are not present on the current system.

EINVAL

The specified idtype or IDs do not exist, all of the target processors are offline, faulted, part of different processor sets or the given combination of options is invalid.

EPERM

Neither the real user ID nor the effective user ID match the real or saved user ID of one of the LWPs being bound, and the {PRIV_PROC_OWNER} privilege is not asserted in the effective set of the calling process.

Examples

Example 1 Binding Processes 200 and 201 to Processor 2

The following example binds processes 200 and 201 to processor 2:

$ pbind -b 2 200 201
	process id 200: was not bound, now 2
	process id 201: was not bound, now 2
Example 2 Binding Processes 201 and 202 to CPUs 2, 5, 6, and 7

The following example binds processes 201 and 202 to CPUs 2, 5, 6, and 7:

$ pbind -b -c 2,5-7 201 202
	process id 201: was bound to CPU(s) 2, now bound to CPU(s) 2, 5-7
	process id 223: was bound to CPU(s) 2, now bound to CPU(s) 2, 5-7
Example 3 Binding Process 200 to Processor Groups 3 and 12

The following example binds process 200 to Processor Groups 3 and 12:

$ pbind -b -g 3 12 200
	process id 204: was 2, now bound to Processor Group 3 (Socket) and 12 (Cache).
Example 4 Binding process 200 to lgroup 5

The following example binds process 200 to lgroup 5:

$ pbind -b -l 5 -i pid 200
	process id 204: was bound to Processor Group(s) 3 (Cache) and 12 (FPU),
	now bound to lgroup 5.
Example 5 Weakly Binding Process 205 to the CPUs Contained in Processor Group 11

The following example weakly binds process 205 to the CPUs contained in Processor Group 11:

$ pbind -b -w -g 11 205
	process id 205: was not bound, now bound to Processor Group 11 (FPU).
Example 6 Binding Process 210 to all CPUs but Processors 0-3, on a System With 8 Processors

The following example binds process 210 to all CPUs but processors 0-3, on a system with 8 processors:

$ pbind -b -n 0-3 210
	process id 205: was not bound, now bound to CPUs 4-7
Example 7 Binding Project testing to CPU 1 by Specifying Project Name

The following example binds project testing to CPU 1 by specifying its name:

$ pbind -b 1 -i projid testing
     process id 205: was not bound, now bound to CPUs 4-7
     pbind(8): pid 101438 strongly bound to processor(s) 1.
     pbind(8): pid 101447 strongly bound to processor(s) 1.
Example 8 Unbinding Process 204

The following example unbinds process 204:

$ pbind -u 204
	process id 204: was 1, now not bound

Example 9 Unbinding all of User's 606 LWPs

The following example unbinds all of user's 606 LWPs:

$ pbind -u -i uid 606
	user id 204: had bindings to CPUs 3, 5 and 6, now not bound
Example 10 Querying Bindings for Processes 1, 149, and 101

The following example queries bindings for processes 1, 149, and 101:

$ pbind -q 1 149 101
	process id 1: 0
	process id 149: 3
	process id 101: not bound
Example 11 Querying all Bindings for LWPs in Zone 2, Including Which Locality Groups are Covered

The following example queries all bindings for LWPs in Zone 2, including which locality groups are covered:

$ pbind -q -l -i zoneid 2
	process id 1011: bound to CPU(s) in lgroup 4
	process id 1518: bound to CPU(s) in lgroup 8
Example 12 Querying Bindings for Process 149's LWPs 1 and 2

The following example queries bindings for process 149's LWPs 1 and 2:

$ pbind -q 149/1-2
	lwp id 149/1: 3
	lwp id 149/2: not bound

The same operation can be accomplished by explicitly specifying the pid idtype:

$ pbind -q -i pid 149/1-2
	lwp id 149/1: 3
	lwp id 149/2: not bound
Example 13 Query Bindings for Process 210, Including Which Processor Groups are Covered

The following example queries bindings for process 210, including which Processor Groups are covered:

$ pbind -q -g -i pid 210
	lwp id 149/1: bound to CPU(s) in Processor Group 12 (Cache)
	lwp id 149/2: not bound

Example 14 Querying bindings for CPU 2

The following example queries bindings for CPU 2:

$ pbind -Q 2
	lwp id 149/4: 2
	lwp id 149/5: 2

The next, equivalent example explicitly specifies that we are querying affinities based on CPU ID:

$ pbind -Q -c 2
	lwp id 149/4: 2
	lwp id 149/5: 2
Example 15 Querying bindings for CPUs contained in lgroup 2

The following example queries bindings for CPUs contained in lgroup 2:

$ pbind -Q -l 2
	lwp id 149/4: bound to CPUs in lgroup 2
	lwp id 149/5: bound to CPUs in lgroup 2
Example 16 Binding process 101048 to Core ID 0

The following example binds process 101048 to Core ID 0:

# pbind -b -r 0 -i pid 101048 
pbind(8): pid 101048 strongly bound to Core(s) 0.
Example 17 Re-Binding process 101048 to Core ID 0-3

The following example re-binds the process 101048 to cores 0, 1, 2, and 3:

# pbind -b -r 1 -i pid 101048 
pbind(8): pid 101048 strongly bound to Core(s) 0. 
pbind(8): pid 101048 strongly bound to Core(s) 0 1 2 3.
Example 18 Unbinding all processes from Core ID 1

The following example unbinds all processes from core ID 1:

# pbind -U -r 1

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/core-os

See Also

processor_bind(2), processor_info(2), sysconf(3C), attributes(7), resource-management(7), psradm(8), psrinfo(8), psrset(8)