diff options
Diffstat (limited to '')
| -rw-r--r-- | htop.1.in | 695 |
1 files changed, 695 insertions, 0 deletions
diff --git a/htop.1.in b/htop.1.in new file mode 100644 index 0000000..2376b7a --- /dev/null +++ b/htop.1.in @@ -0,0 +1,695 @@ +.TH "HTOP" "1" "2024" "@PACKAGE_STRING@" "User Commands" +.SH "NAME" +htop, pcp-htop \- interactive process viewer +.SH "SYNOPSIS" +.B htop +.RB [ \-dCFhpustvH ] +.br +.B pcp\ htop +.RB [ \-dCFhpustvH ] +.RB [ \-\-host/-h\ host ] +.SH "DESCRIPTION" +.B htop +is a cross-platform ncurses-based process viewer. +.LP +It is similar to +.BR top , +but allows you to scroll vertically and horizontally, and interact using +a pointing device (mouse). +You can observe all processes running on the system, along with their +command line arguments, as well as view them in a tree format, select +multiple processes and act on them all at once. +.LP +Tasks related to processes (killing, renicing) can be done without +entering their PIDs. +.LP +.B pcp-htop +is a version of +.B htop +built using the Performance Co-Pilot (PCP) Metrics API (see \c +.BR PCPIntro (1), +.BR PMAPI (3)), +allowing to extend +.B htop +to display values from arbitrary metrics. +See the section below titled +.B "CONFIG FILES" +for further details. +.br +.SH "COMMAND-LINE OPTIONS" +Mandatory arguments to long options are mandatory for short options too. +.TP +\fB\-d \-\-delay=DELAY\fR +Delay between updates, in tenths of a second. If the delay value is +less than 1, it is increased to 1, i.e. 1/10 second. If the delay value +is greater than 100, it is decreased to 100, i.e. 10 seconds. +.TP +\fB\-C \-\-no-color \-\-no-colour\fR +Start +.B htop +in monochrome mode +.TP +\fB\-F \-\-filter=FILTER +Filter processes by terms matching the commands. The terms are matched +case-insensitive and as fixed strings (not regexs). You can separate multiple terms with "|". +.TP +\fB\-h \-\-help +Display a help message and exit +.TP +\fB\-p \-\-pid=PID,PID...\fR +Show only the given PIDs +.TP +\fB\-s \-\-sort\-key COLUMN\fR +Sort by this column (use \-\-sort\-key help for a column list). +This will force a list view unless you specify -t at the same time. +.TP +\fB\-u \-\-user=USERNAME|UID\fR +Show only the processes of a given user +.TP +\fB\-U \-\-no-unicode\fR +Do not use unicode but ASCII characters for graph meters +.TP +\fB\-M \-\-no-mouse\fR +Disable support of mouse control +.TP +\fB\-\-readonly\fR +Disable all system and process changing features +.TP +\fB\-V \-\-version +Output version information and exit +.TP +\fB\-t \-\-tree +Show processes in tree view. This can be used to force a tree view when +requesting a sort order with -s. +.TP +\fB\-H \-\-highlight-changes=DELAY\fR +Highlight new and old processes +.TP +\fB \-\-drop-capabilities[=off|basic|strict]\fR +Linux only; requires libcap support. +.br +Drop unneeded Linux capabilities. +In strict mode features like killing, changing process priorities, and reading +process delay accounting information will not work, due to less capabilities +held. +.SH "INTERACTIVE COMMANDS" +The following commands are supported while in +.BR htop : +.TP 5 +.B Tab, Shift-Tab +Select the next / the previous screen tab to display. +You can enable showing the screen tab names in the Setup screen (F2). +.TP +.B Up, Alt-k +Select (highlight) the previous process in the process list. Scroll the list +if necessary. +.TP +.B Down, Alt-j +Select (highlight) the next process in the process list. Scroll the list if +necessary. +.TP +.B Left, Alt-h +Scroll the process list left. +.TP +.B Right, Alt-l +Scroll the process list right. +.TP +.B PgUp, PgDn +Scroll the process list up or down one window. +.TP +.B Home +Scroll to the top of the process list and select the first process. +.TP +.B End +Scroll to the bottom of the process list and select the last process. +.TP +.B Ctrl-A, ^ +Scroll left to the beginning of the process entry (i.e. beginning of line). +.TP +.B Ctrl-E, $ +Scroll right to the end of the process entry (i.e. end of line). +.TP +.B Space +Tag or untag a process. Commands that can operate on multiple processes, +like "kill", will then apply over the list of tagged processes, instead +of the currently highlighted one. +.TP +.B c +Tag the current process and its children. Commands that can operate on multiple +processes, like "kill", will then apply over the list of tagged processes, +instead of the currently highlighted one. +.TP +.B U +Untag all processes (remove all tags added with the Space or c keys). +.TP +.B s +Trace process system calls: if strace(1) is installed, pressing this key +will attach it to the currently selected process, presenting a live +update of system calls issued by the process. +.TP +.B l +Display open files for a process: if lsof(1) is installed, pressing this key +will display the list of file descriptors opened by the process. +.TP +.B w +Display the command line of the selected process in a separate screen, wrapped +onto multiple lines as needed. +.TP +.B x +Display the active file locks of the selected process in a separate screen. +.TP +.B F1, h, ? +Go to the help screen +.TP +.B F2, S +Go to the setup screen, where you can configure the meters displayed at the top +of the screen, set various display options, choose among color schemes, and +select which columns are displayed, in which order. +.TP +.B F3, / +Incrementally search the command lines of all the displayed processes. The +currently selected (highlighted) command will update as you type. While in +search mode, pressing F3 will cycle through matching occurrences. +Pressing Shift-F3 will cycle backwards. + +Alternatively the search can be started by simply typing the command +you are looking for, although for the first character normal key +bindings take precedence. +.TP +.B F4, \\\\ +Incremental process filtering: type in part of a process command line and +only processes whose names match will be shown. To cancel filtering, +enter the Filter option again and press Esc. +The matching is done case-insensitive. Terms are fixed strings (no regex). +You can separate multiple terms with "|". +.TP +.B F5, t +Tree view: organize processes by parenthood, and layout the relations +between them as a tree. Toggling the key will switch between tree and +your previously selected sort view. Selecting a sort view will exit +tree view. +.TP +.B F6, <, > +Selects a field for sorting, also accessible through < and >. +The current sort field is indicated by a highlight in the header. +.TP +.B F7, ] +Increase the selected process's priority (subtract from 'nice' value). +This can only be done by the superuser. +.TP +.B F8, [ +Decrease the selected process's priority (add to 'nice' value) +.TP +.B Shift-F7, } +Increase the selected process's autogroup priority (subtract from autogroup 'nice' value). +This can only be done by the superuser. +.TP +.B Shift-F8, { +Decrease the selected process's autogroup priority (add to autogroup 'nice' value) +.TP +.B F9, k +"Kill" process: sends a signal which is selected in a menu, to one or a group +of processes. If processes were tagged, sends the signal to all tagged processes. +If none is tagged, sends to the currently selected process. +.TP +.B F10, q +Quit +.TP +.B I +Invert the sort order: if sort order is increasing, switch to decreasing, and +vice-versa. +.TP +.B +, \-, * +When in tree view mode, expand or collapse subtree. When a subtree is collapsed +a "+" sign shows to the left of the process name. +Pressing "*" will expand or collapse all children of PIDs without parents, so +typically PID 1 (init) and PID 2 (kthreadd on Linux, if kernel threads are shown). +.TP +.B a (on multiprocessor machines) +Set CPU affinity: mark which CPUs a process is allowed to use. +.TP +.B u +Show only processes owned by a specified user. +.TP +.B N +Sort by PID. +.TP +.B M +Sort by memory usage (top compatibility key). +.TP +.B P +Sort by processor usage (top compatibility key). +.TP +.B T +Sort by time (top compatibility key). +.TP +.B F +"Follow" process: if the sort order causes the currently selected process +to move in the list, make the selection bar follow it. This is useful for +monitoring a process: this way, you can keep a process always visible on +screen. When a movement key is used, "follow" loses effect. +.TP +.B K +Hide kernel threads: prevent the threads belonging the kernel to be +displayed in the process list. (This is a toggle key.) +.TP +.B H +Hide user threads: on systems that represent them differently than ordinary +processes (such as recent NPTL-based systems), this can hide threads from +userspace processes in the process list. (This is a toggle key.) +.TP +.B O +Hide containerized processes: prevent processes running in a container +from being displayed in the process list. (This is a toggle key.) +.TP +.B p +Show full paths to running programs, where applicable. (This is a toggle key.) +.TP +.B Z +Pause/resume process updates. +.TP +.B m +Merge exe, comm and cmdline, where applicable. (This is a toggle key.) +.TP +.B Ctrl-L +Refresh: redraw screen and recalculate values. +.TP +.B Numbers +PID search: type in process ID and the selection highlight will be moved to it. +.PD +.SH "COLUMNS" +The following columns can display data about each process. A value of '\-' in +all the rows indicates that a column is unsupported on your system, or +currently unimplemented in +.BR htop . +The names below are the ones used in the +"Available Columns" section of the setup screen. If a different name is +shown in +.BR htop 's +main screen, it is shown below in parenthesis. +.TP 5 +.B Command +The full command line of the process (i.e. program name and arguments). + +If the option 'Merge exe, comm and cmdline in Command' (toggled by the 'm' key) +is active, the executable path (/proc/[pid]/exe) and the command name +(/proc/[pid]/comm) are also shown merged with the command line, if available. + +The program basename is highlighted if set in the configuration. Additional +highlighting can be configured for stale executables (cf. EXE column below). +.TP +.B COMM +The command name of the process obtained from /proc/[pid]/comm, if readable. + +Requires Linux kernel 2.6.33 or newer. +.TP +.B EXE +The abbreviated basename of the executable of the process, obtained from +/proc/[pid]/exe, if readable. htop is able to read this file on linux for ALL +the processes only if it has the capability CAP_SYS_PTRACE or root privileges. + +The basename is marked in red if the executable used to run the process has +been replaced or deleted on disk since the process started. The information is +obtained by processing the contents of /proc/[pid]/exe. + +Furthermore the basename is marked in yellow if any library is reported as having +been replaced or deleted on disk since it was last loaded. The information is +obtained by processing the contents of /proc/[pid]/maps. + +When deciding the color the replacement of the main executable always takes +precedence over replacement of any other library. If only the memory map indicates +a replacement of the main executable, this will show as if any other library had +been replaced or deleted. + +This additional color markup can be configured in the "Display Options" section of +the setup screen. + +Displaying EXE requires CAP_SYS_PTRACE and PTRACE_MODE_READ_FSCRED. +.TP +.B PID +The process ID. +.TP +.B STATE (S) +The state of the process: + \fBS\fR for sleeping + \fBI\fR for idle (longer inactivity than sleeping on platforms that distinguish) + \fBR\fR for running + \fBD\fR for disk sleep (uninterruptible) + \fBZ\fR for zombie (waiting for parent to read its exit status) + \fBT\fR for traced or suspended (e.g by SIGTSTP) + \fBW\fR for paging +.TP +.B PPID +The parent process ID. +.TP +.B PGRP +The process's group ID. +.TP +.B SESSION (SID) +The process's session ID. +.TP +.B TTY +The controlling terminal of the process. +.TP +.B TPGID +The process ID of the foreground process group of the controlling terminal. +.TP +.B MINFLT +The number of page faults happening in the main memory. +.TP +.B CMINFLT +The number of minor faults for the process's waited-for children (see MINFLT above). +.TP +.B MAJFLT +The number of page faults happening out of the main memory. +.TP +.B CMAJFLT +The number of major faults for the process's waited-for children (see MAJFLT above). +.TP +.B UTIME (UTIME+) +The user CPU time, which is the amount of time the process has spent executing +on the CPU in user mode (i.e. everything but system calls), measured in clock +ticks. +.TP +.B STIME (STIME+) +The system CPU time, which is the amount of time the kernel has spent +executing system calls on behalf of the process, measured in clock ticks. +.TP +.B CUTIME (CUTIME+) +The children's user CPU time, which is the amount of time the process's +waited-for children have spent executing in user mode (see UTIME above). +.TP +.B CSTIME (CSTIME+) +The children's system CPU time, which is the amount of time the kernel has spent +executing system calls on behalf of all the process's waited-for children (see +STIME above). +.TP +.B PRIORITY (PRI) +The kernel's internal priority for the process, usually just its nice value +plus twenty. Different for real-time processes. +.TP +.B NICE (NI) +The nice value of a process, from 19 (low priority) to -20 (high priority). A +high value means the process is being nice, letting others have a higher +relative priority. The usual OS permission restrictions for adjusting priority apply. +.TP +.B STARTTIME (START) +The time the process was started. +.TP +.B PROCESSOR (CPU) +The ID of the CPU the process last executed on. +.TP +.B M_VIRT (VIRT) +The size of the virtual memory of the process. +.TP +.B M_RESIDENT (RES) +The resident set size (text + data + stack) of the process (i.e. the size of the +process's used physical memory). +.TP +.B M_SHARE (SHR) +The size of the process's shared pages. +.TP +.B M_TRS (CODE) +The text resident set size of the process (i.e. the size of the process's +executable instructions). +.TP +.B M_DRS (DATA) +The data resident set size (data + stack) of the process (i.e. the size of anything +except the process's executable instructions). +.TP +.B M_LRS (LIB) +The library size of the process. +.TP +.B M_SWAP (SWAP) +The size of the process's swapped pages. +.TP +.B M_PSS (PSS) +The proportional set size, same as M_RESIDENT but each page is divided by the +number of processes sharing it. +.TP +.B M_M_PSSWP (PSSWP) +The proportional swap share of this mapping, unlike M_SWAP this does not take +into account swapped out page of underlying shmem objects. +.TP +.B ST_UID (UID) +The user ID of the process owner. +.TP +.B PERCENT_CPU (CPU%) +The percentage of the CPU time that the process is currently using. +This is the default way to represent CPU usage in Linux. Each process can +consume up to 100% which means the full capacity of the core it is running +on. This is sometimes called "Irix mode" e.g. in +.BR top (1). +.TP +.B PERCENT_NORM_CPU (NCPU%) +The percentage of the CPU time that the process is currently using normalized +by CPU count. This is sometimes called "Solaris mode" e.g. in +.BR top (1). +.TP +.B PERCENT_MEM (MEM%) +The percentage of memory the process is currently using (based on the process's +resident memory size, see M_RESIDENT above). +.TP +.B USER +The username of the process owner, or the user ID if the name can't be +determined. + +On Linux the username is highlighted if the process has elevated privileges, +i.e. if it has been started from binaries with file capabilities set or +retained Linux capabilities, via the ambient set, after switching from the +root user. +.TP +.B TIME (TIME+) +The time, measured in clock ticks that the process has spent in user and system +time (see UTIME, STIME above). +.TP +.B NLWP +The number of Light-Weight Processes (=threads) in the process. +.TP +.B TGID +The thread group ID. +.TP +.B CTID +OpenVZ container ID, a.k.a virtual environment ID. +.TP +.B VPID +OpenVZ process ID. +.TP +.B VXID +VServer process ID. +.TP +.B RCHAR (RD_CHAR) +The number of bytes the process has read. +.TP +.B WCHAR (WR_CHAR) +The number of bytes the process has written. +.TP +.B SYSCR (RD_SYSC) +The number of read(2) syscalls for the process. +.TP +.B SYSCW (WR_SYSC) +The number of write(2) syscalls for the process. +.TP +.B RBYTES (IO_RBYTES) +Bytes of read(2) I/O for the process. +.TP +.B WBYTES (IO_WBYTES) +Bytes of write(2) I/O for the process. +.TP +.B CNCLWB (IO_CANCEL) +Bytes of cancelled write(2) I/O. +.TP +.B IO_READ_RATE (DISK READ) +The I/O rate of read(2) in bytes per second, for the process. +.TP +.B IO_WRITE_RATE (DISK WRITE) +The I/O rate of write(2) in bytes per second, for the process. +.TP +.B IO_RATE (DISK R/W) +The I/O rate, IO_READ_RATE + IO_WRITE_RATE (see above). +.TP +.B CGROUP +Which cgroup the process is in. For a shortened view see the CCGROUP column below. +.TP +.B CCGROUP +Shortened view of the cgroup name that the process is in. +This performs some pattern-based replacements to shorten the displayed string and thus condense the information. + \fB/*.slice\fR is shortened to \fB/[*]\fR (exceptions below) + \fB/system.slice\fR is shortened to \fB/[S]\fR + \fB/user.slice\fR is shortened to \fB/[U]\fR + \fB/user-*.slice\fR is shortened to \fB/[U:*]\fR (directly preceding \fB/[U]\fR before dropped) + \fB/machine.slice\fR is shortened to \fB/[M]\fR + \fB/machine-*.scope\fR is shortened to \fB/[SNC:*]\fR (SNC: systemd nspawn container), uppercase for the monitor + \fB/lxc.monitor.*\fR is shortened to \fB/[LXC:*]\fR + \fB/lxc.payload.*\fR is shortened to \fB/[lxc:*]\fR + \fB/*.scope\fR is shortened to \fB/!*\fR + \fB/*.service\fR is shortened to \fB/*\fR (suffix removed) + +Encountered escape sequences (e.g. from systemd) inside the cgroup name are not decoded. +.TP +.B OOM +OOM killer score. +.TP +.B CTXT +Incremental sum of voluntary and nonvoluntary context switches. +.TP +.B IO_PRIORITY (IO) +The I/O scheduling class followed by the priority if the class supports it: + \fBR\fR for Realtime + \fBB\fR for Best-effort + \fBid\fR for Idle +.TP +.B PERCENT_CPU_DELAY (CPUD%) +The percentage of time spent waiting for a CPU (while runnable). Requires CAP_NET_ADMIN. +.TP +.B PERCENT_IO_DELAY (IOD%) +The percentage of time spent waiting for the completion of synchronous block I/O. Requires CAP_NET_ADMIN. +.TP +.B PERCENT_SWAP_DELAY (SWAPD%) +The percentage of time spent swapping in pages. Requires CAP_NET_ADMIN. +.TP +.B AGRP +The autogroup identifier for the process. Requires Linux CFS to be enabled. +.TP +.B ANI +The autogroup nice value for the process autogroup. Requires Linux CFS to be enabled. +.TP +.B All other flags +Currently unsupported (always displays '-'). +.SH "EXTERNAL LIBRARIES" +While +.B htop +depends on most of the libraries it uses at build time there are two +noteworthy exceptions to this rule. These exceptions both relate to +data displayed in meters displayed in the header of +.B htop +and were intentionally created as optional runtime dependencies instead. +These exceptions are described below: +.TP +.B libsystemd +The bindings for libsystemd are used in the SystemD meter to determine +the number of active services and the overall system state. Looking for +the functions to determine these information at runtime allows for +builds to support these meters without forcing the package manager +to install these libraries on systems that otherwise don't use systemd. + +Summary: no build time dependency, optional runtime dependency on +.B libsystemd +via dynamic loading, with +.B systemctl(1) +fallback. +.TP +.B libsensors +The bindings for libsensors are used for the CPU temperature readings +in the CPU usage meters if displaying the temperature is enabled through +the setup screen. In order for +.B htop +to show these temperatures correctly though, a proper configuration +of libsensors through its usual configuration files is assumed and that +all CPU cores correspond to temperature sensors from the +.B coretemp +driver with core 0 corresponding to a sensor labelled "Core 0". The +package temperature may be given as "Package id 0". If missing it is +inferred as the maximum value from the available per-core readings. + +Summary: build time dependency on +.B libsensors(3) +C header files, optional runtime dependency on +.B libsensors(3) +via dynamic loading. +.SH "CONFIG FILES" +By default +.B htop +reads its configuration from the XDG-compliant path +.IR ~/.config/htop/htoprc . +The configuration file is overwritten upon clean exit by +.BR htop 's +in-program Setup configuration, so it should not be hand-edited. +If no user configuration exists +.B htop +tries to read the system-wide configuration from +.I @sysconfdir@/htoprc +and as a last resort, falls back to its hard coded defaults. +.LP +You may override the location of the configuration file using the $HTOPRC +environment variable (so you can have multiple configurations for different +machines that share the same home directory, for example). +.LP +The +.B pcp-htop +utility makes use of +.I htoprc +in exactly the same way. +In addition, it supports additional configuration files allowing +new meters and columns to be added to the display via the usual +Setup function, which will display additional Available Meters +and Available Column entries for each runtime configured meter +or column. +.LP +These +.B pcp-htop +configuration files are read once at startup. +The format of these files is described in detail in the +.BR pcp-htop (5) +manual page. +.LP +This functionality makes available many thousands of Performance +Co-Pilot metrics for display by +.BR pcp-htop , +as well as the ability to display custom metrics added at individual sites. +Applications and services instrumented using the OpenMetrics format +.B https://openmetrics.io +can also be displayed by +.B pcp-htop +if the +.BR pmdaopenmetrics (1) +component is configured. +.LP +The configuration for both +.B htop +and +.B pcp-htop +is only saved when a clean exit is performed. Sending any signal will cause +.I all configuration changes to be lost. +.SH "MEMORY SIZES" +Memory sizes in +.B htop +are displayed in a human-readable form. +Sizes are printed in powers of 1024 using binary IEC units. +If no suffix is shown the units are implicitly K as in KiB (kibibyte, 1 KiB = 1024 bytes). +.LP +The decision to use this convention was made in order to conserve screen +space and make memory size representations consistent throughout +.B htop +as allocations are granular to full memory pages (4 KiB for most platforms). +.SH "SEE ALSO" +.BR proc (5), +.BR top (1), +.BR free (1), +.BR ps (1), +.BR uptime (1) +and +.BR limits.conf (5). +.SH "SEE ALSO FOR PCP" +.BR pmdaopenmetrics (1), +.BR PCPIntro (1), +.BR PMAPI (3), +and +.BR pcp-htop (5). +.SH "AUTHORS" +.B htop +was originally developed by Hisham Muhammad. +Nowadays it is maintained by the community at <htop@groups.io>. +.LP +.B pcp-htop +is maintained as a collaboration between the <htop@groups.io> and <pcp@groups.io> +communities, and forms part of the Performance Co-Pilot suite of tools. +.SH "COPYRIGHT" +Copyright \(co 2004-2019 Hisham Muhammad. +.br +Copyright \(co 2020-2024 htop dev team. +.LP +License GPLv2+: GNU General Public License version 2 or, at your option, any later version. +.LP +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. |