path: root/README.md

# procs

**procs** is a replacement for `ps` written in [Rust](https://www.rust-lang.org/).

[![Actions Status](https://github.com/dalance/procs/workflows/Regression/badge.svg)](https://github.com/dalance/procs/actions)
[![codecov](https://codecov.io/gh/dalance/procs/branch/master/graph/badge.svg)](https://codecov.io/gh/dalance/procs)

[![Changelog](https://img.shields.io/badge/changelog-v0.13.2-green.svg)](https://github.com/dalance/procs/blob/master/CHANGELOG.md)
[![Crates.io](https://img.shields.io/crates/v/procs.svg)](https://crates.io/crates/procs)
[![procs](https://snapcraft.io/procs/badge.svg)](https://snapcraft.io/procs)
[![homebrew](https://img.shields.io/homebrew/v/procs.svg)](https://formulae.brew.sh/formula/procs)

## Documentation quick links

* [Features](#features)
* [Platform](#platform)
* [Installation](#installation)
* [Usage](#usage)
* [Configuration](#configuration)

## Features

- Colored and human-readable output
    - Automatic theme detection based on terminal background
- Multi-column keyword search
- Some additional information which are not supported by `ps`
    - TCP/UDP port
    - Read/Write throughput
    - Docker container name
    - More memory information
- Pager support
- Watch mode (like `top`)
- Tree view

## Platform

- Linux is supported.
- macOS is experimentally supported.
    - macOS version is checked on Travis CI environment only.
    - The issues caused by real-machine are welcome.
- Windows is experimentally supported.
    - Paging is not supported

## Installation

### Download binary

Download from [release page](https://github.com/dalance/procs/releases/latest), and extract to the directory in PATH.

### [![Packaging status](https://repology.org/badge/vertical-allrepos/procs.svg)](https://repology.org/project/procs/versions)

### Nixpkgs

You can install from [Nixpkgs](https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/admin/procs/default.nix).

```
nix-env --install procs
```

### snapcraft

You can install from [snapcraft](https://snapcraft.io/procs).

```
sudo snap install procs
```

### homebrew

You can install from [homebrew](https://formulae.brew.sh/formula/procs).

```
brew install procs
```

### MacPorts

You can install from [MacPorts](https://ports.macports.org/port/procs/).

```
sudo port install procs
```

### Alpine Linux

You can install from the [Alpine Linux repository](https://pkgs.alpinelinux.org/packages?name=procs).

The correct repository (see above link for the most up-to-date information) should be enabled before `apk add`.

```
sudo apk add procs
```

### Arch Linux

You can install from the [Arch Linux community repository](https://archlinux.org/packages/community/x86_64/procs/).

```
sudo pacman -S procs
```

### Scoop

You can install with [scoop](https://scoop.sh/).

```
scoop install procs
```

### Fedora

```
sudo dnf install procs
```

### RPM

You can install with rpm.

```
sudo rpm -i https://github.com/dalance/procs/releases/download/v0.13.2/procs-0.13.2-1.x86_64.rpm
```

### Cargo

You can install with [cargo](https://crates.io/crates/procs).

```
cargo install procs
```

## Installation Notes

### Permissions issues

On macOS, normal users can't access any information on other users' processes
On Linux, normal users can't access some information (ex. Read/Write throughput) of other users.

If you want to show this information, you should use `sudo`.

```console
$ sudo procs
[sudo] password for ...:
```

If you want to skip password input, you can add the following entry to `/etc/sudoers`.

```text
[user or group] ALL= NOPASSWD: [procs binary path]
// ex. myuser ALL= NOPASSWD: /usr/local/bin/procs
```

## Usage

In the following screenshots, `config/large.toml` is used as the configuration.

### Show all processes

Type `procs` only. It shows the information of all processes.

```console
procs
```

![procs](https://user-images.githubusercontent.com/4331004/55446625-5e5fce00-55fb-11e9-8914-69e8640d89d7.png)

### Search by non-numeric keyword

If you add any keyword as argument, it is matched to `USER`, `Command` by default.

```console
procs zsh
```

If you want to add columns matching to non-numeric keyword, `nonnumeric_search` option can be used in configuration file.

![procs_zsh](https://user-images.githubusercontent.com/4331004/55446648-71729e00-55fb-11e9-8e12-1ca63911c568.png)

### Search by numeric keyword

If a numeric is used as the keyword, it is matched to `PID` by default.
Numeric is treated as exact match, and non-numeric is treated as partial match by default.

```console
procs --or 6000 60000 60001 16723
```

If you want to add columns matching to numeric keyword, `numeric_search` option can be used in configuration file.

![procs_port](https://user-images.githubusercontent.com/4331004/55446667-83ecd780-55fb-11e9-8959-53209837c4ee.png)

Note that procfs permissions only allow identifying listening ports for processes owned by the current user, so not all ports will show up unless run as root.

### Logical operation of search keywords

If there are some keywords, logical operation between the keywords can be specified by commandline option.

- `--and` : The processes that match with all keywords are shown.
- `--or`  : The processes that match with any keyword are shown.
- `--nand`: The processes are shown unless these match with all keywords.
- `--nor` : The processes are shown unless these match with any keyword.

The default operation can be specified in the [configuration file](#configuration). See `[search]` section.

### Show Docker container name

If you have access permission to docker daemon ( `unix:///var/run/docker.sock` ), `Docker` column is added.

```console
procs growi
```

![procs_docker](https://user-images.githubusercontent.com/4331004/55446681-91a25d00-55fb-11e9-943d-5b5caeb23c62.png)

Note that procs gets the container information through UNIX domain socket, so [Docker Toolbox](https://docs.docker.com/toolbox/) on macOS (doesn't use UNIX domain socket) is not supported.
[Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/) is supported but not tested.

### Pager

If output lines exceed terminal height, pager is used automatically.
This behavior and pager command can be specified by configuration file.

### Watch mode

If `--watch` or `--watch-interval <second>` option is used, procs automatically updates output like `top`.
If `--watch` is used, the update interval becomes 1s.
The update interval can be specified by the argument of `--watch-interval`.
There are some keyboard shortcuts to control.

- `n`: Change the sort column to the next column
- `p`: Change the sort column to the previous column
- `a`: Change the sort order to ascending
- `d`: Change the sort order to descending
- `q`: Quit

### Tree view

If `--tree` option is used, processes are sorted by dependency order and dependency tree is shown at left side.

```console
procs --tree
```

![procs_tree](https://user-images.githubusercontent.com/4331004/55446692-9ff07900-55fb-11e9-8b66-a8432df0a8e1.png)

If `TreeSlot` column exists in config, dependency tree is shown at the slot.

### Sort column

Column sort order can be changed by `--sorta` or `--sortd` option.
The last character of `--sorta` and `--sortd` means sort order: "a"scending and "d"escending.

The column for sort is selected by the option keyword.
The keyword is matched with column kind that is shown by `--list` option.
If `--sorta cputime`, column is sorted by `CpuTime` with ascending order.
If `--sortd rss`, column is sorted by `VmRss` with descending order.
The keyword is matched partially and case is ignored.

The default sort is specified by `[sort]` section in the [configuration file](#configuration).

```console
procs --sortd cpu
```

![procs_sort](https://user-images.githubusercontent.com/4331004/55446704-ab43a480-55fb-11e9-81dc-e3ac1a1e2507.png)

### Insert column

`--insert` option inserts new column to the position of `Slot` column or `MultiSlot` column.
The column for insert is selected by the option keyword.
The keyword is the same as sort option.
A `Slot` column can be used by a inserted column.
If many insertion is required, many `Slot` should be added.
A `MultiSlot` column can be used by many inserted column.
If there is a `MultiSlot`, all the remaining columns are inserted to the `MultiSlot`, and the subsequent `Slot` / `MultiSlot` is not used.
Unused `Slot` / `MultiSlot` is not shown.

### Shell completion

`--completion` option generates shell completion files under the current directory.
The following shells are supported.

 * `zsh`
 * `bash`
 * `fish`
 * `powershell`
 * `elvish`

`--completion-out` option generates shell completion to stdout.
You can source it directly on some shells.

```console
source <(procs --completion-out bash)
```

## Configuration

You can change configuration by writing a configuration file.
There are some configuration examples in `config` directory of this repository.
`config/large.toml` is the default configuration before procs v0.9.21.

The location of the configuration file is OS-specific:

 * Linux: `~/.config/procs/config.toml`
 * macOS: `~/Library/Preferences/com.github.dalance.procs/config.toml`
 * Windows: `~/AppData/Roaming/dalance/procs/config/config.toml`

For compatibility, if `~/.procs.toml` exists, it will be preferred to
the OS-specific locations.

The complete example of a configuration file can be generated by `--config` option.

```toml
[[columns]]
kind = "Pid"
style = "BrightYellow|Yellow"
numeric_search = true
nonnumeric_search = false

[[columns]]
kind = "Username"
style = "BrightGreen|Green"
numeric_search = false
nonnumeric_search = true
align = "Right"

[style]
header = "BrightWhite|Black"
unit = "BrightWhite|Black"
tree = "BrightWhite|Black"

[style.by_percentage]
color_000 = "BrightBlue|Blue"
color_025 = "BrightGreen|Green"
color_050 = "BrightYellow|Yellow"
color_075 = "BrightRed|Red"
color_100 = "BrightRed|Red"

[style.by_state]
color_d = "BrightRed|Red"
color_r = "BrightGreen|Green"
color_s = "BrightBlue|Blue"
color_t = "BrightCyan|Cyan"
color_z = "BrightMagenta|Magenta"
color_x = "BrightMagenta|Magenta"
color_k = "BrightYellow|Yellow"
color_w = "BrightYellow|Yellow"
color_p = "BrightYellow|Yellow"

[style.by_unit]
color_k = "BrightBlue|Blue"
color_m = "BrightGreen|Green"
color_g = "BrightYellow|Yellow"
color_t = "BrightRed|Red"
color_p = "BrightRed|Red"
color_x = "BrightBlue|Blue"

[search]
numeric_search = "Exact"
nonnumeric_search = "Partial"
logic = "And"

[display]
show_self = false
show_thread = false
show_thread_in_tree = true
cut_to_terminal = true
cut_to_pager = false
cut_to_pipe = false
color_mode = "Auto"

[sort]
column = 0
order = "Ascending"

[docker]
path = "unix:///var/run/docker.sock"

[pager]
mode = "Auto"
```

### `[[columns]]` section

`[[columns]]` section defines which columns are used.
The first `[[columns]]` is shown at left side, and the last is shown at right side.

| Key               | Value               | Default | Description                                                 |
| ----------------- | ------------------- | ------- | ----------------------------------------------------------- |
| kind              | See `kind` list     |         | Column type                                                 |
| style             | See `style` list    |         | Column style                                                |
| numeric_search    | true, false         | false   | Whether the column can be matched with numeric keywords     |
| nonnumeric_search | true, false         | false   | Whether the column can be matched with non-numeric keywords |
| align             | Left, Right, Center | Left    | Text alignment                                              |
| max_width         | [Number]            |         | Maximum column width                                        |
| min_width         | [Number]            |         | Minimum column width                                        |
| header            | [String]            |         | Alternate header description                                |

#### `kind` list

| procs `kind` | `ps` STANDARD FORMAT  | Description                                   | Linux | macOS | Windows |
| ------------ | --------------------- | --------------------------------------------- | ----- | ----- | ------- |
| Command      | args                  | Command with all arguments                    | o     | o     | o       |
| ContextSw    | -not supported-       | Context switch count                          | o     | o     |         |
| CpuTime      | cputime               | Cumulative CPU time                           | o     | o     | o       |
| Docker       | -not supported-       | Docker container name                         | o     | o     |         |
| Eip          | eip                   | Instruction pointer                           | o     |       |         |
| ElapsedTime  | -not supported-       | Elapsed time                                  | o     | o     | o       |
| Esp          | esp                   | Stack pointer                                 | o     |       |         |
| Gid          | egid                  | Group ID                                      | o     | o     | o       |
| GidFs        | fgid                  | File system group ID                          | o     |       |         |
| GidReal      | rgid                  | Real group ID                                 | o     | o     |         |
| GidSaved     | sgid                  | Saved group ID                                | o     | o     |         |
| Group        | egroup                | Group name                                    | o     | o     | o       |
| GroupFs      | fgroup                | File system group name                        | o     |       |         |
| GroupReal    | rgroup                | Real group name                               | o     | o     |         |
| GroupSaved   | sgroup                | Saved group name                              | o     | o     |         |
| MajFlt       | maj_flt               | Major page fault count                        | o     | o     | o       |
| MinFlt       | min_flt               | Minor page fault count                        | o     | o     |         |
| MultiSlot    | -not supported-       | Slot for `--insert` option                    | o     | o     | o       |
| Nice         | ni                    | Nice value                                    | o     | o     |         |
| Pgid         | pgid                  | Process group ID                              | o     | o     |         |
| Pid          | pid                   | Process ID ( or Thread ID sorrunded by `[]` ) | o     | o     | o       |
| Policy       | policy                | Scheduling policy                             | o     | o     |         |
| Ppid         | ppid                  | Parent process ID                             | o     | o     | o       |
| Priority     | pri                   | Priority                                      | o     | o     | o       |
| Processor    | psr                   | Currently assigned processor                  | o     |       |         |
| ReadBytes    | -not supported-       | Read bytes from storage                       | o     | o     | o       |
| RtPriority   | rtprio                | Real-time priority                            | o     |       |         |
| Separator    | -not supported-       | Show `\|` for column separation               | o     | o     | o       |
| Session      | sid                   | Session ID                                    | o     | o     |         |
| ShdPnd       | pending               | Pending signal mask for process               | o     |       |         |
| SigBlk       | blocked               | Blocked signal mask                           | o     |       |         |
| SigCgt       | caught                | Caught signal mask                            | o     |       |         |
| SigIgn       | ignored               | Ignored signal mask                           | o     |       |         |
| SigPnd       | pending               | Pending signal mask for thread                | o     |       |         |
| Slot         | -not supported-       | Slot for `--insert` option                    | o     | o     | o       |
| Ssb          | -not supported-       | Speculative store bypass status               | o     |       |         |
| StartTime    | start_time            | Starting time                                 | o     | o     | o       |
| State        | s                     | Process state                                 | o     | o     |         |
| TcpPort      | -not supported-       | Bound TCP ports                               | o     | o     |         |
| Threads      | nlwp                  | Thread count                                  | o     | o     |         |
| TreeSlot     | -not supported-       | Slot for tree column                          | o     | o     | o       |
| Tty          | tty                   | Controlling TTY                               | o     | o     |         |
| UdpPort      | -not supported-       | Bound UDP ports                               | o     | o     |         |
| Uid          | euid                  | User ID                                       | o     | o     | o       |
| UidFs        | fuid                  | File system user ID                           | o     |       |         |
| UidLogin     | -not supported-       | Login user ID                                 | o     |       |         |
| UidReal      | ruid                  | Real user ID                                  | o     | o     |         |
| UidSaved     | suid                  | Saved user ID                                 | o     | o     |         |
| UsageCpu     | %cpu                  | CPU utilization                               | o     | o     | o       |
| UsageMem     | %mem                  | Memory utilization                            | o     | o     | o       |
| User         | euser                 | User name                                     | o     | o     | o       |
| UserFs       | fuser                 | File system user name                         | o     |       |         |
| UserLogin    | -not supported-       | Login user name                               | o     |       |         |
| UserReal     | ruser                 | Real user name                                | o     | o     |         |
| UserSaved    | suser                 | Saved user name                               | o     | o     |         |
| VmData       | -not supported-       | Data size                                     | o     |       |         |
| VmExe        | trs                   | Text segments size                            | o     |       |         |
| VmHwm        | -not supported-       | Peak resident set size                        | o     |       | o       |
| VmLib        | -not supported-       | Library code size                             | o     |       |         |
| VmLock       | -not supported-       | Locked memory size                            | o     |       |         |
| VmPeak       | -not supported-       | Peak virtual memory size                      | o     |       | o       |
| VmPin        | -not supported-       | Pinned memory size                            | o     |       | o       |
| VmPte        | -not supported-       | Page table entries size                       | o     |       |         |
| VmRss        | rss                   | Resident set size                             | o     | o     | o       |
| VmSize       | vsz                   | Physical page size                            | o     | o     | o       |
| VmStack      | -not supported-       | Stack size                                    | o     |       |         |
| VmSwap       | -not supported-       | Swapped-out virtual memory size               | o     |       | o       |
| Wchan        | wchan                 | Process sleeping kernel function              | o     |       |         |
| WriteByte    | -not supported-       | Write bytes to storage                        | o     | o     | o       |

#### `style` list

- BrightBlack
- BrightRed
- BrightGreen
- BrightYellow
- BrightBlue
- BrightMagenta
-