HWLOC-PS(1)

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

SYNOPSIS
hwloc-ps [options]

OPTIONS

-a  List all processes, even those that are not bound to any specific part of the machine.

--pid <pid>
    Only show process of PID <pid>, even if it is not bound to any specific part of the machine.

--name <name>
    Only show processes whose name contains <name>, even if they are not bound to any specific part of the machine. This is not supported on all operating systems.

--uid <uid>
    Only show processes of the user whose UID is <uid>, or processes of all users if all is given. By default, only processes of the current user are displayed. This is currently only supported on Linux.

-p --physical
    Report OS/physical indexes instead of logical indexes

-l --logical
    Report logical indexes instead of physical/OS indexes (default)

-c --cpuset
    Show process bindings as cpusets instead of objects.

-t --threads
    Show threads inside processes. If -a 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.

-e --get-last-cpu-location
    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.

--disallowed
    Include objects disallowed by administrative limitations.

--pid-cmd <cmd>
    Append the output of the given command to each PID line. For each displayed process ID, execute the command <cmd> <pid> and append the first line of its output to the regular hwloc-ps line.

--json-server
    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.

--json-port <port>
    Use the given port number instead of the default 8888.

-v --verbose
    Increase verbosity of the JSON server.

-h --help
    Display help message and exit.

DESCRIPTION
By default, hwloc-ps lists only those currently-running processes that are bound. If -t is given, processes that are not bound but contain at least one bound thread are also displayed, as well as all their threads.

hwloc-ps displays process identifier, command-line and binding. The binding may be reported as objects or cpusets.

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 --include-disallowed is given.

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).

The -a switch can be used to show all processes, if desired.

EXAMPLES

If a process is bound, it appears in the default output:
    $ hwloc-ps
    4759    Core: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
To display the binding of already running MPI processes (launched by Open MPI) and append their MPI rank (in MPI_COMM_WORLD) to each line:
    $ hwloc-ps --pid-cmd myscript
    29093    L1dCache:0    myprogram    OMPI_COMM_WORLD_RANK=0
    29094    L1dCache:2    myprogram    OMPI_COMM_WORLD_RANK=1
    29095    L1dCache:1    myprogram    OMPI_COMM_WORLD_RANK=2
    29096    L1dCache:3    myprogram    OMPI_COMM_WORLD_RANK=3
where myscript is a bash script doing:
    #!/bin/sh
    cat /proc/$1/environ 2>/dev/null | xargs --null --max-args=1 echo | grep OMPI_COMM_WORLD_RANK

SEE ALSO
hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1), and hwloc-ps.www/README