proctitle

Cross-platform process titles.

proctitle attempts to expose the closest safe approximation of the BSD setproctitle() function on the platforms it supports.

This can be useful if you wish to expose some internal state to top or ps, or to help an administrator distinguish between multiple instances of your program.

use proctitle::set_title;
let tasks = ["frobrinate", "defroogle", "hodor", "bork"];

for task in &tasks {
    set_title(format!("example: {}", task));
    perform_task(task);
}

set_title("example: idle");

On Linux or a BSD you could then watch top or ps and see the process name change as it works:

-% cmd &
[1] 8515
-% ps $!
 PID TT  STAT     TIME COMMAND
8515  4  S+    0:00.06 example: defroggle (cmd)

Supported Platforms

BSD

On BSDs, setproctitle() is used, and should pretty much Just Work. Tested on FreeBSD 12, DragonFlyBSD 5.4, OpenBSD 6.5, and NetBSD 8.0.

Linux

proctitle uses prctl(PR_SET_NAME) to name the current thread, with a truncation limit of 15 bytes. It may be wise to limit set_title() calls to the main thread.

More BSD-ish process-global changes are possible by modifying the process environment, but this is not yet supported because it's wildly unsafe.

macOS

On macOS, proctitle sets the process name as displayed in Activity Monitor by calling private Launch Services APIs at runtime. The current thread name is set via pthread_setname_np().

If the Launch Services APIs are unavailable, the function silently falls back to only setting the thread name.

Windows

SetConsoleTitleW() is used to set a title for the console, if any.

In case there is no console (for example, a system service), a dummy named event handle is also created. This can be found via tools such as Process Explorer (View ⮕ Lower Pane View ⮕ Handles) and Process Hacker (Properties ⮕ Handles).

Everything Else

Unsupported platforms merely receive a stub function that does nothing.