Proctitle

https://docs.rs/proctitle
Admin
Proctitle is a Rust library that provides cross-platform support for setting the title of the...
Tokens:4,631
Snippets:26
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example calling a_crate::a_func in examples/ex.rs

Source: https://docs.rs/proctitle/latest/scrape-examples-help.html

Shows an example file that calls the public function from the library crate, which will be scraped and included in the documentation for that function.

```rust
// examples/ex.rs
fn main() {
  a_crate::a_func();
}
```

--------------------------------

### Example usage in examples/hello.rs

Source: https://docs.rs/proctitle/latest/proctitle/fn.set_title.html?search=std%3A%3Avec

Shows a loop that repeatedly sets the process title to a formatted string with an incrementing counter, then sleeps for 500 milliseconds. The example is from the repository's `examples/hello.rs` file.

```rust
fn main() {
    let mut i = 0;
    loop {
        proctitle::set_title(format!("Hello, world, {}", i));
        i += 1;
        std::thread::sleep(std::time::Duration::from_millis(500));
    }
}
```

--------------------------------

### Example public function in src/lib.rs

Source: https://docs.rs/proctitle/latest/scrape-examples-help.html

Shows a simple public function in a library's source code that can be documented and scraped for examples.

```rust
// src/lib.rs
pub fn a_func() {}
```

--------------------------------

### Command to enable scraping examples with cargo doc

Source: https://docs.rs/proctitle/latest/scrape-examples-help.html

Command to run cargo doc with unstable options to enable Rustdoc's example scraping feature.

```bash
cargo doc -Zunstable-options -Zrustdoc-scrape-examples
```

--------------------------------

### proctitle lib.rs: platform-specific set_title implementations

Source: https://docs.rs/proctitle/latest/src/proctitle/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Complete lib.rs for the proctitle crate. It defines a platform-specific `imp` module with `set_title` for BSD (using `setproctitle`), Linux (using `libc::prctl` with `PR_SET_NAME`), Windows (using `SetConsoleTitleW` and a named event handle), and a no-op fallback for other targets. Includes tests for Linux, Windows, and a generic callable test.

```rust
1#![cfg_attr(feature = "nightly", feature(external_doc))]
2#![cfg_attr(feature = "nightly", doc(include = "../README.md"))]
3
4#[cfg(any(
5    target_os = "freebsd",
6    target_os = "dragonfly",
7    target_os = "netbsd",
8    target_os = "openbsd",
9    target_os = "bitrig",
10))]
11mod imp {
12    use std::ffi::CString;
13    use std::ffi::OsStr;
14    use std::os::unix::ffi::OsStrExt;
15
16    /// Set a process title, or some approximation of it, if possible.
17    pub fn set_title<T: AsRef<OsStr>>(title: T) {
18        if let Ok(title) = CString::new(title.as_ref().to_owned().as_bytes()) {
19            unsafe {
20                setproctitle(b"-%s\0".as_ptr(), title.as_ptr());
21            }
22        }
23    }
24
25    #[link(name = "c")]
26    extern "C" {
27        fn setproctitle(fmt: *const u8, ...);
28    }
29}
30
31#[cfg(target_os = "linux")]
32mod imp {
33    use libc;
34    use std::ffi::CString;
35    use std::ffi::OsStr;
36    use std::os::unix::ffi::OsStrExt;
37
38    /// Set a process title, or some approximation of it, if possible.
39    pub fn set_title<T: AsRef<OsStr>>(title: T) {
40        if let Ok(title) = CString::new(title.as_ref().to_owned().as_bytes()) {
41            unsafe { libc::prctl(libc::PR_SET_NAME, title.as_ptr(), 0, 0, 0) };
42        }
43    }
44
45    #[test]
46    fn set_title_sets_name() {
47        use libc;
48        set_title("abcdefghijklmnopqrstu");
49
50        let mut buf = [0u8; 16];
51        unsafe { libc::prctl(libc::PR_GET_NAME, buf.as_mut_ptr(), 0, 0, 0) };
52        assert_eq!(&buf, b"abcdefghijklmno\0");
53    }
54}
55
56#[cfg(target_os = "windows")]
57mod imp {
58    use std::ffi::OsStr;
59    use std::os::windows::ffi::OsStrExt;
60    use std::sync::Mutex;
61
62    use lazy_static::lazy_static;
63    use winapi::um::handleapi::CloseHandle;
64    use winapi::um::synchapi::CreateEventW;
65    use winapi::um::wincon::SetConsoleTitleW;
66    use winapi::um::winnt::HANDLE;
67
68    struct NamedHandle(HANDLE);
69    unsafe impl Send for NamedHandle {}
70
71    impl From<Vec<u16>> for NamedHandle {
72        fn from(t: Vec<u16>) -> Self {
73            assert!(t.ends_with(&[0]));
74
75            Self(unsafe { CreateEventW(std::ptr::null_mut(), 1, 0, t.as_ptr()) })
76        }
77    }
78
79    impl Drop for NamedHandle {
80        fn drop(&mut self) {
81            if !self.0.is_null() {
82                unsafe { CloseHandle(self.0) };
83            }
84        }
85    }
86
87    lazy_static! {
88        static ref EVENT_HANDLE: Mutex<Option<NamedHandle>> = Mutex::new(None);
89    }
90
91    /// Set a process title, or some approximation of it, if possible.
92    pub fn set_title<T: AsRef<OsStr>>(title: T) {
93        // Windows doesn't appear to have a userspace mechanism to name the current
94        // process.
95        //
96        // Try to set a console title, and in case we're not attached to one,
97        // follow PostgreSQL's lead and create a named event handle that can be
98        // found in Process Explorer, Process Hacker, etc.
99        let mut t: Vec<u16> = title.as_ref().encode_wide().take(1024).collect();
100        t.push(0);
101
102        unsafe { SetConsoleTitleW(t.as_ptr()) };
103
104        EVENT_HANDLE
105            .lock()
106            .expect("event handle lock")
107            .replace(NamedHandle::from(t));
108    }
109
110    #[test]
111    fn set_title_sets_console_title_and_makes_a_handle() {
112        let title = "Pinkle, squirmy, blib, blab, blob";
113        set_title(title);
114
115        let mut t: Vec<u16> = std::ffi::OsString::from(title).encode_wide().collect();
116        t.push(0);
117        let mut buf = vec![0; t.len()];
118        let len =
119            unsafe { winapi::um::wincon::GetConsoleTitleW(buf.as_mut_ptr(), buf.len() as u32) };
120
121        assert_eq!(len, title.len() as u32, "length mismatch");
122        assert_eq!(buf, t, "buffer mismatch");
123        assert!(
124            EVENT_HANDLE.lock().unwrap().is_some(),
125            "event handle missing"
126        );
127    }
128}
129
130#[cfg(not(any(
131    target_os = "freebsd",
132    target_os = "dragonfly",
133    target_os = "netbsd",
134    target_os = "openbsd",
135    target_os = "bitrig",
136    target_os = "linux",
137    target_os = "windows"
138)))]
139mod imp {
140    use std::ffi::OsStr;
141
142    /// Set a process title, or some approximation of it, if possible.
143    pub fn set_title<T: AsRef<OsStr>>(_title: T) {}
144}
145
146pub use self::imp::*;
147
148// This races against the SetConsoleTitle() tests on Windows
149#[cfg(not(windows))]
150#[test]
151fn set_title_is_at_least_callable() {
152    set_title("What was it like being a hamster?");
153    set_title(String::from("It was better than being a chicken."));
154    set_title(std::ffi::OsString::from(
155        "Have you seen the size of an egg?",
156    ));
157}

```

--------------------------------

### BSD-like systems: set_title using setproctitle

Source: https://docs.rs/proctitle/latest/src/proctitle/lib.rs.html

Implementation for FreeBSD, DragonFly, NetBSD, OpenBSD, and Bitrig. It converts the title to a CString and calls the C `setproctitle` function with a format string `-%s`. The function is unsafe and requires the `libc` link.

```rust
#![cfg_attr(feature = "nightly", feature(external_doc))]
#![cfg_attr(feature = "nightly", doc(include = "../README.md"))]

#[cfg(any(
    target_os = "freebsd",
    target_os = "dragonfly",
    target_os = "netbsd",
    target_os = "openbsd",
    target_os = "bitrig",
))]
mod imp {
    use std::ffi::CString;
    use std::ffi::OsStr;
    use std::os::unix::ffi::OsStrExt;

    /// Set a process title, or some approximation of it, if possible.
    pub fn set_title<T: AsRef<OsStr>>(title: T) {
        if let Ok(title) = CString::new(title.as_ref().to_owned().as_bytes()) {
            unsafe {
                setproctitle(b"-%s\0".as_ptr(), title.as_ptr());
            }
        }
    }

    #[link(name = "c")]
    extern "C" {
        fn setproctitle(fmt: *const u8, ...);
    }
}

```

--------------------------------

### set_title

Source: https://docs.rs/proctitle/latest/proctitle/fn.set_title.html?search=std%3A%3Avec

Documentation for the set_title function in the proctitle crate.

```APIDOC
## set_title

### Description
Sets a process title, or some approximation of it, if possible.

### Function Signature
```rust
pub fn set_title<T: AsRef<OsStr>>(title: T)
```

### Parameters
- **title** (`T` where `T: AsRef<OsStr>`) - Required - The new process title to set.

### Example
```rust
proctitle::set_title(format!("Hello, world, {}", i));
```
```

--------------------------------

### set_title

Source: https://docs.rs/proctitle/latest/proctitle/fn.set_title.html

Sets the process title to the given string, or an approximation if the platform does not support exact titles.

```APIDOC
## set_title

### Description
Sets the process title to the given string, or an approximation if the platform does not support exact titles.

### Function Signature
```rust
pub fn set_title<T: AsRef<OsStr>>(title: T)
```

### Parameters
- `title` (T) - Required - The new process title. Accepts any type that implements `AsRef<OsStr>`.

### Example
```rust
proctitle::set_title(format!("Hello, world, {}", i));
```
```

--------------------------------

### Windows: set_title using console title and named event handle

Source: https://docs.rs/proctitle/latest/src/proctitle/lib.rs.html

Implementation for Windows. It sets the console title via `SetConsoleTitleW` and creates a named event handle (using `CreateEventW`) that can be found in tools like Process Explorer. Includes a test verifying the console title and handle creation.

```rust
#[cfg(target_os = "windows")]
mod imp {
    use std::ffi::OsStr;
    use std::os::windows::ffi::OsStrExt;
    use std::sync::Mutex;

    use lazy_static::lazy_static;
    use winapi::um::handleapi::CloseHandle;
    use winapi::um::synchapi::CreateEventW;
    use winapi::um::wincon::SetConsoleTitleW;
    use winapi::um::winnt::HANDLE;

    struct NamedHandle(HANDLE);
    unsafe impl Send for NamedHandle {}

    impl From<Vec<u16>> for NamedHandle {
        fn from(t: Vec<u16>) -> Self {
            assert!(t.ends_with(&[0]));

            Self(unsafe { CreateEventW(std::ptr::null_mut(), 1, 0, t.as_ptr()) })
        }
    }

    impl Drop for NamedHandle {
        fn drop(&mut self) {
            if !self.0.is_null() {
                unsafe { CloseHandle(self.0) };
            }
        }
    }

    lazy_static! {
        static ref EVENT_HANDLE: Mutex<Option<NamedHandle>> = Mutex::new(None);
    }

    /// Set a process title, or some approximation of it, if possible.
    pub fn set_title<T: AsRef<OsStr>>(title: T) {
        // Windows doesn't appear to have a userspace mechanism to name the current
        // process.
        //
        // Try to set a console title, and in case we're not attached to one,
        // follow PostgreSQL's lead and create a named event handle that can be
        // found in Process Explorer, Process Hacker, etc.
        let mut t: Vec<u16> = title.as_ref().encode_wide().take(1024).collect();
        t.push(0);

        unsafe { SetConsoleTitleW(t.as_ptr()) };

        EVENT_HANDLE
            .lock()
            .expect("event handle lock")
            .replace(NamedHandle::from(t));
    }

    #[test]
    fn set_title_sets_console_title_and_makes_a_handle() {
        let title = "Pinkle, squirmy, blib, blab, blob";
        set_title(title);

        let mut t: Vec<u16> = std::ffi::OsString::from(title).encode_wide().collect();
        t.push(0);
        let mut buf = vec![0; t.len()];
        let len =
            unsafe { winapi::um::wincon::GetConsoleTitleW(buf.as_mut_ptr(), buf.len() as u32) };

        assert_eq!(len, title.len() as u32, "length mismatch");
        assert_eq!(buf, t, "buffer mismatch");
        assert!(
            EVENT_HANDLE.lock().unwrap().is_some(),
            "event handle missing"
        );
    }
}

```

--------------------------------

### Fallback: no-op set_title for unsupported platforms

Source: https://docs.rs/proctitle/latest/src/proctitle/lib.rs.html

Implementation for platforms not covered by the specific OS modules. The `set_title` function does nothing.

```rust
#[cfg(not(any(
    target_os = "freebsd",
    target_os = "dragonfly",
    target_os = "netbsd",
    target_os = "openbsd",
    target_os = "bitrig",
    target_os = "linux",
    target_os = "windows"
)))]
mod imp {
    use std::ffi::OsStr;

    /// Set a process title, or some approximation of it, if possible.
    pub fn set_title<T: AsRef<OsStr>>(_title: T) {}
}

```

--------------------------------

### Set process title in a loop with proctitle::set_title

Source: https://docs.rs/proctitle/latest/src/hello/hello.rs.html?search=u32+-%3E+bool

Continuously updates the process title with an incrementing counter every 500 milliseconds. Requires the proctitle crate and is intended for testing or demonstrating the set_title function.

```rust
use proctitle;

fn main() {
    let mut i = 0;
    loop {
        proctitle::set_title(format!("Hello, world, {}", i));
        i += 1;
        std::thread::sleep(std::time::Duration::from_millis(500));
    }
}

```

--------------------------------

### Linux: set_title using prctl and test

Source: https://docs.rs/proctitle/latest/src/proctitle/lib.rs.html

Implementation for Linux using `libc::prctl` with `PR_SET_NAME`. Includes a test that sets a long title and verifies it is truncated to 15 characters plus null terminator.

```rust
#[cfg(target_os = "linux")]
mod imp {
    use libc;
    use std::ffi::CString;
    use std::ffi::OsStr;
    use std::os::unix::ffi::OsStrExt;

    /// Set a process title, or some approximation of it, if possible.
    pub fn set_title<T: AsRef<OsStr>>(title: T) {
        if let Ok(title) = CString::new(title.as_ref().to_owned().as_bytes()) {
            unsafe { libc::prctl(libc::PR_SET_NAME, title.as_ptr(), 0, 0, 0) };
        }
    }

    #[test]
    fn set_title_sets_name() {
        use libc;
        set_title("abcdefghijklmnopqrstu");

        let mut buf = [0u8; 16];
        unsafe { libc::prctl(libc::PR_GET_NAME, buf.as_mut_ptr(), 0, 0, 0) };
        assert_eq!(&buf, b"abcdefghijklmno\0");
    }
}

```

--------------------------------

### Function signature: proctitle::set_title

Source: https://docs.rs/proctitle/latest/proctitle/fn.set_title.html?search=std%3A%3Avec

Declares the public function `set_title` that accepts any type implementing `AsRef<OsStr>` and returns `()`. Use it to set the process title to an approximation if possible.

```rust
pub fn set_title<T: AsRef<OsStr>>(title: T)
```

--------------------------------

### Re-export and generic test for set_title

Source: https://docs.rs/proctitle/latest/src/proctitle/lib.rs.html

Re-exports the platform-specific `imp` module and includes a test that verifies `set_title` is callable with various string types on non-Windows platforms.

```rust
pub use self::imp::*;

// This races against the SetConsoleTitle() tests on Windows
#[cfg(not(windows))]
#[test]
fn set_title_is_at_least_callable() {
    set_title("What was it like being a hamster?");
    set_title(String::from("It was better than being a chicken."));
    set_title(std::ffi::OsString::from(
        "Have you seen the size of an egg?",
    ));
}

```
Tokens:
Raw