https://github.com/Freaky/rust-proctitle
A safe cross-platform interface to setting process titles
https://github.com/Freaky/rust-proctitle
Last synced: 10 months ago
JSON representation
A safe cross-platform interface to setting process titles
- Host: GitHub
- URL: https://github.com/Freaky/rust-proctitle
- Owner: Freaky
- License: mit
- Created: 2019-04-25T02:05:24.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2019-04-28T18:18:59.000Z (about 7 years ago)
- Last Synced: 2024-11-23T19:36:09.090Z (over 1 year ago)
- Language: Rust
- Size: 18.6 KB
- Stars: 16
- Watchers: 3
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# proctitle
[][crate]
[](https://travis-ci.org/Freaky/rust-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.
```rust
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:
```sh
-% 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)`][prctl] 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.
#### 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.
[`setproctitle()`]: https://www.freebsd.org/cgi/man.cgi?query=setproctitle&sektion=3
[prctl]: http://man7.org/linux/man-pages/man2/prctl.2.html
[`SetConsoleTitleW()`]: https://docs.microsoft.com/en-us/windows/console/setconsoletitle
[event handle]: https://docs.microsoft.com/en-us/windows/desktop/api/synchapi/nf-synchapi-createeventa
[Process Explorer]: https://docs.microsoft.com/en-us/sysinternals/downloads/process-explorer
[Process Hacker]: https://processhacker.sourceforge.io/
[crate]: https://crates.io/crates/proctitle