Struct psutil::process::Process

pub struct Process {
    pub pid: PID,
    pub uid: UID,
    pub gid: GID,
    pub comm: String,
    pub state: State,
    pub ppid: PID,
    pub pgrp: i32,
    pub session: i32,
    pub tty_nr: i32,
    pub tpgid: i32,
    pub flags: u32,
    pub minflt: u64,
    pub cminflt: u64,
    pub majflt: u64,
    pub cmajflt: u64,
    pub utime: f64,
    pub utime_ticks: u64,
    pub stime: f64,
    pub stime_ticks: u64,
    pub cutime: f64,
    pub cutime_ticks: i64,
    pub cstime: f64,
    pub cstime_ticks: i64,
    pub priority: i64,
    pub nice: i64,
    pub num_threads: i64,
    pub starttime: f64,
    pub starttime_ticks: u128,
    pub vsize: u64,
    pub rss: i64,
    pub rsslim: u64,
    pub wchan: u64,
    pub exit_signal: i32,
    pub processor: i32,
    pub rt_priority: u32,
    pub policy: u32,
    pub delayacct_blkio: f64,
    pub delayacct_blkio_ticks: u128,
    pub guest_time: f64,
    pub guest_time_ticks: u64,
    pub cguest_time: f64,
    pub cguest_time_ticks: i64,
    pub exit_code: i32,
    // some fields omitted
}

Information about a process gathered from /proc/[pid]/stat.

More information about specific fields can be found in proc(5).

Field sizes

The manual pages for proc define integer sizes using scanf(3) format specifiers, which parse to implementation specific sizes. This is obviously a terrible idea, and so this code makes some assumptions about the sizes of those specifiers.

These assumptions are backed up by libc::types::os::arch::posix88::pid_t, which declares PIDs to be signed 32 bit integers. proc(5) declares that PIDs use the %d format specifier.

• %d / %u - 32 bit signed and unsigned integers
• %ld / %lu - 64 bit signed and unsigned integers
• %llu - 128 bit unsigned integers

CPU time fields and clock ticks

The CPU time fields are very strange. Inside the Linux kernel they each use the same type (array.c:361) but when printed use different types (array.c:456) - the fields utime, stime and gtime are unsigned integers, whereas cutime, cstime and cgtime are signed integers.

These values are all returned as a number of clock ticks, which can be divided by sysconf(_SC_CLK_TCK) to get a value in seconds. The Process struct does this conversion automatically, and all CPU time fields use the f64 type. A corresponding _ticks field (e.g. utime_ticks gives the raw number of ticks as found in /proc.

Unmaintained fields

The itrealvalue [20], nswap [35] and cnswap [36] fields are not maintained, and in some cases are hardcoded to 0 in the kernel. The signal [30], blocked [31], sigignore [32] and sigcatch [33] fields are included as private fields, but proc(5) recommends the use of /proc/[pid]/status instead.

Examples

psutil::process::Process::new(psutil::getpid()).unwrap();

Fields

pid: PID

PID of the process.

uid: UID

UID of the process.

gid: GID

UID of the process.

comm: String

Filename of the executable.

state: State

State of the process as an enum.

ppid: PID

PID of the parent process.

pgrp: i32

Process group ID.

session: i32

Session ID.

tty_nr: i32

Controlling terminal of the process [TODO: Actually two numbers].

tpgid: i32

ID of the foreground group of the controlling terminal.

flags: u32

Kernel flags for the process.

minflt: u64

Minor faults.

cminflt: u64

Minor faults by child processes.

majflt: u64

Major faults.

cmajflt: u64

Major faults by child processes.

utime: f64

Time scheduled in user mode (seconds).

utime_ticks: u64

Time scheduled in user mode (ticks).

stime: f64

Time scheduled in kernel mode (seconds).

stime_ticks: u64

Time scheduled in kernel mode (ticks).

cutime: f64

Time waited-for child processes were scheduled in user mode (seconds).

cutime_ticks: i64

Time waited-for child processes were scheduled in user mode (ticks).

cstime: f64

Time waited-for child processes were scheduled in kernel mode (seconds).

cstime_ticks: i64

Time waited-for child processes were scheduled in kernel mode (ticks).

priority: i64

Priority value (-100..-2 | 0..39).

nice: i64

Nice value (-20..19).

num_threads: i64

Number of threads in the process.

starttime: f64

Time the process was started after system boot (seconds).

starttime_ticks: u128

Time the process was started after system boot (ticks).

vsize: u64

Virtual memory size in bytes.

rss: i64

Resident Set Size (bytes).

rsslim: u64

Current soft limit on process RSS (bytes).

wchan: u64

Channel the process is waiting on (address of a system call).

exit_signal: i32

Signal sent to parent when process dies.

processor: i32

Number of the CPU the process was last executed on.

rt_priority: u32

Real-time scheduling priority (0 | 1..99).

policy: u32

Scheduling policy.

delayacct_blkio: f64

Aggregated block I/O delays (seconds).

delayacct_blkio_ticks: u128

Aggregated block I/O delays (ticks).

guest_time: f64

Guest time of the process (seconds).

guest_time_ticks: u64

Guest time of the process (ticks).

cguest_time: f64

Guest time of the process's children (seconds).

cguest_time_ticks: i64

Guest time of the process's children (ticks).

exit_code: i32

The thread's exit status.

Methods

impl Process

pub fn new(pid: PID) -> Result<Process>

Attempts to read process information from /proc/[pid]/stat.

Some additional metadata is read from the permissions on the /proc/[pid]/, which defines the process UID/GID. The format of /proc/[pid]/stat format is defined in proc(5).

pub fn from_pidfile<P>(path: P) -> Result<Process> where
    P: AsRef<Path>, 

Create a Process by reading its PID from a pidfile.

pub fn is_alive(&self) -> bool

Return true if the process was alive at the time it was read.

pub fn cmdline_vec(&self) -> Result<Option<Vec<String>>>

Read /proc/[pid]/cmdline as a vector.

Returns Err if /proc/[pid]/cmdline is empty.

pub fn cmdline(&self) -> Result<Option<String>>

Return the result of cmdline_vec as a String.

pub fn cwd(&self) -> Result<PathBuf>

Read the path of the process' current working directory.

pub fn exe(&self) -> Result<PathBuf>

Read the absolute path of the process

pub fn environ(&self) -> Result<HashMap<String, String>>

pub fn memory(&self) -> Result<Memory>

Reads /proc/[pid]/statm into a struct.

pub fn open_fds(&self) -> Result<Vec<Fd>>

Reads /proc/[pid]/fd directory

pub fn kill(&self) -> Result<()>

Send SIGKILL to the process.

Trait Implementations

impl Clone for Process

fn clone(&self) -> Process

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl PartialEq<Process> for Process

fn eq(&self, other: &Process) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Debug for Process

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.