-
Notifications
You must be signed in to change notification settings - Fork 168
/
hwloc-ps.1in
216 lines (199 loc) · 6.61 KB
/
hwloc-ps.1in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
.\" -*- nroff -*-
.\" Copyright © 2010-2021 Inria. All rights reserved.
.\" Copyright © 2009-2010 Cisco Systems, Inc. All rights reserved.
.\" See COPYING in top-level directory.
.TH HWLOC-PS "1" "%HWLOC_DATE%" "%PACKAGE_VERSION%" "%PACKAGE_NAME%"
.SH NAME
hwloc-ps \- List currently-running processes or threads that are bound
.
.\" **************************
.\" Synopsis Section
.\" **************************
.SH SYNOPSIS
.
.B hwloc-ps
[\fIoptions\fR]
.
.\" **************************
.\" Options Section
.\" **************************
.SH OPTIONS
.
.TP 10
\fB\-a\fR
List all processes, even those that are not bound to any
specific part of the machine.
.TP
\fB\-\-pid <pid>\fR
Only show process of PID \fI<pid>\fR,
even if it is not bound to any specific part of the machine.
.TP
\fB\-\-name <name>\fR
Only show processes whose name contains \fI<name>\fR,
even if they are not bound to any specific part of the machine.
This is not supported on all operating systems.
.TP
\fB\-\-uid <uid>\fR
Only show processes of the user whose UID is \fI<uid>\fR,
or processes of all users if \fIall\fR is given.
By default, only processes of the current user are displayed.
This is currently only supported on Linux.
.TP
\fB\-p\fR \fB\-\-physical\fR
Report OS/physical indexes instead of logical indexes
.TP
\fB\-l\fR \fB\-\-logical\fR
Report logical indexes instead of physical/OS indexes (default)
.TP
\fB\-c\fR \fB\-\-cpuset\fR
Show process bindings as cpusets instead of objects.
.TP
\fB\-t\fR \fB\-\-threads\fR
Show threads inside processes.
If \fB\-a\fR is given as well, list all threads within each process.
Otherwise, show all threads inside each process where at least one
thread is bound.
This is currently only supported on Linux.
.TP
\fB\-\-single\-ancestor\fR
When the object is bound to different objects,
report their common ancestor (even if it may be larger than the actual binding).
.TP
\fB\-e\fR \fB\-\-get\-last\-cpu\-location\fR
Report the last processors where the process/thread ran.
Note that the result may already be outdated when reported
since the operating system may move the tasks to other processors
at any time according to the binding.
.TP
\fB\-\-disallowed\fR
Include objects disallowed by administrative limitations.
.TP
\fB\-\-pid\-cmd <cmd>\fR
Append the output of the given command to each PID line.
For each displayed process ID, execute the command \fI<cmd> <pid>\fR
and append \fBthe first line\fR of its output to the regular hwloc-ps
line.
.TP
\fB\-\-pid\-cmd env=<name>\fR
On Linux, try to read the value of environment variable \fIname\fR
in each process and display it at the end of the line.
.TP
\fB\-\-pid\-cmd mpirank\fR
On Linux, try to find the process MPI rank (by querying some widespread
environment variables) and display it at the end of the line.
.TP
\fB\-\-json\-server\fR
Run the tool as a JSON server that waits for other process' requests
on a port and sends back binding information.
See contrib/hwloc-ps.www/ for details.
.TP
\fB\-\-json\-port <port>\fR
Use the given port number instead of the default 8888.
.TP
\fB\-v\fR \fB\-\-verbose\fR
Increase verbosity of the JSON server.
.TP
\fB\-\-short\-name\fR
Show only the process short name instead of the path.
.TP
\fB\-\-version\fR
Report version and exit.
.TP
\fB\-h\fR \fB\-\-help\fR
Display help message and exit.
.
.\" **************************
.\" Description Section
.\" **************************
.SH DESCRIPTION
.
By default, hwloc-ps lists only those currently-running processes that
are bound. If \fB-t\fR is given, processes that are not bound but contain
at least one bound thread are also displayed, as well as all their threads.
.
.PP
hwloc-ps displays process identifier, command-line and
binding. The binding may be reported as objects or cpusets.
.
.PP
By default, process bindings are restricted to the currently available
topology. If some processes are bound to processors that are not available
to the current process, they are ignored unless \fB\-\-disallowed\fR
is given.
.
.PP
The output is a plain list. If you wish to annotate the hierarchical
topology with processes so as to see how they are actual distributed
on the machine, you might want to use lstopo --ps instead (which also
only shows processes that are bound).
.
.PP
The
.I -a
switch can be used to show
.I all
processes, if desired.
.
.\" **************************
.\" Examples Section
.\" **************************
.SH EXAMPLES
.PP
If a process is bound, it appears in the default output:
$ hwloc-ps
4759 Core:0 myprogram
If a process is bound on two cores of a larger package,
the output will show these cores.
Option \-\-single\-ancestor will rather return the package
even if it is actually larger than the binding here
(the process is not bound to Core:0 of Package:0):
$ hwloc-ps
4863 Core:1 Core:2 myprogram
$ hwloc-ps --single-ancestor
4863 Package:0 myprogram
If a process is not bound but 3 of his 4 threads are bound,
it only appears in the thread-aware output (or if explicitly selected):
$ hwloc-ps
$ hwloc-ps -t
4759 Machine:0 myprogram
4759 Machine:0
4761 PU:0
4762 PU:2
4765 PU:1
$ hwloc-ps --pid 4759
4759 Machine:0 myprogram
On Linux, hwloc-ps may also display some process specific environment
variable at the end of the line. This is for instance useful
for identify MPI ranks among processes:
$ hwloc-ps --pid-cmd env=OMPI_COMM_WORLD_RANK
29093 PU:0 myprogram OMPI_COMM_WORLD_RANK=0
29094 PU:2 myprogram OMPI_COMM_WORLD_RANK=1
29095 PU:1 myprogram OMPI_COMM_WORLD_RANK=2
29096 PU:3 myprogram OMPI_COMM_WORLD_RANK=3
Some widespread MPI specific environment variables
(OMPI_COMM_WORLD_RANK, PMIX_RANK, PMI_RANK and SLURM_PROCID)
are actually directly recognized by hwloc-ps when requesting the \fImpirank\fR command:
$ hwloc-ps --pid-cmd mpirank
29093 PU:0 myprogram PMIX_RANK=0
29094 PU:2 myprogram PMIX_RANK=1
29095 PU:1 myprogram PMIX_RANK=2
29096 PU:3 myprogram PMIX_RANK=3
Beside reading environment variables, hwloc-ps may also append
the output of a custom program. Again, for reading the Open MPI
process rank:
$ hwloc-ps --pid-cmd myscript
29093 PU:0 myprogram OMPI_COMM_WORLD_RANK=0
29094 PU:2 myprogram OMPI_COMM_WORLD_RANK=1
29095 PU:1 myprogram OMPI_COMM_WORLD_RANK=2
29096 PU:3 myprogram OMPI_COMM_WORLD_RANK=3
where \fBmyscript\fR is a shell script doing:
#!/bin/sh
cat /proc/$1/environ 2>/dev/null | xargs --null --max-args=1 echo | grep OMPI_COMM_WORLD_RANK
.\" **************************
.\" See also section
.\" **************************
.SH SEE ALSO
.
.ft R
hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1), and hwloc-ps.www/README
.sp