1HWLOC-PS(1)                          hwloc                         HWLOC-PS(1)
2
3
4

NAME

6       hwloc-ps - List currently-running processes or threads that are bound
7

SYNOPSIS

9       hwloc-ps [options]
10

OPTIONS

12       -a        List all processes, even those that are not bound to any spe‐
13                 cific part of the machine.
14
15       --pid <pid>
16                 Only show process of PID <pid>, even if it is  not  bound  to
17                 any specific part of the machine.
18
19       --name <name>
20                 Only  show processes whose name contains <name>, even if they
21                 are not bound to any specific part of the machine.   This  is
22                 not supported on all operating systems.
23
24       --uid <uid>
25                 Only  show  processes of the user whose UID is <uid>, or pro‐
26                 cesses of all users if all is given.  By default,  only  pro‐
27                 cesses  of the current user are displayed.  This is currently
28                 only supported on Linux.
29
30       -p --physical
31                 Report OS/physical indexes instead of logical indexes
32
33       -l --logical
34                 Report  logical  indexes  instead  of   physical/OS   indexes
35                 (default)
36
37       -c --cpuset
38                 Show process bindings as cpusets instead of objects.
39
40       -t --threads
41                 Show  threads inside processes.  If -a is given as well, list
42                 all threads within each process.  Otherwise, show all threads
43                 inside each process where at least one thread is bound.  This
44                 is currently only supported on Linux.
45
46       -e --get-last-cpu-location
47                 Report  the last processors  where  the  process/thread  ran.
48                 Note  that  the  result may already be outdated when reported
49                 since the operating system may move the tasks to  other  pro‐
50                 cessors at any time according to the binding.
51
52       --disallowed
53                 Include objects disallowed by administrative limitations.
54
55       --pid-cmd <cmd>
56                 Append the output of the given command to each PID line.  For
57                 each displayed process ID, execute the  command  <cmd>  <pid>
58                 and append the first line of its output to the regular hwloc-
59                 ps line.
60
61       --json-server
62                 Run the tool as a JSON server that waits for  other  process'
63                 requests  on  a port and sends back binding information.  See
64                 contrib/hwloc-ps.www/ for details.
65
66       --json-port <port>
67                 Use the given port number instead of the default 8888.
68
69       -v --verbose
70                 Increase verbosity of the JSON server.
71
72       -h --help Display help message and exit.
73

DESCRIPTION

75       By default, hwloc-ps lists only those currently-running processes  that
76       are  bound. If -t is given, processes that are not bound but contain at
77       least one bound thread  are  also  displayed,  as  well  as  all  their
78       threads.
79
80       hwloc-ps  displays  process  identifier, command-line and binding.  The
81       binding may be reported as objects or cpusets.
82
83       By default, process bindings are restricted to the currently  available
84       topology. If some processes are bound to processors that are not avail‐
85       able to the current process, they are ignored  unless  --include-disal‐
86       lowed is given.
87
88       The  output  is  a plain list. If you wish to annotate the hierarchical
89       topology with processes so as to see how they are actual distributed on
90       the machine, you might want to use lstopo --ps instead (which also only
91       shows processes that are bound).
92
93       The -a switch can be used to show all processes, if desired.
94

EXAMPLES

96       If a process is bound, it appears in the default output:
97
98           $ utils/hwloc-ps
99           4759  Core:0         myprogram
100
101       If a process is not bound but 3 of his 4 threads  are  bound,  it  only
102       appears in the thread-aware output (or if explicitly selected):
103
104           $ utils/hwloc-ps
105
106           $ utils/hwloc-ps -t
107           4759  Machine:0      myprogram
108            4759 Machine:0
109            4761 PU:0
110            4762 PU:2
111            4765 PU:1
112
113           $ utils/hwloc-ps --pid 4759
114           4759  Machine:0      myprogram
115
116       To  display  the  binding of already running MPI processes (launched by
117       Open MPI) and append their MPI rank (in MPI_COMM_WORLD) to each line:
118
119           $ utils/hwloc-ps --pid-cmd myscript
120           29093 L1dCache:0     myprogram OMPI_COMM_WORLD_RANK=0
121           29094 L1dCache:2     myprogram OMPI_COMM_WORLD_RANK=1
122           29095 L1dCache:1     myprogram OMPI_COMM_WORLD_RANK=2
123           29096 L1dCache:3     myprogram OMPI_COMM_WORLD_RANK=3
124
125       where myscript is a bash script doing:
126
127           #!/bin/sh
128           cat /proc/$1/environ 2>/dev/null | xargs --null --max-args=1 echo |
129       grep OMPI_COMM_WORLD_RANK
130
131

SEE ALSO

133       hwloc(7),   lstopo(1),   hwloc-calc(1),  hwloc-distrib(1),  and  hwloc-
134       ps.www/README
135
136
137
138
1392.2.0                            Mar 30, 2020                      HWLOC-PS(1)