1HTOP(1)                          User Commands                         HTOP(1)
2
3
4

NAME

6       pcp-htop - interactive process viewer
7

SYNOPSIS

9       htop [-dCFhpustvH]
10       pcp htop [-dCFhpustvH] [--host/-h host]
11

DESCRIPTION

13       htop is a cross-platform ncurses-based process viewer.
14
15       It  is similar to top, but allows you to scroll vertically and horizon‐
16       tally, and interact using a pointing device (mouse).  You  can  observe
17       all  processes running on the system, along with their command line ar‐
18       guments, as well as view them in a tree format,  select  multiple  pro‐
19       cesses and act on them all at once.
20
21       Tasks  related to processes (killing, renicing) can be done without en‐
22       tering their PIDs.
23
24       pcp-htop is a version of htop  built  using  the  Performance  Co-Pilot
25       (PCP)  Metrics API (see PCPIntro(1), PMAPI(3)), allowing to extend htop
26       to display values from arbitrary metrics.  See the section below titled
27       CONFIG FILES for further details.
28

COMMAND-LINE OPTIONS

30       Mandatory  arguments  to  long  options are mandatory for short options
31       too.
32
33       -d --delay=DELAY
34              Delay between updates, in tenths of a second. If the delay value
35              is  less  than 1, it is increased to 1, i.e. 1/10 second. If the
36              delay value is greater than 100, it is decreased to 100, i.e. 10
37              seconds.
38
39       -C --no-color --no-colour
40              Start htop in monochrome mode
41
42       -F --filter=FILTER
43              Filter  processes  by terms matching the commands. The terms are
44              matched case-insensitive and as fixed strings (not regexs).  You
45              can separate multiple terms with "|".
46
47       -h --help
48              Display a help message and exit
49
50       -p --pid=PID,PID...
51              Show only the given PIDs
52
53       -s --sort-key COLUMN
54              Sort  by  this  column  (use --sort-key help for a column list).
55              This will force a list view unless you specify -t  at  the  same
56              time.
57
58       -u --user=USERNAME|UID
59              Show only the processes of a given user
60
61       -U --no-unicode
62              Do not use unicode but ASCII characters for graph meters
63
64       -M --no-mouse
65              Disable support of mouse control
66
67       --readonly
68              Disable all system and process changing features
69
70       -V --version
71              Output version information and exit
72
73       -t --tree
74              Show  processes  in  tree view. This can be used to force a tree
75              view when requesting a sort order with -s.
76
77       -H --highlight-changes=DELAY
78              Highlight new and old processes
79
80          --drop-capabilities[=off|basic|strict]
81              Linux only; requires libcap support.
82              Drop unneeded Linux capabilities.  In strict mode features  like
83              killing,  changing process priorities, and reading process delay
84              accounting information will not work, due to  less  capabilities
85              held.
86

INTERACTIVE COMMANDS

88       The following commands are supported while in htop:
89
90       Tab, Shift-Tab
91            Select the next / the previous screen tab to display.  You can en‐
92            able showing the screen tab names in the Setup screen (F2).
93
94       Up, Alt-k
95            Select (highlight) the  previous  process  in  the  process  list.
96            Scroll the list if necessary.
97
98       Down, Alt-j
99            Select  (highlight)  the  next process in the process list. Scroll
100            the list if necessary.
101
102       Left, Alt-h
103            Scroll the process list left.
104
105       Right, Alt-l
106            Scroll the process list right.
107
108       PgUp, PgDn
109            Scroll the process list up or down one window.
110
111       Home Scroll to the top  of  the  process  list  and  select  the  first
112            process.
113
114       End  Scroll  to  the  bottom  of  the  process list and select the last
115            process.
116
117       Ctrl-A, ^
118            Scroll left to the beginning of the process entry (i.e.  beginning
119            of line).
120
121       Ctrl-E, $
122            Scroll right to the end of the process entry (i.e. end of line).
123
124       Space
125            Tag or untag a process. Commands that can operate on multiple pro‐
126            cesses, like "kill", will then apply over the list of tagged  pro‐
127            cesses, instead of the currently highlighted one.
128
129       c    Tag  the current process and its children. Commands that can oper‐
130            ate on multiple processes, like "kill", will then apply  over  the
131            list  of  tagged  processes,  instead of the currently highlighted
132            one.
133
134       U    Untag all processes (remove all tags added with  the  Space  or  c
135            keys).
136
137       s    Trace  process  system  calls: if strace(1) is installed, pressing
138            this key will attach it to the currently  selected  process,  pre‐
139            senting a live update of system calls issued by the process.
140
141       l    Display  open files for a process: if lsof(1) is installed, press‐
142            ing this key will display the list of file descriptors  opened  by
143            the process.
144
145       w    Display  the  command  line  of the selected process in a separate
146            screen, wrapped onto multiple lines as needed.
147
148       x    Display the active file locks of the selected process in  a  sepa‐
149            rate screen.
150
151       F1, h, ?
152            Go to the help screen
153
154       F2, S
155            Go  to  the  setup screen, where you can configure the meters dis‐
156            played at the top of the  screen,  set  various  display  options,
157            choose  among  color  schemes,  and  select which columns are dis‐
158            played, in which order.
159
160       F3, /
161            Incrementally search the command lines of all the  displayed  pro‐
162            cesses.  The  currently selected (highlighted) command will update
163            as you type. While in search mode, pressing F3 will cycle  through
164            matching occurrences.  Pressing Shift-F3 will cycle backwards.
165
166            Alternatively  the search can be started by simply typing the com‐
167            mand you are looking for, although for the first character  normal
168            key bindings take precedence.
169
170       F4, \
171            Incremental  process  filtering: type in part of a process command
172            line and only processes whose names match will be shown. To cancel
173            filtering,  enter  the  Filter  option  again  and press Esc.  The
174            matching is done case-insensitive. Terms  are  fixed  strings  (no
175            regex).  You can separate multiple terms with "|".
176
177       F5, t
178            Tree  view: organize processes by parenthood, and layout the rela‐
179            tions between them as a tree. Toggling the key will switch between
180            tree and your previously selected sort view. Selecting a sort view
181            will exit tree view.
182
183       F6, <, >
184            Selects a field for sorting, also accessible through < and >.  The
185            current sort field is indicated by a highlight in the header.
186
187       F7, ]
188            Increase  the  selected  process's  priority (subtract from 'nice'
189            value).  This can only be done by the superuser.
190
191       F8, [
192            Decrease the selected process's priority (add to 'nice' value)
193
194       Shift-F7, }
195            Increase the selected process's autogroup priority (subtract  from
196            autogroup 'nice' value).  This can only be done by the superuser.
197
198       Shift-F8, {
199            Decrease  the  selected process's autogroup priority (add to auto‐
200            group 'nice' value)
201
202       F9, k
203            "Kill" process: sends a signal which is selected in a menu, to one
204            or  a group of processes. If processes were tagged, sends the sig‐
205            nal to all tagged processes.  If none is tagged, sends to the cur‐
206            rently selected process.
207
208       F10, q
209            Quit
210
211       I    Invert  the sort order: if sort order is increasing, switch to de‐
212            creasing, and vice-versa.
213
214       +, -, *
215            When in tree view mode, expand or collapse subtree. When a subtree
216            is  collapsed  a  "+"  sign shows to the left of the process name.
217            Pressing "*" will expand or collapse all children of PIDs  without
218            parents,  so  typically PID 1 (init) and PID 2 (kthreadd on Linux,
219            if kernel threads are shown).
220
221       a (on multiprocessor machines)
222            Set CPU affinity: mark which CPUs a process is allowed to use.
223
224       u    Show only processes owned by a specified user.
225
226       N    Sort by PID.
227
228       M    Sort by memory usage (top compatibility key).
229
230       P    Sort by processor usage (top compatibility key).
231
232       T    Sort by time (top compatibility key).
233
234       F    "Follow" process: if the sort order causes the currently  selected
235            process  to  move  in  the list, make the selection bar follow it.
236            This is useful for monitoring a process: this way, you can keep  a
237            process  always  visible  on  screen. When a movement key is used,
238            "follow" loses effect.
239
240       K    Hide kernel threads: prevent the threads belonging the  kernel  to
241            be displayed in the process list. (This is a toggle key.)
242
243       H    Hide user threads: on systems that represent them differently than
244            ordinary processes (such as recent NPTL-based systems),  this  can
245            hide  threads  from userspace processes in the process list. (This
246            is a toggle key.)
247
248       p    Show full paths to running programs, where applicable. (This is  a
249            toggle key.)
250
251       Z    Pause/resume process updates.
252
253       m    Merge  exe,  comm and cmdline, where applicable. (This is a toggle
254            key.)
255
256       Ctrl-L
257            Refresh: redraw screen and recalculate values.
258
259       Numbers
260            PID search: type in process ID and the selection highlight will be
261            moved to it.
262

COLUMNS

264       The  following  columns can display data about each process. A value of
265       '-' in all the rows indicates that a column is unsupported on your sys‐
266       tem,  or currently unimplemented in htop.  The names below are the ones
267       used in the "Available Columns" section of the setup screen. If a  dif‐
268       ferent name is shown in htop's main screen, it is shown below in paren‐
269       thesis.
270
271       Command
272            The full command line of the process (i.e. program name and  argu‐
273            ments).
274
275            If the option 'Merge exe, comm and cmdline in Command' (toggled by
276            the 'm' key) is active, the executable path (/proc/[pid]/exe)  and
277            the command name (/proc/[pid]/comm) are also shown merged with the
278            command line, if available.
279
280            The program basename is highlighted if set in  the  configuration.
281            Additional  highlighting  can  be configured for stale executables
282            (cf. EXE column below).
283
284       COMM The command name of the process obtained from /proc/[pid]/comm, if
285            readable.
286
287            Requires Linux kernel 2.6.33 or newer.
288
289       EXE  The  abbreviated  basename  of  the executable of the process, ob‐
290            tained from /proc/[pid]/exe, if readable. htop  is  able  to  read
291            this  file on linux for ALL the processes only if it has the capa‐
292            bility CAP_SYS_PTRACE or root privileges.
293
294            The basename is marked in red if the executable used  to  run  the
295            process  has  been  replaced  or deleted on disk since the process
296            started. The information is obtained by processing the contents of
297            /proc/[pid]/exe.
298
299            Furthermore the basename is marked in yellow if any library is re‐
300            ported as having been replaced or deleted on  disk  since  it  was
301            last  loaded.  The  information is obtained by processing the con‐
302            tents of /proc/[pid]/maps.
303
304            When deciding the color the replacement of the main executable al‐
305            ways  takes  precedence  over replacement of any other library. If
306            only the memory map indicates  a  replacement  of  the  main  exe‐
307            cutable,  this will show as if any other library had been replaced
308            or deleted.
309
310            This additional color markup can be configured in the "Display Op‐
311            tions" section of the setup screen.
312
313            Displaying  EXE  requires  CAP_SYS_PTRACE and PTRACE_MODE_READ_FS‐
314            CRED.
315
316       PID  The process ID.
317
318       STATE (S)
319            The state of the process:
320               S for sleeping (idle)
321               R for running
322               D for disk sleep (uninterruptible)
323               Z for zombie (waiting for parent to read its exit status)
324               T for traced or suspended (e.g by SIGTSTP)
325               W for paging
326
327       PPID The parent process ID.
328
329       PGRP The process's group ID.
330
331       SESSION (SID)
332            The process's session ID.
333
334       TTY  The controlling terminal of the process.
335
336       TPGID
337            The process ID of the foreground process group of the  controlling
338            terminal.
339
340       MINFLT
341            The number of page faults happening in the main memory.
342
343       CMINFLT
344            The  number  of minor faults for the process's waited-for children
345            (see MINFLT above).
346
347       MAJFLT
348            The number of page faults happening out of the main memory.
349
350       CMAJFLT
351            The number of major faults for the process's  waited-for  children
352            (see MAJFLT above).
353
354       UTIME (UTIME+)
355            The  user  CPU  time,  which is the amount of time the process has
356            spent executing on the CPU in user mode (i.e. everything but  sys‐
357            tem calls), measured in clock ticks.
358
359       STIME (STIME+)
360            The  system  CPU  time, which is the amount of time the kernel has
361            spent executing system calls on behalf of the process, measured in
362            clock ticks.
363
364       CUTIME (CUTIME+)
365            The  children's  user  CPU  time,  which is the amount of time the
366            process's waited-for children have spent executing  in  user  mode
367            (see UTIME above).
368
369       CSTIME (CSTIME+)
370            The  children's  system  CPU time, which is the amount of time the
371            kernel has spent executing system  calls  on  behalf  of  all  the
372            process's waited-for children (see STIME above).
373
374       PRIORITY (PRI)
375            The  kernel's  internal priority for the process, usually just its
376            nice value plus twenty. Different for real-time processes.
377
378       NICE (NI)
379            The nice value of a process, from 19 (low priority) to  -20  (high
380            priority).  A  high value means the process is being nice, letting
381            others have a higher relative priority. The  usual  OS  permission
382            restrictions for adjusting priority apply.
383
384       STARTTIME (START)
385            The time the process was started.
386
387       PROCESSOR (CPU)
388            The ID of the CPU the process last executed on.
389
390       M_VIRT (VIRT)
391            The size of the virtual memory of the process.
392
393       M_RESIDENT (RES)
394            The  resident  set size (text + data + stack) of the process (i.e.
395            the size of the process's used physical memory).
396
397       M_SHARE (SHR)
398            The size of the process's shared pages.
399
400       M_TRS (CODE)
401            The text resident set size of the process (i.e. the  size  of  the
402            process's executable instructions).
403
404       M_DRS (DATA)
405            The data resident set size (data + stack) of the process (i.e. the
406            size of anything except the process's executable instructions).
407
408       M_LRS (LIB)
409            The library size of the process.
410
411       M_SWAP (SWAP)
412            The size of the process's swapped pages.
413
414       M_PSS (PSS)
415            The proportional set size, same as M_RESIDENT but each page is di‐
416            vided by the number of processes sharing it.
417
418       M_M_PSSWP (PSSWP)
419            The  proportional  swap  share of this mapping, unlike M_SWAP this
420            does not take into account swapped out page  of  underlying  shmem
421            objects.
422
423       ST_UID (UID)
424            The user ID of the process owner.
425
426       PERCENT_CPU (CPU%)
427            The  percentage  of the CPU time that the process is currently us‐
428            ing.  This is the default way to represent  CPU  usage  in  Linux.
429            Each  process can consume up to 100% which means the full capacity
430            of the core it is running on. This is sometimes called "Irix mode"
431            e.g. in top(1).
432
433       PERCENT_NORM_CPU (NCPU%)
434            The percentage of the CPU time that the process is currently using
435            normalized by CPU count. This is sometimes called  "Solaris  mode"
436            e.g. in top(1).
437
438       PERCENT_MEM (MEM%)
439            The  percentage of memory the process is currently using (based on
440            the process's resident memory size, see M_RESIDENT above).
441
442       USER The username of the process owner, or the  user  ID  if  the  name
443            can't be determined.
444
445       TIME (TIME+)
446            The  time,  measured  in clock ticks that the process has spent in
447            user and system time (see UTIME, STIME above).
448
449       NLWP The number of Light-Weight Processes (=threads) in the process.
450
451       TGID The thread group ID.
452
453       CTID OpenVZ container ID, a.k.a virtual environment ID.
454
455       VPID OpenVZ process ID.
456
457       VXID VServer process ID.
458
459       RCHAR (RD_CHAR)
460            The number of bytes the process has read.
461
462       WCHAR (WR_CHAR)
463            The number of bytes the process has written.
464
465       SYSCR (RD_SYSC)
466            The number of read(2) syscalls for the process.
467
468       SYSCW (WR_SYSC)
469            The number of write(2) syscalls for the process.
470
471       RBYTES (IO_RBYTES)
472            Bytes of read(2) I/O for the process.
473
474       WBYTES (IO_WBYTES)
475            Bytes of write(2) I/O for the process.
476
477       CNCLWB (IO_CANCEL)
478            Bytes of cancelled write(2) I/O.
479
480       IO_READ_RATE (DISK READ)
481            The I/O rate of read(2) in bytes per second, for the process.
482
483       IO_WRITE_RATE (DISK WRITE)
484            The I/O rate of write(2) in bytes per second, for the process.
485
486       IO_RATE (DISK R/W)
487            The I/O rate, IO_READ_RATE + IO_WRITE_RATE (see above).
488
489       CGROUP
490            Which cgroup the process is in. For a shortened view see  the  CC‐
491            GROUP column below.
492
493       CCGROUP
494            Shortened  view  of  the cgroup name that the process is in.  This
495            performs some pattern-based replacements to shorten the  displayed
496            string and thus condense the information.
497               /*.slice is shortened to /[*] (exceptions below)
498               /system.slice is shortened to /[S]
499               /user.slice is shortened to /[U]
500               /user-*.slice  is  shortened to /[U:*] (directly preceding /[U]
501            before dropped)
502               /machine.slice is shortened to /[M]
503               /machine-*.scope is shortened to /[SNC:*] (SNC: systemd  nspawn
504            container), uppercase for the monitor
505               /lxc.monitor.* is shortened to /[LXC:*]
506               /lxc.payload.* is shortened to /[lxc:*]
507               /*.scope is shortened to /!*
508               /*.service is shortened to /* (suffix removed)
509
510            Encountered escape sequences (e.g. from systemd) inside the cgroup
511            name are not decoded.
512
513       OOM  OOM killer score.
514
515       CTXT Incremental sum of voluntary and nonvoluntary context switches.
516
517       IO_PRIORITY (IO)
518            The I/O scheduling class followed by the  priority  if  the  class
519            supports it:
520               R for Realtime
521               B for Best-effort
522               id for Idle
523
524       PERCENT_CPU_DELAY (CPUD%)
525            The  percentage  of time spent waiting for a CPU (while runnable).
526            Requires CAP_NET_ADMIN.
527
528       PERCENT_IO_DELAY (IOD%)
529            The percentage of time spent waiting for the  completion  of  syn‐
530            chronous block I/O. Requires CAP_NET_ADMIN.
531
532       PERCENT_SWAP_DELAY (SWAPD%)
533            The   percentage   of  time  spent  swapping  in  pages.  Requires
534            CAP_NET_ADMIN.
535
536       AGRP The autogroup identifier for the process. Requires Linux CFS to be
537            enabled.
538
539       ANI  The autogroup nice value for the process autogroup. Requires Linux
540            CFS to be enabled.
541
542       All other flags
543            Currently unsupported (always displays '-').
544

EXTERNAL LIBRARIES

546       While htop depends on most of the libraries it uses at build time there
547       are  two  noteworthy exceptions to this rule. These exceptions both re‐
548       late to data displayed in meters displayed in the header  of  htop  and
549       were  intentionally  created  as optional runtime dependencies instead.
550       These exceptions are described below:
551
552       libsystemd
553              The bindings for libsystemd are used in the SystemD meter to de‐
554              termine  the  number  of  active services and the overall system
555              state. Looking for the functions to determine these  information
556              at  runtime  allows  for  builds to support these meters without
557              forcing the package manager to install these libraries  on  sys‐
558              tems that otherwise don't use systemd.
559
560              Summary:  no  build time dependency, optional runtime dependency
561              on libsystemd via dynamic loading, with systemctl(1) fallback.
562
563       libsensors
564              The bindings for libsensors are used  for  the  CPU  temperature
565              readings  in  the CPU usage meters if displaying the temperature
566              is enabled through the setup screen. In order for htop  to  show
567              these  temperatures  correctly though, a proper configuration of
568              libsensors through its usual configuration files is assumed  and
569              that  all  CPU  cores correspond to temperature sensors from the
570              coretemp driver with core 0 corresponding to a  sensor  labelled
571              "Core  0".  The  package temperature may be given as "Package id
572              0". If missing it is inferred as  the  maximum  value  from  the
573              available per-core readings.
574
575              Summary:  build time dependency on libsensors(3) C header files,
576              optional runtime dependency on libsensors(3) via  dynamic  load‐
577              ing.
578

CONFIG FILES

580       By  default  htop  reads  its configuration from the XDG-compliant path
581       ~/.config/htop/htoprc.  The configuration file is overwritten by htop's
582       in-program Setup configuration, so it should not be hand-edited.  If no
583       user configuration exists htop tries to read the system-wide configura‐
584       tion  from /etc/pcp/htoprc and as a last resort, falls back to its hard
585       coded defaults.
586
587       You may override the location of the configuration file using the $HTO‐
588       PRC  environment  variable (so you can have multiple configurations for
589       different machines that share the same home directory, for example).
590
591       The pcp-htop utility makes use of htoprc in exactly the same  way.   In
592       addition,  it  supports additional configuration files allowing new me‐
593       ters and columns to be added to the display via the usual  Setup  func‐
594       tion, which will display additional Available Meters and Available Col‐
595       umn entries for each runtime configured meter or column.
596
597       These pcp-htop configuration files are read once at startup.  The  for‐
598       mat  of  these  files  is described in detail in the pcp-htop(5) manual
599       page.
600
601       This functionality makes available many thousands of Performance Co-Pi‐
602       lot  metrics for display by pcp-htop, as well as the ability to display
603       custom metrics added at individual sites.   Applications  and  services
604       instrumented  using  the  OpenMetrics format https://openmetrics.io can
605       also be displayed by pcp-htop if the  pmdaopenmetrics(1)  component  is
606       configured.
607

MEMORY SIZES

609       Memory sizes in htop are displayed in a human-readable form.  Sizes are
610       printed in powers of 1024. (e.g., 1023M = 1072693248 Bytes)
611
612       The decision to use this convention  was  made  in  order  to  conserve
613       screen space and make memory size representations consistent throughout
614       htop.
615

SEE ALSO

617       proc(5), top(1), free(1), ps(1), uptime(1) and limits.conf(5).
618

SEE ALSO FOR PCP

620       pmdaopenmetrics(1), PCPIntro(1), PMAPI(3), and pcp-htop(5).
621

AUTHORS

623       htop was originally developed by Hisham Muhammad.  Nowadays it is main‐
624       tained by the community at <htop@groups.io>.
625
626       pcp-htop  is maintained as a collaboration between the <htop@groups.io>
627       and <pcp@groups.io> communities, and forms part of the Performance  Co-
628       Pilot suite of tools.
629
631       Copyright © 2004-2019 Hisham Muhammad.
632       Copyright © 2020-2022 htop dev team.
633
634       License  GPLv2+:  GNU  General Public License version 2 or, at your op‐
635       tion, any later version.
636
637       This is free software: you are free  to  change  and  redistribute  it.
638       There is NO WARRANTY, to the extent permitted by law.
639
640
641
642Performance Co-Pilot                 2022                              HTOP(1)
Impressum