diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/free.1 | 169 | ||||
| -rw-r--r-- | man/kill.1 | 110 | ||||
| -rw-r--r-- | man/pgrep.1 | 334 | ||||
| -rw-r--r-- | man/pidof.1 | 82 | ||||
| -rw-r--r-- | man/pidwait.1 | 1 | ||||
| -rw-r--r-- | man/pkill.1 | 1 | ||||
| -rw-r--r-- | man/pmap.1 | 100 | ||||
| -rw-r--r-- | man/procps.3 | 185 | ||||
| -rw-r--r-- | man/procps_misc.3 | 156 | ||||
| -rw-r--r-- | man/procps_pids.3 | 210 | ||||
| -rw-r--r-- | man/ps.1 | 2124 | ||||
| -rw-r--r-- | man/pwdx.1 | 40 | ||||
| -rw-r--r-- | man/skill.1 | 128 | ||||
| -rw-r--r-- | man/slabtop.1 | 123 | ||||
| -rw-r--r-- | man/snice.1 | 1 | ||||
| -rw-r--r-- | man/sysctl.8 | 196 | ||||
| -rw-r--r-- | man/sysctl.conf.5 | 92 | ||||
| -rw-r--r-- | man/tload.1 | 69 | ||||
| -rw-r--r-- | man/top.1 | 2810 | ||||
| -rw-r--r-- | man/uptime.1 | 74 | ||||
| -rw-r--r-- | man/vmstat.8 | 202 | ||||
| -rw-r--r-- | man/w.1 | 115 | ||||
| -rw-r--r-- | man/watch.1 | 232 |
23 files changed, 7554 insertions, 0 deletions
diff --git a/man/free.1 b/man/free.1 new file mode 100644 index 0000000..cfe9509 --- /dev/null +++ b/man/free.1 @@ -0,0 +1,169 @@ +.\" +.\" Copyright (c) 2011-2023 Craig Small <csmall@dropbear.xyz> +.\" Copyright (c) 2013-2023 Jim Warner <james.warner@comcast.net> +.\" Copyright (c) 2011-2012 Sami Kerola <kerolasa@iki.fi> +.\" Copyright (c) 2002-2003 Albert Cahalan +.\" Copyright (c) 1993 Matt Welsh <mdw@sunsite.unc.edu> +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" +.TH FREE 1 "2023-05-02" "procps-ng" "User Commands" +.SH NAME +free \- Display amount of free and used memory in the system +.SH SYNOPSIS +.B free +.RI [ options ] +.SH DESCRIPTION +.B free +displays the total amount of free and used physical and swap memory in the +system, as well as the buffers and caches used by the kernel. The +information is gathered by parsing /proc/meminfo. The displayed +columns are: +.TP +\fBtotal\fR +Total usable memory (MemTotal and SwapTotal in /proc/meminfo). This includes +the physical and swap memory minus a few reserved bits and kernel binary code. +.TP +\fBused\fR +Used or unavailable memory (calculated as \fBtotal\fR - \fBavailable\fR) +.TP +\fBfree\fR +Unused memory (MemFree and SwapFree in /proc/meminfo) +.TP +\fBshared\fR +Memory used (mostly) by tmpfs (Shmem in /proc/meminfo) +.TP +\fBbuffers\fR +Memory used by kernel buffers (Buffers in /proc/meminfo) +.TP +\fBcache\fR +Memory used by the page cache and slabs (Cached and SReclaimable in /proc/meminfo) +.TP +\fBbuff/cache\fR +Sum of \fBbuffers\fR and \fBcache\fR +.TP +\fBavailable\fR +Estimation of how much memory is available for starting +new applications, without swapping. Unlike the data +provided by the \fBcache\fR or \fBfree\fR fields, +this field takes into account page cache and also that +not all reclaimable memory slabs will be reclaimed +due to items being in use (MemAvailable in /proc/meminfo, available on +kernels 3.14, emulated on kernels 2.6.27+, otherwise the same as \fBfree\fR) +.SH OPTIONS +.TP +\fB\-b\fR, \fB\-\-bytes\fR +Display the amount of memory in bytes. +.TP +\fB\-k\fR, \fB\-\-kibi\fR +Display the amount of memory in kibibytes. This is the default. +.TP +\fB\-m\fR, \fB\-\-mebi\fR +Display the amount of memory in mebibytes. +.TP +\fB\-g\fR, \fB\-\-gibi\fR +Display the amount of memory in gibibytes. +.TP +\fB\-\-tebi\fR +Display the amount of memory in tebibytes. +.TP +\fB\-\-pebi\fR +Display the amount of memory in pebibytes. +.TP +\fB\-\-kilo\fR +Display the amount of memory in kilobytes. Implies --si. +.TP +\fB\-\-mega\fR +Display the amount of memory in megabytes. Implies --si. +.TP +\fB\-\-giga\fR +Display the amount of memory in gigabytes. Implies --si. +.TP +\fB\-\-tera\fR +Display the amount of memory in terabytes. Implies --si. +.TP +\fB\-\-peta\fR +Display the amount of memory in petabytes. Implies --si. +.TP +\fB\-h\fR, \fB\-\-human\fP +Show all output fields automatically scaled to shortest three digit unit and +display the units of print out. Following units are used. +.sp +.nf + B = bytes + Ki = kibibyte + Mi = mebibyte + Gi = gibibyte + Ti = tebibyte + Pi = pebibyte +.fi +.sp +If unit is missing, and you have exbibyte of RAM or swap, the number is in +tebibytes and columns might not be aligned with header. +.TP +\fB\-w\fR, \fB\-\-wide\fR +Switch to the wide mode. The wide mode produces lines longer +than 80 characters. In this mode \fBbuffers\fR and \fBcache\fR +are reported in two separate columns. +.TP +\fB\-c\fR, \fB\-\-count\fR \fIcount\fR +Display the result +.I count +times. Requires the +.B \-s +option. +.TP +\fB\-l\fR, \fB\-\-lohi\fR +Show detailed low and high memory statistics. +.TP +\fB\-L\fR, \fB\-\-line\fR +Show output on a single line, often used with the +.B \-s +option to show memory statistics repeatedly. +.TP +\fB\-s\fR, \fB\-\-seconds\fR \fIdelay\fR +Continuously display the result \fIdelay\fR seconds +apart. You may actually specify any floating point number for +\fIdelay\fR using either . or , for decimal point. +.BR usleep (3) +is used for microsecond resolution delay times. +.TP +\fB\-\-si\fR +Use kilo, mega, giga etc (power of 1000) instead of kibi, mebi, gibi (power +of 1024). +.TP +\fB\-t\fR, \fB\-\-total\fR +Display a line showing the column totals. +.TP +\fB\-v\fR, \fB\-\-committed\fR +Display a line showing the memory commit limit and amount of committed/uncommitted +memory. The \fBtotal\fR column on this line will display the memory commit +limit. This line is relevant if memory overcommit is disabled. +.TP +\fB\-\-help\fR +Print help. +.TP +\fB\-V\fR, \fB\-\-version\fR +Display version information. +.PD +.SH FILES +.TP +/proc/meminfo +memory information +.PD +.SH BUGS +The value for the \fBshared\fR column is not available from kernels before +2.6.32 and is displayed as zero. +.TP +Please send bug reports to +.UR procps@freelists.org +.UE +.SH "SEE ALSO" +.BR ps (1), +.BR slabtop (1), +.BR top "(1), +.BR vmstat (8). diff --git a/man/kill.1 b/man/kill.1 new file mode 100644 index 0000000..b74717c --- /dev/null +++ b/man/kill.1 @@ -0,0 +1,110 @@ +.\" +.\" Copyright (c) 2002-2023 Craig Small <csmall@dropbear.xyz> +.\" Copyright (c) 2011-2023 Jim Warner <james.warner@comcast.net> +.\" Copyright (c) 2011-2012 Sami Kerola <kerolasa@iki.fi> +.\" Copyright (c) 1998-2003 Albert Cahalan +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.TH KILL 1 "2023-01-16" "procps-ng" "User Commands" +.SH NAME +kill \- send a signal to a process +.SH SYNOPSIS +.B kill +[options] <pid> [...] +.SH DESCRIPTION +The default signal for kill is TERM. Use +.B \-l +or +.B \-L +to list available signals. Particularly useful signals include HUP, +INT, KILL, STOP, CONT, and 0. Alternate signals may be specified in +three ways: +.BR \-9 ", " \-SIGKILL +or +.BR \-KILL . +Negative PID values may be used to choose whole process groups; see +the PGID column in ps command output. A PID of +.B \-1 +is special; it indicates all processes except the kill process itself +and init. +.SH OPTIONS +.TP +.B <pid> [...] +Send signal to every <pid> listed. +.TP +.B \-<signal> +.TQ +.B \-s <signal> +.TQ +.B \-\-signal <signal> +Specify the +.B signal +to be sent. The signal can be specified by using name or number. +The behavior of signals is explained in +.BR signal (7) +manual page. +.TP +\fB\-q\fR, \fB\-\-queue \fIvalue\fP +Use +.BR sigqueue (3) +rather than +.BR kill (2) +and the value argument is used to specify +an integer to be sent with the signal. If the receiving process has +installed a handler for this signal using the SA_SIGINFO flag to +.BR sigaction (2), +then it can obtain this data via the si_value field of the +siginfo_t structure. +.TP +\fB\-l\fR, \fB\-\-list\fR [\fIsignal\fR] +List signal names. This option has optional argument, which +will convert signal number to signal name, or other way round. +.TP +.BR \-L , \ \-\-table +List signal names in a nice table. +.TP +.PD +.SH NOTES +Your shell (command line interpreter) may have a built-in kill +command. You may need to run the command described here as /bin/kill +to solve the conflict. +.SH EXAMPLES +.TP +.B kill \-9 \-1 +Kill all processes you can kill. +.TP +.B kill \-l 11 +Translate number 11 into a signal name. +.TP +.B kill -L +List the available signal choices in a nice table. +.TP +.B kill 123 543 2341 3453 +Send the default signal, SIGTERM, to all those processes. +.SH "SEE ALSO" +.BR kill (2), +.BR killall (1), +.BR nice (1), +.BR pkill (1), +.BR renice (1), +.BR signal (7), +.BR sigqueue (3), +.BR skill (1) +.SH STANDARDS +This command meets appropriate standards. The +.B \-L +flag is Linux-specific. +.SH AUTHOR +.UR albert@users.sf.net +Albert Cahalan +.UE +wrote kill in 1999 to replace a bsdutils one that was not standards +compliant. The util-linux one might also work correctly. +.SH "REPORTING BUGS" +Please send bug reports to +.UR procps@freelists.org +.UE diff --git a/man/pgrep.1 b/man/pgrep.1 new file mode 100644 index 0000000..41d9ac0 --- /dev/null +++ b/man/pgrep.1 @@ -0,0 +1,334 @@ +.\" +.\" Copyright (c) 2004-2023 Craig Small <csmall@dropbear.xyz> +.\" Copyright (c) 2013-2023 Jim Warner <james.warner@comcast.net> +.\" Copyright (c) 2011-2012 Sami Kerola <kerolasa@iki.fi> +.\" Copyright (c) 2002-2004 Albert Cahalan +.\" Copyright (c) 2000 Kjetil Torgrim Homme +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.TH PGREP "1" "2023-01-16" "procps-ng" "User Commands" +.SH NAME +pgrep, pkill, pidwait \- look up, signal, or wait for processes based on name and other attributes +.SH SYNOPSIS +.B pgrep +[options] pattern +.br +.B pkill +[options] pattern +.br +.B pidwait +[options] pattern +.SH DESCRIPTION +.B pgrep +looks through the currently running processes and lists the process IDs which +match the selection criteria to stdout. All the criteria have to match. +For example, +.IP +$ pgrep \-u root sshd +.PP +will only list the processes called +.B sshd +AND owned by +.BR root . +On the other hand, +.IP +$ pgrep \-u root,daemon +.PP +will list the processes owned by +.B root +OR +.BR daemon . +.PP +.B pkill +will send the specified signal (by default +.BR SIGTERM ) +to each process instead of listing them on stdout. +.PP +.B pidwait +will wait for each process instead of listing them on stdout. +.SH OPTIONS +.TP +\fB\-\fR\fIsignal\fP +.TQ +\fB\-\-signal\fR \fIsignal\fR +Defines the signal to send to each matched process. Either the numeric or +the symbolic signal name can be used. In +.B pgrep +or +.B pidwait +mode only the long option can be used and has no effect unless used in conjunction with +\fB\-\-require\-handler\fR to filter to processes with a userspace signal +handler present for a particular signal. + +.TP +\fB\-c\fR, \fB\-\-count\fR +Suppress normal output; instead print a count of matching processes. When +count does not match anything, e.g. returns zero, the command will return +non-zero value. Note that for pkill and pidwait, the count is the number of +matching processes, not the processes that were successfully signaled or waited +for. +.TP +\fB\-d\fR, \fB\-\-delimiter\fR \fIdelimiter\fP +Sets the string used to delimit each process ID in the output (by default a +newline). +.RB ( pgrep +only.) +.TP +\fB\-e\fR, \fB\-\-echo\fR +Display name and PID of the process being killed. +.RB ( pkill +only.) +.TP +\fB\-f\fR, \fB\-\-full\fR +The +.I pattern +is normally only matched against the process name. When +.B \-f +is set, the full command line is used. +.TP +\fB\-g\fR, \fB\-\-pgroup\fR \fIpgrp\fP,... +Only match processes in the process group IDs listed. Process group 0 is +translated into +.BR pgrep 's, +.BR pkill 's, +or +.BR pidwait 's +own process group. +.TP +\fB\-G\fR, \fB\-\-group\fR \fIgid\fP,... +Only match processes whose real group ID is listed. Either the numerical or +symbolical value may be used. +.TP +\fB\-i\fR, \fB\-\-ignore\-case\fR +Match processes case-insensitively. +.TP +\fB\-l\fR, \fB\-\-list\-name\fR +List the process name as well as the process ID. +.RB ( pgrep +only.) +.TP +\fB\-a\fR, \fB\-\-list\-full\fR +List the full command line as well as the process ID. +.RB ( pgrep +only.) +.TP +\fB\-n\fR, \fB\-\-newest\fR +Select only the newest (most recently started) of the matching processes. +.TP +\fB\-o\fR, \fB\-\-oldest\fR +Select only the oldest (least recently started) of the matching processes. +.TP +\fB\-O\fR, \fB\-\-older\fR \fIsecs\fP +Select processes older than secs. +.TP +\fB\-P\fR, \fB\-\-parent\fR \fIppid\fP,... +Only match processes whose parent process ID is listed. +.TP +\fB\-s\fR, \fB\-\-session\fR \fIsid\fP,... +Only match processes whose process session ID is listed. Session ID 0 +is translated into +.BR pgrep 's, +.BR pkill 's, +or +.BR pidwait 's +own session ID. +.TP +\fB\-t\fR, \fB\-\-terminal\fR \fIterm\fP,... +Only match processes whose controlling terminal is listed. The terminal name +should be specified without the "/dev/" prefix. +.TP +\fB\-u\fR, \fB\-\-euid\fR \fIeuid\fP,... +Only match processes whose effective user ID is listed. Either the numerical +or symbolical value may be used. +.TP +\fB\-U\fR, \fB\-\-uid\fR \fIuid\fP,... +Only match processes whose real user ID is listed. Either the numerical or +symbolical value may be used. +.TP +\fB\-v\fR, \fB\-\-inverse\fR\fR +Negates the matching. This option is usually used in +.BR pgrep 's +or +.BR pidwait 's +context. In +.BR pkill 's +context the short option is disabled to avoid accidental usage of the option. +.TP +\fB\-w\fR, \fB\-\-lightweight\fR\fR +Shows all thread ids instead of pids in +.BR pgrep 's +or +.BR pidwait 's +context. In +.BR pkill 's +context this option is disabled. +.TP +\fB\-x\fR, \fB\-\-exact\fR\fR +Only match processes whose names (or command lines if \fB\-f\fR is specified) +.B exactly +match the +.IR pattern . +.TP +\fB\-F\fR, \fB\-\-pidfile\fR \fIfile\fR +Read \fIPID\fRs from \fIfile\fR. This option is more useful for +.B pkill +or +.B pidwait +than +.BR pgrep . +.TP +\fB\-L\fR, \fB\-\-logpidfile\fR +Fail if pidfile (see \fB\-F\fR) not locked. +.TP +\fB\-r\fR, \fB\-\-runstates\fR \fID,R,S,Z,\fP... +Match only processes which match the process state. +.TP +\fB\-A\fR, \fB\-\-ignore-ancestors\fR\fR +Ignore all ancestors of +.BR pgrep , +.BR pkill , +or +.BR pidwait . +For example, this can be useful when elevating with +.BR sudo +or similar tools. +.TP +\fB\-H\fR, \fB\-\-require\-handler\fR\fR +Only match processes with a userspace signal handler present for the signal to +be sent. +.TP +\fB\-\-cgroup \fIname\fP,... +Match on provided control group (cgroup) v2 name. See +.BR cgroups (8) +.TP +\fB\-\-ns \fIpid\fP +Match processes that belong to the same namespaces. Required to run as +root to match processes from other users. See \fB\-\-nslist\fR for how to +limit which namespaces to match. +.TP +\fB\-\-nslist \fIname\fP,... +Match only the provided namespaces. Available namespaces: +ipc, mnt, net, pid, user, uts. +.TP +\fB\-q\fR, \fB\-\-queue \fIvalue\fP +Use +.BR sigqueue (3) +rather than +.BR kill (2) +and the value argument is used to specify +an integer to be sent with the signal. If the receiving process has +installed a handler for this signal using the SA_SIGINFO flag to +.BR sigaction (2), +then it can obtain this data via the si_value field of the +siginfo_t structure. +.TP +\fB\-V\fR, \fB\-\-version\fR +Display version information and exit. +.TP +\fB\-h\fR, \fB\-\-help\fR +Display help and exit. +.PD +.SH OPERANDS +.TP +.I pattern +Specifies an Extended Regular Expression for matching against the process +names or command lines. +.SH EXAMPLES +Example 1: Find the process ID of the +.B named +daemon: +.IP +$ pgrep \-u root named +.PP +Example 2: Make +.B syslog +reread its configuration file: +.IP +$ pkill \-HUP syslogd +.PP +Example 3: Give detailed information on all +.B xterm +processes: +.IP +$ ps \-fp $(pgrep \-d, \-x xterm) +.PP +Example 4: Make all +.B chrome +processes run nicer: +.IP +$ renice +4 $(pgrep chrome) +.SH "EXIT STATUS" +.PD 0 +.TP +0 +One or more processes matched the criteria. For +.B pkill +and +.BR pidwait , +one or more +processes must also have been successfully signalled or waited for. +.TP +1 +No processes matched or none of them could be signalled. +.TP +2 +Syntax error in the command line. +.TP +3 +Fatal error: out of memory etc. +.PD +.SH NOTES +The process name used for matching is limited to the 15 characters present in +the output of /proc/\fIpid\fP/stat. Use the \fB\-f\fR option to match against the +complete command line, /proc/\fIpid\fP/cmdline. Threads may not have the +same process name as the parent process but will have the same command line. +.PP +The running +.BR pgrep , +.BR pkill , +or +.B pidwait +process will never report itself as a +match. +.PP +The +.B \-O \-\-older +option will silently fail if \fI/proc\fR is mounted with the \fIsubset=pid\fR option. +.SH BUGS +The options +.B \-n +and +.B \-o +and +.B \-v +can not be combined. Let +me know if you need to do this. +.PP +Defunct processes are reported. +.PP +.B pidwait +requires the +.BR pidfd_open (2) +system call which first appeared in Linux 5.3. +.SH "SEE ALSO" +.BR ps (1), +.BR regex (7), +.BR signal (7), +.BR sigqueue (3), +.BR killall (1), +.BR skill (1), +.BR kill (1), +.BR kill (2), +.BR cgroups (8). +.SH AUTHOR +.UR kjetilho@ifi.uio.no +Kjetil Torgrim Homme +.UE +.SH "REPORTING BUGS" +Please send bug reports to +.UR procps@freelists.org +.UE diff --git a/man/pidof.1 b/man/pidof.1 new file mode 100644 index 0000000..479b4b5 --- /dev/null +++ b/man/pidof.1 @@ -0,0 +1,82 @@ +.\" +.\" Copyright (c) 2018-2023 Jim Warner <james.warner@comcast.net> +.\" Copyright (c) 2019-2023 Craig Small <csmall@dropbear.xyz> +.\" Copyright (c) 2013 Jaromir Capik <jcapik@redhat.com> +.\" Copyright (c) 1998 Miquel van Smoorenburg +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" +.TH PIDOF 1 "2023-01-16" "" "User Commands" +.SH NAME +pidof \- find the process ID of a running program +.SH SYNOPSIS +.B pidof +.RB [ \-s ] +.RB [ \-c ] +.RB [ \-q ] +.RB [ \-w ] +.RB [ \-x ] +.RB [ \-o +.IR omitpid[,omitpid...]... ] +.RB [ \-t ] +.RB [ \-S +.IR separator ] +.I program +.IB [ program... ] +.SH DESCRIPTION +.B Pidof +finds the process id's (pids) of the named programs. It prints those +id's on the standard output. +.SH OPTIONS +.IP \fB\-s\fP +Single shot - this instructs the program to only return one \fIpid\fP. +.IP \fB\-c\fP +Only return process ids that are running with the same root directory. +This option is ignored for non-root users, as they will be unable to check +the current root directory of processes they do not own. +.IP \fB\-q\fP +Quiet mode, suppress any output and only sets the exit status accordingly. +.IP \fB\-w\fP +Show also processes that do not have visible command line (e.g. kernel +worker threads). +.IP \fB\-x\fP +Scripts too - this causes the program to also return process id's of +shells running the named scripts. +.IP "\fB-o\fP \fIomitpid\fP" +Tells \fBpidof\fP to omit processes with that process id. The special +pid \fB%PPID\fP can be used to name the parent process of the \fBpidof\fP +program, in other words the calling shell or shell script. +.IP \fB\-t\fP +Shows all thread ids instead of pids. +.IP "\fB-S\fP \fIseparator\fP" +Use \fIseparator\fP as a separator put between pids. Used only when +more than one pids are printed for the program. +The \fB\-d\fR option is an alias for this option for sysvinit +.B pidof +compatibility. +.SH "EXIT STATUS" +.TP +.B 0 +At least one program was found with the requested name. +.TP +.B 1 +No program was found with the requested name. + +.SH BUGS +When using the \fB\-x\fP option, +.B pidof +only has a simple method for detecting scripts and will miss scripts that, +for example, use env. This limitation is due to how the scripts look in +the proc filesystem. + +.SH SEE ALSO +.BR pgrep (1), +.BR pkill (1) +.SH AUTHOR +.UR jcapik@redhat.com +Jaromir Capik +.UE diff --git a/man/pidwait.1 b/man/pidwait.1 new file mode 100644 index 0000000..0e94b52 --- /dev/null +++ b/man/pidwait.1 @@ -0,0 +1 @@ +.so man1/pgrep.1 diff --git a/man/pkill.1 b/man/pkill.1 new file mode 100644 index 0000000..0e94b52 --- /dev/null +++ b/man/pkill.1 @@ -0,0 +1 @@ +.so man1/pgrep.1 diff --git a/man/pmap.1 b/man/pmap.1 new file mode 100644 index 0000000..6954158 --- /dev/null +++ b/man/pmap.1 @@ -0,0 +1,100 @@ +.\" +.\" Copyright (c) 2011-2023 Craig Small <csmall@dropbear.xyz> +.\" Copyright (c) 2011-2012 Sami Kerola <kerolasa@iki.fi> +.\" Copyright (c) 2013 Jaromir Capik <jcapik@redhat.com> +.\" Copyright (c) 1998-2002 Albert Cahalan +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" +.\" (The preceding line is a note to broken versions of man to tell +.\" them to pre-process this man page with tbl) +.\" Man page for pmap. +.\" Licensed under version 2 of the GNU General Public License. +.\" Written by Albert Cahalan. +.\" +.TH PMAP "1" "2020-06-04" "procps-ng" "User Commands" +.SH NAME +pmap \- report memory map of a process +.SH SYNOPSIS +.B pmap +[\fIoptions\fR] \fIpid\fR [...] +.SH DESCRIPTION +The +.B pmap +command reports the memory map of a process or processes. +.SH OPTIONS +.TP +\fB\-x\fR, \fB\-\-extended\fR +Show the extended format. +.TP +\fB\-d\fR, \fB\-\-device\fR +Show the device format. +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Do not display some header or footer lines. +.TP +\fB\-A\fR, \fB\-\-range\fR \fIlow\fR,\fIhigh\fR +Limit results to the given range to +.I low +and +.I high +address range. Notice that the low and high arguments are single string +separated with comma. +.TP +\fB\-X\fR +Show even more details than the \fB\-x\fR option. WARNING: format changes +according to \fI/proc/PID/smaps\fR +.TP +\fB\-XX\fR +Show everything the kernel provides +.TP +\fB\-p\fR, \fB\-\-show\-path\fR +Show full path to files in the mapping column +.TP +\fB\-c\fR, \fB\-\-read\-rc\fR +Read the default configuration +.TP +\fB\-C\fR, \fB\-\-read\-rc\-from\fR \fIfile\fR +Read the configuration from \fIfile\fR +.TP +\fB\-n\fR, \fB\-\-create\-rc\fR +Create new default configuration +.TP +\fB\-N\fR, \fB\-\-create\-rc\-to\fR \fIfile\fR +Create new configuration to \fIfile\fR +.TP +\fB\-h\fR, \fB\-\-help\fR +Display help text and exit. +.TP +\fB\-V\fR, \fB\-\-version\fR +Display version information and exit. +.SH "EXIT STATUS" +.PP +.RS +.PD 0 +.TP +.B 0 +Success. +.TP +.B 1 +Failure. +.TP +.B 42 +Did not find all processes asked for. +.PD +.RE +.SH "SEE ALSO" +.BR ps (1), +.BR pgrep (1) +.SH STANDARDS +No standards apply, but +.B pmap +looks an awful lot like a SunOS command. +.SH "REPORTING BUGS" +Please send bug reports to +.UR procps@freelists.org +.UE diff --git a/man/procps.3 b/man/procps.3 new file mode 100644 index 0000000..4e07a92 --- /dev/null +++ b/man/procps.3 @@ -0,0 +1,185 @@ +.\" +.\" Copyright (c) 2020-2023 Jim Warner <james.warner@comcast.net> +.\" Copyright (c) 2020-2023 Craig Small <csmall@dropbear.xyz> +.\" +.\" This manual is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU Lesser General Public +.\" License as published by the Free Software Foundation; either +.\" version 2.1 of the License, or (at your option) any later version. +.\" +.\" +.TH PROCPS 3 "August 2022" "libproc2" +.\" Please adjust this date whenever revising the manpage. +.\" +.nh +.SH NAME +procps \- API to access system level information in the /proc filesystem + +.SH SYNOPSIS +Five distinct interfaces are represented in this synopsis and named after +the files they access in the /proc pseudo filesystem: +.BR diskstats ", " meminfo ", " slabinfo ", " stat " and " vmstat . + +.nf +.RS +4 +#include <libproc2/\fBnamed_interface\fR.h> + +.RI "int\fB procps_new \fR (struct info **" info ); +.RI "int\fB procps_ref \fR (struct info *" info ); +.RI "int\fB procps_unref\fR (struct info **" info ); + +.RB "struct result *" procps_get " (" +.RI " struct info *" info , +.RI "[ const char *" name ", ] \fBdiskstats\fR api only" +.RI " enum item " item ); + +.RB "struct stack *" procps_select " (" +.RI " struct info *" info , +.RI "[ const char *" name ", ] \fBdiskstats\fR api only" +.RI " enum item *" items , +.RI " int " numitems ); + +.RB "struct reaped *" procps_reap " (" +.RI " struct info *" info , +.RI "[ enum reap_type " what ", ] \fBstat\fR api only" +.RI " enum item *" items , +.RI " int " numitems ); + +.RB "struct stack **" procps_sort " (" +.RI " struct info *" info , +.RI " struct stack *" stacks [], +.RI " int " numstacked , +.RI " enum item " sortitem , +.RI " enum sort_order " order ); + +.fi + +The above functions and structures are generic but the specific +\fBnamed_interface\fR would also be part of any identifiers. +For example, `procps_new' would actually be `procps_\fBmeminfo\fR_new' +and `info' would really be `\fBdiskstats\fR_info', etc. + +The same \fBnamed_interface\fR is used in each header file name with +an appended `.h' suffix. + +Link with \fI\-lproc2\fP. + +.SH DESCRIPTION +.SS Overview +Central to these interfaces is a simple `result' +structure reflecting an `item' plus its value (in a union +with standard C language types as members). +All `result' structures are automatically allocated and +provided by the library. + +By specifying an array of `items', these structures can be +organized as a `stack', potentially yielding many results +with a single function call. +Thus, a `stack' can be viewed as a variable length record +whose content and order is determined solely by the user. + +As part of each interface there are two unique enumerators. +The `noop' and `extra' items exist to hold user values. +They are never set by the library, but the `extra' +result will be zeroed with each library interaction. + +The \fBnamed_interface\fR header file will be an essential +document during user program development. +There you will find available items, their return type +(the `result' struct member name) and the source for such values. +Additional enumerators and structures are also documented there. + +.SS Usage +The following would be a typical sequence of calls to +these interfaces. + +.nf +.RB "1. " procps_new() +.RB "2. " procps_get() ", " procps_select() " or " procps_reap() +.RB "3. " procps_unref() +.fi + +The \fBget\fR function is used to retrieve a `result' structure for +a single `item'. +Alternatively, a \fBGET\fR macro is available when only the return +value is of interest. + +The \fBselect\fR function can retrieve multiple `result' structures +in a single `stack'. + +For unpredictable variable outcomes, the \fBdiskstats\fR, \fBslabinfo\fR +and \fBstat\fR interfaces export a \fBreap\fR function. +It is used to retrieve multiple `stacks' each containing multiple +`result' structures. +Optionally, a user may choose to \fBsort\fR those results. + +To exploit any `stack', and access individual `result' structures, +a \fIrelative_enum\fR is required as shown in the \fBVAL\fR macro +defined in the header file. +Such values could be hard coded as: 0 through numitems-1. +However, this need is typically satisfied by creating your own +enumerators corresponding to the order of the `items' array. + +.SS Caveats +The \fBnew\fR, \fBref\fR, \fBunref\fR, \fBget\fR and \fBselect\fR +functions are available in all five interfaces. + +For the \fBnew\fR and \fBunref\fR functions, the address of an \fIinfo\fR +struct pointer must be supplied. +With \fBnew\fR it must have been initialized to NULL. +With \fBunref\fR it will be reset to NULL if the reference count reaches zero. + +In the case of the \fBdiskstats\fR interface, a \fIname\fR parameter +on the \fBget\fR and \fBselect\fR functions identifies a disk or +partition name + +For the \fBstat\fR interface, a \fIwhat\fR parameter on the \fBreap\fR +function identifies whether data for just CPUs or both CPUs and NUMA +nodes is to be gathered. + +When using the \fBsort\fR function, the parameters \fIstacks\fR and +\fInumstacked\fR would normally be those returned in the `reaped' +structure. + +.SH RETURN VALUE +.SS Functions Returning an `int' +An error will be indicated by a negative number that +is always the inverse of some well known errno.h value. + +Success is indicated by a zero return value. +However, the \fBref\fR and \fBunref\fR functions return +the current \fIinfo\fR structure reference count. + +.SS Functions Returning an `address' +An error will be indicated by a NULL return pointer +with the reason found in the formal errno value. + +Success is indicated by a pointer to the named structure. + +.SH DEBUGGING +To aid in program development, there is a provision that can +help ensure `result' member references agree with library +expectations. +It assumes that a supplied macro in the header file is +used to access the `result' value. + +This feature can be activated through either of the following +methods and any discrepancies will be written to \fBstderr\fR. + +.IP 1) 3 +Add CFLAGS='-DXTRA_PROCPS_DEBUG' to any other ./configure +options employed. + +.IP 2) 3 +Add #include <procps/xtra-procps-debug.h> to any program +\fIafter\fR the named interface includes. + +.PP +This verification feature incurs substantial overhead. +Therefore, it is important that it \fInot\fR be activated +for a production/release build. + +.SH SEE ALSO +.BR procps_misc (3), +.BR procps_pids (3), +.BR proc (5). diff --git a/man/procps_misc.3 b/man/procps_misc.3 new file mode 100644 index 0000000..bc42aac --- /dev/null +++ b/man/procps_misc.3 @@ -0,0 +1,156 @@ +.\" +.\" Copyright (c) 2020-2023 Jim Warner <james.warner@comcast.net> +.\" Copyright (c) 2020-2023 Craig Small <csmall@dropbear.xyz> +.\" +.\" This manual is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU Lesser General Public +.\" License as published by the Free Software Foundation; either +.\" version 2.1 of the License, or (at your option) any later version. +.\" +.\" +.TH PROCPS_MISC 3 "August 2022" "libproc2" +.\" Please adjust this date whenever revising the manpage. +.\" +.nh +.SH NAME +procps_misc \- API for miscellaneous information in the /proc filesystem +.SH SYNOPSIS +.nf +.B #include <libproc2/misc.h> +.PP +Platform Particulars +.RS 4 +.PP +.RB "long " procps_cpu_count " (void); +.RB "long " procps_hertz_get " (void); +.RB "unsigned int " procps_pid_length " (void); +.RB "int " procps_linux_version " (void); +.RE +.PP +Runtime Particulars +.PP +.RS 4 +.RI "int \fB procps_loadavg\fR (double *" av1 ", double *" av5 ", double *" av15 ");" +.RI "int \fB procps_uptime\fR (double *" uptime_secs ", double *" idle_secs ");" +.RB "char *" procps_uptime_sprint " (void);" +.RB "char *" procps_uptime_sprint_short " (void);" +.RE +.PP +Namespace Particulars +.PP +.RS 4 +.RI "int \fB procps_ns_get_id\fR (const char *" name ");" +.RI "const char\fB *procps_ns_get_name\fR (int " id ");" +.RI "int \fB procps_ns_read_pid\fR (int " pid ", struct procps_ns *" nsp ");" +.RE + +Link with \fI\-lproc2\fP. + +.SH DESCRIPTION +.BR procps_cpu_count () +returns the number of CPUs that are currently online as +.BI sysconf( _SC_NPROCESSORS_ONLY ) +or an assumed \fI1\fR. + +.BR procps_hertz_get () +returns the number of clock ticks per second as +.BI sysconf( _SC_CLK_TCK ) +or an assumed \fI100\fR. +Dividing tics by this value yields seconds. + +.BR procps_pid_length () +returns the maximum string length for a PID on the system. For example, if the largest +possible PID value on was 123, then the length would be 3. If the file +\fI/proc/sys/kernel/pid_max\fR is unreadable, the value is assumed to be \fI5\fR. + +.BR procps_linux_version () +returns the current Linux version as an encoded integer. On non-Linux systems that +have an emulated proc filesystem this function returns the version of the +Linux emulation instead. +The version consists of three positive integers representing the major, +minor and patch levels. +The following macros are provided for encoding a given Linux version or +separating out the components of the current version. +.RS 4 +.PP +LINUX_VERSION(\ major\ ,\ minor\ ,\ patch\ ) +.PP +LINUX_VERSION_MAJOR(\ ver\ ) +.PP +LINUX_VERSION_MINOR(\ ver\ ) +.PP +LINUX_VERSION_PATCH(\ ver\ ) +.RE + +.BR procps_loadavg () +fetches the system load average and puts the 1, 5 and 15 minute averages into +location(s) specified by any pointer which is not \fINULL\fR. + +.BR procps_uptime () +returns uptime and/or idle seconds into location(s) specified by any pointer +which is not \fINULL\fR. +The \fBsprint\fR varieties return a human-readable string in one of two forms. +.RS 4 +.PP +HH:MM:SS up HH:MM, # users, load average: 1, 5, 15 MM averages +.PP +up HH, MM +.RE + +.BR procps_ns_get_id () +returns the integer id (enum namespace_type) of the namespace for the given namespace \fIname\fR. + +.BR procps_ns_get_name () +returns the name of the namespace for the given \fIid\fR (enum namespace_type). + +.BR procps_ns_read_pid () +returns the inodes for the namespaces of the given process in the +procps_ns structure pointed to by \fInsp\fR. +Those inodes will appear in the order proscribed by enum namespace_type. +.PP +.RS 4 +.nf +enum namespace_type { + PROCPS_NS_CGROUP, + PROCPS_NS_IPC, + PROCPS_NS_MNT, + PROCPS_NS_NET, + PROCPS_NS_PID, + PROCPS_NS_TIME, + PROCPS_NS_USER, + PROCPS_NS_UTS +}; +.fi +.RE + + +.SH RETURN VALUE +.SS Functions Returning an `int' or `long' +An error will be indicated by a negative number that +is always the inverse of some well known errno.h value. + +.SS Functions Returning an `address' +An error will be indicated by a NULL return pointer +with the reason found in the formal errno value. + +.SH FILES +.TP +.I /proc/loadavg +The raw values for load average. +.TP +.I /proc/sys/kernel/osrelease +Contains the release version of the Linux kernel or proc filesystem. +.TP +.I /proc/sys/kernel/pid_max +Contains the value at which PIDs wrap around, one greater than the maximum PID value. +.TP +.I /proc/uptime +The raw values for uptime and idle time. +.TP +.IB /proc/<PID>/ns +contains the set of namespaces for a particular \fBPID\fR. + +.SH SEE ALSO +.BR procps (3), +.BR procps_pids (3), +.BR proc (5). diff --git a/man/procps_pids.3 b/man/procps_pids.3 new file mode 100644 index 0000000..9ead691 --- /dev/null +++ b/man/procps_pids.3 @@ -0,0 +1,210 @@ +.\" +.\" Copyright (c) 2020-2023 Jim Warner <james.warner@comcast.net> +.\" Copyright (c) 2020-2023 Craig Small <csmall@dropbear.xyz> +.\" +.\" This manual is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU Lesser General Public +.\" License as published by the Free Software Foundation; either +.\" version 2.1 of the License, or (at your option) any later version. +.\" +.\" +.TH PROCPS_PIDS 3 "August 2022" "libproc2" +.\" Please adjust this date whenever revising the manpage. +.\" +.nh +.SH NAME +procps_pids \- API to access process information in the /proc filesystem + +.SH SYNOPSIS +.nf +#include <libproc2/pids.h> + +.RI "int\fB procps_pids_new \fR (struct pids_info **" info ", enum pids_item *" items ", int " numitems ); +.RI "int\fB procps_pids_ref \fR (struct pids_info *" info ); +.RI "int\fB procps_pids_unref\fR (struct pids_info **" info ); + + +.RB "struct pids_stack *" procps_pids_get " (" +.RI " struct pids_info *" info , +.RI " enum pids_fetch_type " which ); + +.RB "struct pids_fetch *" procps_pids_reap " (" +.RI " struct pids_info *" info , +.RI " enum pids_fetch_type " which ); + +.RB "struct pids_fetch *" procps_pids_select " (" +.RI " struct pids_info *" info , +.RI " unsigned *" these , +.RI " int " numthese , +.RI " enum pids_select_type " which ); + +.RB "struct pids_stack **" procps_pids_sort " (" +.RI " struct pids_info *" info , +.RI " struct pids_stack *" stacks [], +.RI " int " numstacked , +.RI " enum pids_item " sortitem , +.RI " enum pids_sort_order " order ); + +.RB "int " procps_pids_reset " (" +.RI " struct pids_info *" info , +.RI " enum pids_item *" newitems , +.RI " int " newnumitems ); + +.RB "struct pids_stack *" fatal_proc_unmounted " (" +.RI " struct pids_info *" info , +.RI " int " return_self ); + +.fi + +Link with \fI\-lproc2\fP. + +.SH DESCRIPTION +.SS Overview +Central to this interface is a simple `result' +structure reflecting an `item' plus its value (in a union +with standard C language types as members). +All `result' structures are automatically allocated and +provided by the library. + +By specifying an array of `items', these structures can be +organized as a `stack', potentially yielding many results +with a single function call. +Thus, a `stack' can be viewed as a variable length record +whose content and order is determined solely by the user. + +As part of this interface there are two unique enumerators. +The `noop' and `extra' items exist to hold user values. +They are never set by the library, but the `extra' +result will be zeroed with each library interaction. + +The pids.h file will be an essential document during +user program development. +There you will find available items, their return type +(the `result' struct member name) and the source for such values. +Additional enumerators and structures are also documented there. + +.SS Usage +The following would be a typical sequence of calls to +this interface. + +.nf +.RB "1. " fatal_proc_unmounted() +.RB "2. " procps_pids_new() +.RB "3. " procps_pids_get() ", " procps_pids_reap() " or " procps_pids_select() +.RB "4. " procps_pids_unref() +.fi + +The \fBget\fR function is an iterator for successive PIDs/TIDs, +returning those `items' previously identified via \fBnew\fR +or \fBreset\fR. + +Two functions support unpredictable variable outcomes. +The \fBreap\fR function gathers data for all processes while +the \fBselect\fR function deals with specific PIDs or UIDs. +Both can return multiple `stacks' each containing multiple `result' +structures. +Optionally, a user may choose to \fBsort\fR such results + +To exploit any `stack', and access individual `result' structures, +a \fIrelative_enum\fR is required as shown in the \fBVAL\fR macro +defined in the header file. +Such values could be hard coded as: 0 through numitems-1. +However, this need is typically satisfied by creating your own +enumerators corresponding to the order of the `items' array. + +.SS Caveats +The <pids> API differs from others in that those items +of interest must be provided at \fBnew\fR or \fBreset\fR time, +the latter being unique to this API. +If either the \fIitems\fR or \fInumitems\fR parameter is zero at +\fBnew\fR time, then \fBreset\fR becomes mandatory before +issuing any other call. + +For the \fBnew\fR and \fBunref\fR functions, the address of an \fIinfo\fR +struct pointer must be supplied. +With \fBnew\fR it must have been initialized to NULL. +With \fBunref\fR it will be reset to NULL if the reference count reaches zero. + +The \fBget\fR and \fBreap\fR functions use the \fIwhich\fR parameter +to specify whether just tasks or both tasks and threads are to be fetched. + +The \fBselect\fR function requires an array of PIDs or UIDs as +\fIthese\fR along with \fInumthese\fR to identify which processes +are to be fetched. +This function then operates as a subset of \fBreap\fR. + +When using the \fBsort\fR function, the parameters \fIstacks\fR and +\fInumstacked\fR would normally be those returned in the `pids_fetch' +structure. + +Lastly, a \fBfatal_proc_unmounted\fR function may be called before +any other function to ensure that the /proc/ directory is mounted. +As such, the \fIinfo\fR parameter would be NULL and the +\fIreturn_self\fR parameter zero. +If, however, some items are desired for the issuing program (a +\fIreturn_self\fR other than zero) then the \fBnew\fR call must precede +it to identify the \fIitems\fR and obtain the required \fIinfo\fR pointer. + +.SH RETURN VALUE +.SS Functions Returning an `int' +An error will be indicated by a negative number that +is always the inverse of some well known errno.h value. + +Success is indicated by a zero return value. +However, the \fBref\fR and \fBunref\fR functions return +the current \fIinfo\fR structure reference count. + +.SS Functions Returning an `address' +An error will be indicated by a NULL return pointer +with the reason found in the formal errno value. + +Success is indicated by a pointer to the named structure. +However, if one survives the \fBfatal_proc_unmounted\fR call, +NULL is always returned when \fIreturn_self\fR is zero. + +.SH DEBUGGING +To aid in program development, there are two procps-ng provisions +that can be exploited. + +The first is a supplied file named `libproc.supp' which may be +useful when developing a \fImulti-threaded\fR application. +When used with the valgrind `--suppressions=' option, warnings +associated with the procps library itself are avoided. + +Such warnings arise because the library handles heap based +allocations in a thread-safe manner. +A \fIsingle-threaded\fR application will not receive those warnings. + +The second provision can help ensure `result' member references +agree with library expectations. +It assumes that a supplied macro in the header file is +used to access the `result' value. + +This feature can be activated through either of the following +methods and any discrepancies will be written to \fBstderr\fR. + +.IP 1) 3 +Add CFLAGS='-DXTRA_PROCPS_DEBUG' to any other ./configure +options your project may employ. + +.IP 2) 3 +Add #include <procps/xtra-procps-debug.h> to any program +\fIafter\fR the #include <procps/pids.h>. + +.PP +This verification feature incurs substantial overhead. +Therefore, it is important that it \fInot\fR be activated +for a production/release build. + +.SH ENVIRONMENT VARIABLE(S) +The value set for the following is unimportant, just its presence. + +.IP LIBPROC_HIDE_KERNEL +This will hide kernel threads which would otherwise be returned with a +.BR procps_pids_get ", " procps_pids_select " or " procps_pids_reap +call. + +.SH SEE ALSO +.BR procps (3), +.BR procps_misc (3), +.BR proc (5). diff --git a/man/ps.1 b/man/ps.1 new file mode 100644 index 0000000..0f4d946 --- /dev/null +++ b/man/ps.1 @@ -0,0 +1,2124 @@ +.\" +.\" Copyright (c) 2004-2023 Craig Small <csmall@dropbear.xyz> +.\" Copyright (c) 2011-2023 Jim Warner <james.warner@comcast.net> +.\" Copyright (c) 2011-2012 Sami Kerola <kerolasa@iki.fi> +.\" Copyright (c) 1998-2003 Albert Cahalan +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" +.TH PS "1" "2023-08-19" "procps-ng" "User Commands" +.\" +.\" Ragged-right text. +.na +.\" Disable hyphenation. +.nh +.\" +.\" ColSize is used for the format spec table. +.\" It's the left margin, minus the right, minus +.\" the space needed for the 1st two columns. +.\" Making it messy: inches, ens, points, scaled points... +.\" +.nr ColSize ((\n[.l] - \n[.i]) / 1n - 29) +.\" +.SH NAME +ps \- report a snapshot of the current processes. +.SH SYNOPSIS +\fBps\fR [\,\fIoptions\/\fR] +.SH DESCRIPTION +.B ps +displays information about a selection of the active processes. If you want +a repetitive update of the selection and the displayed information, use +.B top +instead. +.P +This version of +.B ps +accepts several kinds of options: +.IP +.PD 0 +.IP 1 4 +UNIX options, which may be grouped and must be preceded by a dash. +.IP 2 4 +BSD options, which may be grouped and must not be used with a dash. +.IP 3 4 +GNU long options, which are preceded by two dashes. +.PD +.PP +Options of different types may be freely mixed, but conflicts can appear. +There are some synonymous options, which are functionally identical, due to +the many standards and +.B ps +implementations that this +.B ps +is compatible with. +.P +By default, +.B ps +selects all processes with the same effective user ID (euid=EUID) as the +current user and associated with the same terminal as the invoker. It +displays the process ID (pid=PID), the terminal associated with the process +(tname=TTY), the cumulated CPU time in [DD\-]hh:mm:ss format (time=TIME), and +the executable name (ucmd=CMD). Output is unsorted by default. +.P +The use of BSD\-style options will add process state (stat=STAT) to the +default display and show the command args (args=COMMAND) instead of the +executable name. You can override this with the +.B PS_FORMAT +environment variable. The use of BSD\-style options will also change the +process selection to include processes on other terminals (TTYs) that are +owned by you; alternately, this may be described as setting the selection to +be the set of all processes filtered to exclude processes owned by other +users or not on a terminal. These effects are not considered when options +are described as being "identical" below, so +.B \-M +will be considered identical to \fBZ\fR and so on. +.P +Except as described below, process selection options are additive. The +default selection is discarded, and then the selected processes are added to +the set of processes to be displayed. A process will thus be shown if it +meets any of the given selection criteria. +.SH "EXAMPLES" +.TP 3 +To see every process on the system using standard syntax: +.B ps\ \-e +.br +.B ps\ \-ef +.br +.B ps\ \-eF +.br +.B ps\ \-ely +.TP +To see every process on the system using BSD syntax: +.B ps\ ax +.br +.B ps\ axu +.TP +To print a process tree: +.B ps\ \-ejH +.br +.B ps\ axjf +.TP +To get info about threads: +.B ps\ \-eLf +.br +.B ps\ axms +.TP +To get security info: +.B ps\ \-eo euser,ruser,suser,fuser,f,comm,label +.br +.B ps\ axZ +.br +.B ps\ \-eM +.TP +To see every process running as root (real\ &\ effective\ ID) in user format: +.B ps\ \-U\ root\ \-u\ root\ u +.TP +To see every process with a user\-defined format: +.B ps\ \-eo\ pid,tid,class,rtprio,ni,pri,psr,pcpu,stat,wchan:14,comm +.br +.B ps\ axo\ stat,euid,ruid,tty,tpgid,sess,pgrp,ppid,pid,pcpu,comm +.br +.B ps\ \-Ao\ pid,tt,user,fname,tmout,f,wchan +.TP +Print only the process IDs of syslogd: +.B ps\ \-C\ syslogd\ \-o\ pid= +.TP +Print only the name of PID 42: +.B ps\ \-q\ 42\ \-o\ comm= +.SH "SIMPLE PROCESS SELECTION" +.TP +.B a +Lift the BSD\-style "only yourself" restriction, which is imposed upon the +set of all processes when some BSD\-style (without "\-") options are used or +when the +.B ps +personality setting is BSD\-like. The set of processes selected in this +manner is in addition to the set of processes selected by other means. An +alternate description is that this option causes +.B ps +to list all processes with a terminal (tty), or to list all processes when +used together with the +.B x +option. +.TP +.B \-A +Select all processes. Identical to +.BR \-e . +.TP +.B \-a +Select all processes except both session leaders (see +.IR getsid (2)) +and processes not associated with a terminal. +.TP +.B \-d +Select all processes except session leaders. +.TP +.B \-\-deselect +Select all processes except those that fulfill the specified conditions +(negates the selection). Identical to +.BR \-N . +.TP +.B \-e +Select all processes. Identical to +.BR \-A . +.\" Current "g" behavior: add in the session leaders, which would +.\" be excluded in the sunos4 personality. Supposed "g" behavior: +.\" add in the group leaders -- at least according to the SunOS 4 +.\" man page on the FreeBSD site. Uh oh. I think I had tested SunOS +.\" though, so maybe the code is correct. +.TP +.B g +Really all, even session leaders. This flag is obsolete and may be +discontinued in a future release. It is normally implied by the +.B a +flag, and is only useful when operating in the sunos4 personality. +.TP +.B \-N +Select all processes except those that fulfill the specified conditions +(negates the selection). Identical to +.BR \-\-deselect . +.TP +.B T +Select all processes associated with this terminal. Identical to the +.B t +option without any argument. +.TP +.B r +Restrict the selection to only running processes. +.TP +.B x +Lift the BSD\-style "must have a tty" restriction, which is imposed upon the +set of all processes when some BSD\-style (without "\-") options are used or +when the +.B ps +personality setting is BSD\-like. The set of processes selected in this +manner is in addition to the set of processes selected by other means. An +alternate description is that this option causes +.B ps +to list all processes owned by you (same EUID as +.BR ps ), +or to list all processes when used together with the +.B a +option. +.PD +.SH "PROCESS SELECTION BY LIST" +These options accept a single argument in the form of a blank\-separated or +comma\-separated list. They can be used multiple times. For example: +.B ps\ \-p\ "1\ 2"\ \-p\ 3,4 +.TP +.I 123 +Identical to +.B \-\-pid\ \fI123\fR. +.TP +.RI \+ 123 +Identical to +.B \-\-sid\ \fI123\fR. +.TP +.RI \- 123 +Select by process group ID (PGID). +.TP +.BI \-C \ cmdlist +Select by command name. This selects the processes whose executable name is +given in +.IR cmdlist . +NOTE: The command name is not the same as the command line. Previous versions +of procps and the kernel truncated this command name to 15 characters. This +limitation is no longer present in both. If you depended on matching only +15 characters, you may no longer get a match. +.TP +.BI \-G \ grplist +Select by real group ID (RGID) or name. This selects the processes whose +real group name or ID is in the +.I grplist +list. The real group ID identifies the group of the user who created the +process, see +.IR getgid (2). +.TP +.BI \-g \ grplist +Select by session OR by effective group name. Selection by session is +specified by many standards, but selection by effective group is the logical +behavior that several other operating systems use. This +.B ps +will select by session when the list is completely numeric (as sessions +are). Group ID numbers will work only when some group names are also +specified. See the +.B \-s +and +.B \-\-group +options. +.TP +.BI \-\-Group \ grplist +Select by real group ID (RGID) or name. Identical to +.BR \-G . +.TP +.BI \-\-group \ grplist +Select by effective group ID (EGID) or name. This selects the processes +whose effective group name or ID is in +.IR grplist . +The effective group ID describes the group whose file access permissions are +used by the process (see +.IR getegid (2)). +The +.B \-g +option is often an alternative to +.BR \-\-group . +.TP +.BI p \ pidlist +Select by process ID. Identical to +.B \-p +and +.BR \-\-pid . +.TP +.BI \-p \ pidlist +Select by PID. This selects the processes whose process ID numbers appear in +.IR pidlist . +Identical to +.B p +and +.BR \-\-pid . +.TP +.BI \-\-pid \ pidlist +Select by process\ ID. Identical to +.B \-p +and +.BR p . +.TP +.BI \-\-ppid \ pidlist +Select by parent process ID. This selects the processes with a parent +process\ ID in +.IR pidlist . +That is, it selects processes that are children of those listed in +.IR pidlist . +.TP +.BI q \ pidlist +Select by process ID (quick mode). Identical to +.B \-q +and +.BR \-\-quick\-pid . +.TP +.BI \-q \ pidlist +Select by PID (quick mode). +This selects the processes whose process ID numbers appear in +.IR pidlist . +With this option \fBps\fR reads the necessary info only +for the pids listed in the \fIpidlist\fR and doesn't apply +additional filtering rules. The order of pids is unsorted +and preserved. No additional selection options, sorting +and forest type listings are allowed in this mode. +Identical to +.B q +and +.BR \-\-quick\-pid . +.TP +.BI \-\-quick\-pid \ pidlist +Select by process\ ID (quick mode). Identical to +.B \-q +and +.BR q . +.TP +.BI \-s \ sesslist +Select by session ID. This selects the processes with a session ID specified +in +.IR sesslist . +.TP +.BI \-\-sid \ sesslist +Select by session\ ID. Identical to +.BR \-s . +.TP +.BI t \ ttylist +Select by tty. Nearly identical to +.B \-t +and +.BR \-\-tty , +but can also +be used with an empty +.I ttylist +to indicate the terminal associated with +.BR ps . +Using the +.B T +option is considered cleaner than using +.B t +with an empty +.IR ttylist . +.TP +.BI \-t \ ttylist +Select by tty. This selects the processes associated with the terminals +given in +.IR ttylist . +Terminals (ttys, or screens for text output) can be specified in several +forms: /dev/ttyS1, ttyS1, S1. A plain "\-" may be used to select processes +not attached to any terminal. +.TP +.BI \-\-tty \ ttylist +Select by terminal. Identical to +.B \-t +and +.BR t . +.TP +.BI U \ userlist +Select by effective user ID (EUID) or name. This selects the processes whose +effective user name or ID is in +.IR userlist . +The effective user ID describes the user whose file access permissions are +used by the process (see +.IR geteuid (2)). +Identical to +.B \-u +and +.BR \-\-user . +.TP +.BI \-U \ userlist +Select by real user ID (RUID) or name. It selects the processes whose real +user name or ID is in the +.I userlist +list. The real user ID identifies the user who created the process, see +.IR getuid (2). +.TP +.BI \-u \ userlist +Select by effective user ID (EUID) or name. This selects the processes whose +effective user name or ID is in +.IR userlist . + +The effective user ID describes the user whose file +access permissions are used by the process (see +.IR geteuid (2)). +Identical to +.B U +and +.BR \-\-user . +.TP +.BI \-\-User \ userlist +Select by real user ID (RUID) or name. Identical to +.BR \-U . +.TP +.BI \-\-user \ userlist +Select by effective user ID (EUID) or name. Identical to +.B \-u +and +.BR U . +.PD +.SH "OUTPUT FORMAT CONTROL" +These options are used to choose the information displayed by +.BR ps . +The output may differ by personality. +.TP +.B \-c +Show different scheduler information for the +.B \-l +option. +.TP +.B \-\-context +Display security context format (for SELinux). +.TP +.B \-f +Do full\-format listing. This option can be combined with many other +UNIX\-style options to add additional columns. It also causes the command +arguments to be printed. When used with +.BR \-L , +the NLWP (number of threads) and LWP (thread ID) columns will be added. See +the +.B c +option, the format keyword +.BR args , +and the format keyword +.BR comm . +.TP +.B \-F +Extra full format. See the +.B \-f +option, which +.B \-F +implies. +.TP +.BI \-\-format \ format +user\-defined format. Identical to +.B \-o +and +.BR o . +.TP +.B j +BSD job control format. +.TP +.B \-j +Jobs format. +.TP +.B l +Display BSD long format. +.TP +.B \-l +Long format. The +.B \-y +option is often useful with this. +.TP +.B \-M +Add a column of security data. Identical to +.B Z +(for SELinux). +.TP +.BI O \ format +is preloaded +.B o +(overloaded). The BSD +.B O +option can act like +.B \-O +(user\-defined output format with some common fields predefined) or can be +used to specify sort order. Heuristics are used to determine the behavior of +this option. To ensure that the desired behavior is obtained (sorting or +formatting), specify the option in some other way (e.g. with +.B \-O +or +.BR \-\-sort ). +When used as a formatting option, it is identical to +.BR \-O , +with the BSD personality. +.TP +.BI \-O \ format +Like +.BR \-o , +but preloaded with some default columns. Identical to +.BI \-o\ pid,\: format ,\:state,\:tname,\:time,\:command +or +.BI \-o\ pid,\: format ,\:tname,\:time,\:cmd \fR, +see +.B \-o +below. +.TP +.BI o \ format +Specify user\-defined format. Identical to +.B \-o +and +.BR \-\-format . +.TP +.BI \-o \ format +User\-defined format. +.I format +is a single argument in the form of a blank\-separated or comma\-separated +list, which offers a way to specify individual output columns. The +recognized keywords are described in the +.B STANDARD FORMAT SPECIFIERS +section below. Headers may be renamed +.RB ( "ps \-o pid,\:ruser=RealUser \-o comm=Command" ) +as desired. +If all column headers are empty +.RB ( "ps \-o pid= \-o comm=" ) +then the header line will not be output. Column width will increase as +needed for wide headers; this may be used to widen up columns such as WCHAN +.RB ( "ps \-o pid,\:wchan=\:WIDE\-\:WCHAN\-\:COLUMN \-o comm" ). +Explicit width +control +.RB ( "ps opid,\:wchan:42,\:cmd" ) +is offered too. The behavior of +.B ps \-o pid=X,\:comm=Y +varies with personality; output may be one column named "X,\:comm=Y" or two +columns named "X" and "Y". Use multiple +.B \-o +options when in doubt. Use the +.B PS_FORMAT +environment variable to specify a default as desired; DefSysV and DefBSD are +macros that may be used to choose the default UNIX or BSD columns. +.TP +.B \-P +Add a column showing \fBpsr\fR. +.TP +.B s +Display signal format. +.TP +.B u +Display user\-oriented format. +.TP +.B v +Display virtual memory format. +.TP +.B X +Register format. +.TP +.B \-y +Do not show flags; show rss in place of addr. This option can only be used +with +.BR \-l . +.TP +.B Z +Add a column of security data. Identical to +.B \-M +(for SELinux). +.PD +.SH "OUTPUT MODIFIERS" +.TP +.B c +Show the true command name. This is derived from the name of the executable +file, rather than from the argv value. Command arguments and any +modifications to them are thus not shown. This option effectively turns the +.B args +format keyword into the +.B comm +format keyword; it is useful with the +.B \-f +format option and with the various BSD\-style format options, which all +normally display the command arguments. See the +.B \-f +option, the format +keyword +.BR args , +and the format keyword +.BR comm . +.TP +.BI \-\-cols \ n +Set screen width. +.TP +.BI \-\-columns \ n +Set screen width. +.TP +.B \-\-cumulative +Include some dead child process data (as a sum with the parent). +.TP +.TP +.BI \-D \ format +Set the date format of the \fBlstart\fR field to \fIformat\fR. This format is parsed +by +.BR strftime (3) +and should be a maximum of 24 characters to not mis-align columns. +.TP +.BI \-\-date-format \ format +Identical to \fB\-D\fR. +.TP +.B e +Show the environment after the command. +.TP +.B f +ASCII art process hierarchy (forest). +.TP +.B \-\-forest +ASCII art process tree. +.TP +.B h +No header. (or, one header per screen in the BSD personality). The +.B h +option is problematic. Standard BSD +.B ps +uses this option to print a header on each page of output, but older Linux +.B ps +uses this option to totally disable the header. This version of +.B ps +follows the Linux usage of not printing the header unless the BSD personality +has been selected, in which case it prints a header on each page of output. +Regardless of the current personality, you can use the long options +.B \-\-headers +and +.B \-\-no\-headers +to enable printing headers each page or disable headers entirely, +respectively. +.TP +.B \-H +Show process hierarchy (forest). +.TP +.B \-\-headers +Repeat header lines, one per page of output. +.TP +.BI k \ spec +Specify sorting order. Sorting syntax is +.RB [ + | \- ]\c +.I key\/\c +.RB [,[ + | \- ]\c +.IR key [,...]]. +Choose a multi\-letter key from the +.B STANDARD FORMAT SPECIFIERS +section. The "+" is optional since default direction is increasing +numerical or lexicographic order. Identical to +.BR \-\-sort . +.RS 8 +.IP +Examples: +.br +.B ps jaxkuid,\-ppid,+pid +.br +.B ps axk comm o comm,args +.br +.B ps kstart_time \-ef +.RE +.TP +.BI \-\-lines \ n +Set screen height. +.TP +.B n +Numeric output for WCHAN and USER (including all types of UID and GID). +.TP +.B \-\-no\-headers +Print no header line at all. +.B \-\-no\-heading +is an alias for this option. +.TP +.BI O \ order +Sorting order (overloaded). +The BSD +.B O +option can act like +.B \-O +(user\-defined output format with some common fields predefined) or can be +used to specify sort order. Heuristics are used to determine the behavior of +this option. To ensure that the desired behavior is obtained (sorting or +formatting), specify the option in some other way (e.g. with +.B \-O +or +.BR \-\-sort ). +.IP +For sorting, obsolete BSD +.B O +option syntax is +.BR O [ + | \- ]\c +.IR k1 [,[\c +.BR + | \- ]\c +.IR k2 [,...]]. +It orders the processes listing according to the multilevel sort specified by +the sequence of one\-letter short keys +.IR k1 , k2 ", ...\&" +described in the +.B OBSOLETE SORT KEYS +section below. The\ "+" is currently optional, merely re\-iterating the +default direction on a key, but may help to distinguish an +.B O +sort from an +.B O +format. The "\-" reverses direction only on the key it precedes. +.TP +.BI \-\-rows \ n +Set screen height. +.TP +.B S +Sum up some information, such as CPU usage, from dead child processes into +their parent. This is useful for examining a system where a parent process +repeatedly forks off short\-lived children to do work. +.TP +.BI \-\-sort \ spec +Specify sorting order. Sorting syntax is +.RI [ + | \- ]\c +.IR key [,[\c +.BR + | \- ]\c +.IR key [,...]]. +Choose a multi\-letter key from the +.B STANDARD FORMAT SPECIFIERS +section. The "+" is optional since default direction is increasing numerical +or lexicographic order. Identical to +.BR k . +For example: +.B ps jax \-\-sort=\:uid,\:\-ppid,\:+pid +.TP +.B \-\-signames +Show signal masks using abbreviated signal names and expands the collumn. +If the column width cannot show all signals, the column will end with a plus "\fI+\fR". +Columns with only a hyphen have no signals. +.TP +.B w +Wide output. Use this option twice for unlimited width. +.TP +.B \-w +Wide output. Use this option twice for unlimited width. +.TP +.BI \-\-width \ n +Set screen width. +.PD +.SH "THREAD DISPLAY" +.TP +.B H +Show threads as if they were processes. +.TP +.B \-L +Show threads, possibly with LWP and NLWP columns. +.TP +.B m +Show threads after processes. +.TP +.B \-m +Show threads after processes. +.TP +.B \-T +Show threads, possibly with SPID column. +.SH "OTHER INFORMATION" +.TP +.BI \-\-help \ section +Print a help message. The \fIsection\fR argument can be one of +.IR s imple, +.IR l ist, +.IR o utput, +.IR t hreads, +.IR m "isc, or" +.IR a ll. +The argument can be shortened to one of the underlined letters as in: +s\^|\^l\^|\^o\^|\^t\^|\^m\^|\^a. +.TP +.B \-\-info +Print debugging info. +.TP +.B L +List all format specifiers. +.TP +.B V +Print the procps-ng version. +.TP +.B \-V +Print the procps-ng version. +.TP +.B \-\-version +Print the procps-ng version. +.SH NOTES +This +.B ps +works by reading the virtual files in /proc. This +.B ps +does not need to be setuid kmem or have any privileges to run. Do not give +this +.B ps +any special permissions. +.PP +CPU usage is currently expressed as the percentage of time spent running +during the entire lifetime of a process. This is not ideal, and\ it does not +conform to the standards that +.B ps +otherwise conforms to. CPU usage is unlikely to add up to exactly 100%. +.PP +The SIZE and RSS fields don't count some parts of a process including the +page tables, kernel stack, struct thread_info, and struct task_struct. This +is usually at least 20\ KiB of memory that is always resident. SIZE is the +virtual size of the process (code+\:data+\:stack). +.PP +Processes marked <defunct> are dead processes (so\-called "zombies") that +remain because their parent has not destroyed them properly. These processes +will be destroyed by +.IR init (8) +if the parent process exits. +.PP +If the length of the username is greater than the width of the display +column, the username will be truncated. See the \fB\-o\fR and \fB\-O\fR +formatting options to customize length. +.PP +Commands options such as +.B ps \-aux +are not recommended as it is a confusion of two different standards. +According to the POSIX and UNIX standards, the above command asks to +display all processes with a TTY (generally the commands users are +running) plus all processes owned by a user named \fIx\fR. If that user +doesn't exist, then +.B ps +will assume you really meant +.RB """" ps +.IR aux """." +.SH "PROCESS FLAGS" +The sum of these values is displayed in the "F" column, +which is provided by the +.B flags +output specifier: +.PP +.RS 8 +.PD 0 +.TP 5 +1 +forked but didn't exec +.TP +4 +used super\-user privileges +.PD +.RE +.SH "PROCESS STATE CODES" +Here are the different values that the +.BR s ", " stat " and " state +output specifiers (header "STAT" or "S") will display to describe the state +of a process: +.PP +.RS 8 +.PD 0 +.TP 5 +D +uninterruptible sleep (usually IO) +.TP +I +Idle kernel thread +.TP +R +running or runnable (on run queue) +.TP +S +interruptible sleep (waiting for an event to complete) +.TP +T +stopped by job control signal +.TP +t +stopped by debugger during the tracing +.TP +W +paging (not valid since the 2.6.xx kernel) +.TP +X +dead (should never be seen) +.TP +Z +defunct ("zombie") process, terminated but not reaped by its parent +.PD +.RE +.PP +For BSD formats and when the +.B stat +keyword is used, additional characters may be displayed: +.PP +.RS 8 +.PD 0 +.TP 5 +< +high\-priority (not nice to other users) +.TP +N +low\-priority (nice to other users) +.TP +L +has pages locked into memory (for real\-time and custom IO) +.TP +s +is a session leader +.TP +l +is multi-threaded (using CLONE_THREAD, like NPTL pthreads do) +.TP ++ +is in the foreground process group +.PD +.RE +.SH "OBSOLETE SORT KEYS" +These keys are used by the BSD +.B O +option (when it is used for sorting). The GNU +.B \-\-sort +option doesn't use these keys, but the specifiers described below in the +.B STANDARD FORMAT SPECIFIERS +section. Note that the values used in sorting are the internal values +.B ps +uses and not the "cooked" values used in some of the output format fields +(e.g. sorting on tty will sort into device number, not according to the +terminal name displayed). Pipe +.B ps +output into the +.BR sort (1) +command if you want to sort the cooked values. +.TS +l l lw(3i). +\fBKEY LONG DESCRIPTION\fR +c cmd simple name of executable +C pcpu cpu utilization +f flags flags as in long format F field +g pgrp process group ID +G tpgid controlling tty process group ID +j cutime cumulative user time +J cstime cumulative system time +k utime user time +m min_flt number of minor page faults +M maj_flt number of major page faults +n cmin_flt cumulative minor page faults +N cmaj_flt cumulative major page faults +o session session ID +p pid process ID +P ppid parent process ID +r rss resident set size +R resident resident pages +s size memory size in kilobytes +S share amount of shared pages +t tty the device number of the controlling tty +T start_time time process was started +U uid user ID number +u user user name +v vsize total VM size in KiB +y priority kernel scheduling priority +.\"K stime system time (conflict, system vs. start time) +.TE +.SH "AIX FORMAT DESCRIPTORS" +This +.B ps +supports AIX format descriptors, which work somewhat like the +formatting codes of +.IR printf (1) +and +.IR printf (3). +For example, the normal default output can be produced with this: +.B ps \-eo """%p %y %x %c""\fR." +The +.B NORMAL +codes are described in the next section. +.TS +l l l. +\fBCODE NORMAL HEADER\fR +%C pcpu %CPU +%G group GROUP +%P ppid PPID +%U user USER +%a args COMMAND +%c comm COMMAND +%g rgroup RGROUP +%n nice NI +%p pid PID +%r pgid PGID +%t etime ELAPSED +%u ruser RUSER +%x time TIME +%y tty TTY +%z vsz VSZ +.TE +.SH "STANDARD FORMAT SPECIFIERS" +Here are the different keywords that may be used to control the output +format (e.g., with option +.BR \-o ) +or to sort the selected processes with the GNU\-style +.B \-\-sort +option. +.PP +For example: +.B ps \-eo pid,\:user,\:args \-\-sort user +.PP +This version of +.B ps +tries to recognize most of the keywords used in other implementations of +.BR ps . +.PP +The following user\-defined format specifiers may contain +spaces: +.BR args ", " cmd ", " comm ", " command ", " fname ", " ucmd ", " ucomm , +.BR lstart ", " bsdstart ", " start . +.PP +Some keywords may not be available for sorting. + +.\" ####################################################################### +.\" lB1 lB1 lB1 lB1 s s s +.\" lB1 l1 l1 l1 s s s. +.\" +.\" lB1 lB1 lBw(5.5i) +.\" lB1 l1 l. +.\" +.TS +expand; +l1B l1B lBw(\n[ColSize]n) +l1B l1 l. +CODE HEADER DESCRIPTION + +%cpu %CPU T{ +cpu utilization of the process in "##.#" format. Currently, it is the CPU +time used divided by the time the process has been running (cputime/realtime +ratio), expressed as a percentage. It will not add up to 100% unless you are +lucky. (alias +.BR pcpu ). +T} + +%mem %MEM T{ +ratio of the process's resident set size to the physical memory on the +machine, expressed as a percentage. (alias +.BR pmem ). +T} + +ag_id AGID T{ +The autogroup identifier associated with a process which operates in conjunction +with the CFS scheduler to improve interactive desktop performance. +T} + +ag_nice AGNI T{ +The autogroup nice value which affects scheduling of all processes in that group. +T} + +args COMMAND T{ +command with all its arguments as a string. Modifications to the arguments +may be shown. The output in this column may contain spaces. A process +marked <defunct> is partly dead, waiting to be fully destroyed by its parent. +Sometimes the process args will be unavailable; when this happens, +.B ps +will instead print the executable name in brackets. (alias +.BR cmd ", " command ). +See also the +.B comm +format keyword, the +.B \-f +option, and the +.B c +option. +.br +When specified last, this column will extend to the edge of the display. If +.B ps +can not determine display width, as when output is redirected (piped) into a +file or another command, the output width is undefined (it may be 80, +unlimited, determined by the +.B TERM +variable, and so on). The +.B COLUMNS +environment variable or +.B \-\-cols +option may be used to exactly determine the width in this case. The +.B w +or +.B \-w +option may be also be used to adjust width. +T} + +blocked BLOCKED T{ +mask of the blocked signals, see +.IR signal (7). +According to the width of the field, a 32 or 64\-bit mask in hexadecimal +format is displayed, unless the \fB\-\-signames\fR option is used. (alias +.BR sig_block ", " sigmask ). +T} + +bsdstart START T{ +time the command started. If the process was started less than 24 hours ago, +the output format is "\ HH:MM", else it is " Mmm:SS" (where Mmm is the three +letters of the month). See also +.BR lstart , \ start , \ start_time ", and" \ stime . +T} + +bsdtime TIME T{ +accumulated cpu time, user + system. The display format is usually +"MMM:SS", but can be shifted to the right if the process used more than 999 +minutes of cpu time. +T} + +c C T{ +processor utilization. Currently, this is the integer value of the percent +usage over the lifetime of the process. (see +.BR %cpu ). +T} + +caught CAUGHT T{ +mask of the caught signals, see +.IR signal (7). +According to the width of the field, a 32 or 64 bits mask in hexadecimal +format is displayed, unless the \fB\-\-signames\fR option is used. (alias +.BR sig_catch ", " sigcatch ). +T} + +cgname CGNAME T{ +display name of control groups to which the process belongs. +T} + +cgroup CGROUP T{ +display control groups to which the process belongs. +T} + +cgroupns CGROUPNS T{ +Unique inode number describing the namespace the process belongs to. +See +.IR namespaces (7). +T} + +class CLS T{ +scheduling class of the process. (alias +.BR policy ", " cls ). +Field's possible values are: +.sp 1 +.in +9n +\- not reported +.br +TS SCHED_OTHER +.br +FF SCHED_FIFO +.br +RR SCHED_RR +.br +B SCHED_BATCH +.br +ISO SCHED_ISO +.br +IDL SCHED_IDLE +.br +DLN SCHED_DEADLINE +.br +? unknown value +.in +T} + +cls CLS T{ +scheduling class of the process. (alias +.BR policy ", " cls ). +Field's possible values are: +.sp 1 +.in +9n +\- not reported +.br +TS SCHED_OTHER +.br +FF SCHED_FIFO +.br +RR SCHED_RR +.br +B SCHED_BATCH +.br +ISO SCHED_ISO +.br +IDL SCHED_IDLE +.br +DLN SCHED_DEADLINE +.br +? unknown value +.in +T} + +cmd CMD T{ +see +.BR args . +(alias +.BR args ", " command ). +T} + +comm COMMAND T{ +command name (only the executable name). The output in this column may +contain spaces. +(alias +.BR ucmd ", " ucomm ). +See also the +.B args +format keyword, the +.B \-f +option, and the +.B c +option. +.br +When specified last, this column will extend to the edge of the display. If +.B ps +can not determine display width, as when output is redirected (piped) into a +file or another command, the output width is undefined (it may be 80, +unlimited, determined by the +.B TERM +variable, and so on). The +.B COLUMNS +environment variable or +.B \-\-cols +option may be used to exactly determine the width in this case. The +.BR w \ or \ \-w +option may be also be used to adjust width. +T} + +command COMMAND T{ +See +.BR args . +(alias +.BR args ", " command ). +T} + +cp CP T{ +per\-mill (tenths of a percent) CPU usage. (see +.BR %cpu ). +T} + +cputime TIME T{ +cumulative CPU time, "[DD\-]hh:mm:ss" format. (alias +.BR time ). +T} + +cputimes TIME T{ +cumulative CPU time in seconds (alias +.BR times ). +T} + +cuc %CUC T{ +The CPU utilization of a process, including dead children, in an extended "##.###" format. +(see also +.BR %cpu , +.BR c , +.BR cp , +.BR cuu , +.BR pcpu ). +T} + +cuu %CUU T{ +The CPU utilization of a process in an extended "##.###" format. +(see also +.BR %cpu , +.BR c , +.BR cp , +.BR cuc , +.BR pcpu ). +T} + +drs DRS T{ +data resident set size, the amount of private memory \fIreserved\fR by a process. +It is also known as DATA. Such memory may not yet be mapped to +.B rss +but will always be included +included in the +.B vsz +amount. + +T} + +egid EGID T{ +effective group ID number of the process as a decimal integer. (alias +.BR gid ). +T} + +egroup EGROUP T{ +effective group ID of the process. This will be the textual group ID, if it +can be obtained and the field width permits, or a decimal representation +otherwise. (alias +.BR group ). +T} + +eip EIP T{ +instruction pointer. As of kernel 4.9.xx will be zeroed out unless task is +exiting or being core dumped. +T} + +esp ESP T{ +stack pointer. As of kernel 4.9.xx will be zeroed out unless task is +exiting or being core dumped. +T} + +etime ELAPSED T{ +elapsed time since the process was started, in the form [[DD\-]hh:]mm:ss. +T} + +etimes ELAPSED T{ +elapsed time since the process was started, in seconds. +T} + +euid EUID T{ +effective user ID (alias +.BR uid ). +T} + +euser EUSER T{ +effective user name. This will be the textual user ID, if it can be obtained +and the field width permits, or a decimal representation otherwise. The +.B n +option can be used to force the decimal representation. (alias +.BR uname ", " user ). +T} + +exe EXE T{ +path to the executable. Useful if path cannot be printed via +.BR cmd ", " comm +or +.BR args +format options. +T} + +f F T{ +flags associated with the process, see the +.B PROCESS FLAGS +section. (alias +.BR flag ", " flags ). +T} + +fgid FGID T{ +filesystem access group\ ID. (alias +.BR fsgid ). +T} + +fgroup FGROUP T{ +filesystem access group ID. This will be the textual group ID, if it can +be obtained and the field width permits, or a decimal representation +otherwise. (alias +.BR fsgroup ). +T} + +flag F T{ +see +.BR f . +(alias +.BR f ", " flags ). +T} + +flags F T{ +see +.BR f . +(alias +.BR f ", " flag ). +T} + +fname COMMAND T{ +first 8 bytes of the base name of the process's executable file. The output +in this column may contain spaces. +T} + +fuid FUID T{ +filesystem access user ID. (alias +.BR fsuid ). +T} + +fuser FUSER T{ +filesystem access user ID. This will be the textual user ID, if it can be +obtained and the field width permits, or a decimal representation otherwise. +T} + +gid GID T{ +see +.BR egid . +(alias +.BR egid ). +T} + +group GROUP T{ +see +.BR egroup . +(alias +.BR egroup ). +T} + +ignored IGNORED T{ +mask of the ignored signals, see +.IR signal (7). +According to the width of the field, a 32 or 64 bits mask in hexadecimal +format is displayed, unless the \fB\-\-signames\fR option is used. (alias +.BR sig_ignore ", " sigignore ). +T} + +ipcns IPCNS T{ +Unique inode number describing the namespace the process belongs to. +See +.IR namespaces (7). +T} + +label LABEL T{ +security label, most commonly used for SELinux context data. This is for +the +.I Mandatory Access Control +("MAC") found on high\-security systems. +T} + +lstart STARTED T{ +time the command started. This will be in the form "DDD mmm HH:MM:SS YYY" +unless changed by the \fB\-D\fR option. +T} + +lsession SESSION T{ +displays the login session identifier of a process, +if systemd support has been included. +T} + +luid LUID T{ +displays Login ID associated with a process. +T} + +lwp LWP T{ +light weight process (thread) ID of the dispatchable entity (alias +.BR spid , \ tid ). +See +.B tid +for additional information. +T} + +lxc LXC T{ +The name of the lxc container within which a task is running. +If a process is not running inside a container, a dash ('\-') will be shown. +T} + +machine MACHINE T{ +displays the machine name for processes assigned to VM or container, +if systemd support has been included. +T} + +maj_flt MAJFLT T{ +The number of major page faults that have occurred with this process. +T} + +min_flt MINFLT T{ +The number of minor page faults that have occurred with this process. +T} + +mntns MNTNS T{ +Unique inode number describing the namespace the process belongs to. +See +.IR namespaces (7). +T} + +netns NETNS T{ +Unique inode number describing the namespace the process belongs to. +See +.IR namespaces (7). +T} + +ni NI T{ +nice value. This ranges from 19 (nicest) to \-20 (not nice to others), +see +.IR nice (1). +(alias +.BR nice ). +T} + +nice NI T{ +see +.BR ni . (alias +.BR ni ). +T} + +nlwp NLWP T{ +number of lwps (threads) in the process. (alias +.BR thcount ). +T} + +numa NUMA T{ +The node associated with the most recently used processor. +A \fI\-1\fR means that NUMA information is unavailable. +T} + +nwchan WCHAN T{ +address of the kernel function where the process is sleeping (use +.B wchan +if you want the kernel function name). +T} + +oom OOM T{ +Out of Memory Score. The value, ranging from 0 to +1000, used to select +task(s) to kill when memory is exhausted. +T} + +oomadj OOMADJ T{ +Out of Memory Adjustment Factor. The value is added to the current out of +memory score which is then used to determine which task to kill when memory +is exhausted. +T} + +ouid OWNER T{ +displays the Unix user identifier of the owner of the session of a process, +if systemd support has been included. +T} + +pcpu %CPU T{ +see +.BR %cpu . +(alias +.BR %cpu ). +T} + +pending PENDING T{ +mask of the pending signals. See +.IR signal (7). +Signals pending on the process are distinct from signals pending on +individual threads. Use the +.B m +option or the +.B \-m +option to see both. According to the width of the field, a 32 or 64 bits +mask in hexadecimal +format is displayed, unless the \fB\-\-signames\fR option is used. (alias +.BR sig ). +T} + +pgid PGID T{ +process group ID or, equivalently, the process ID of the process group +leader. (alias +.BR pgrp ). +T} + +pgrp PGRP T{ +see +.BR pgid . +(alias +.BR pgid ). +T} + +pid PID T{ +a number representing the process ID (alias +.BR tgid ). +T} + +pidns PIDNS T{ +Unique inode number describing the namespace the process belongs to. +See +.IR namespaces (7). +T} + +pmem %MEM T{ +see +.BR %mem . +(alias +.BR %mem ). +T} + +policy POL T{ +scheduling class of the process. (alias +.BR class ", " cls ). +Possible values are: +.sp 1 +.in +9n +\- not reported +.br +TS SCHED_OTHER +.br +FF SCHED_FIFO +.br +RR SCHED_RR +.br +B SCHED_BATCH +.br +ISO SCHED_ISO +.br +IDL SCHED_IDLE +.br +DLN SCHED_DEADLINE +.br +? unknown value +.in +T} + +ppid PPID T{ +parent process ID. +T} + +pri PRI T{ +priority of the process. Higher number means higher priority. +T} + +psr PSR T{ +processor that process last executed on. +T} + +pss PSS T{ +Proportional share size, the non-swapped physical memory, with shared memory +proportionally accounted to all tasks mapping it. +T} + +rbytes RBYTES T{ +Number of bytes which this process really did cause to be fetched from the storage layer. +T} + +rchars RCHARS T{ +Number of bytes which this task has caused to be read from storage. +T} + +rgid RGID T{ +real group ID. +T} + +rgroup RGROUP T{ +real group name. This will be the textual group ID, if it can be obtained +and the field width permits, or a decimal representation otherwise. +T} + +rops ROPS T{ +Number of read I/O operations—that is, system calls such as +.BR read "(2) and " pread (2). +T} + +rss RSS T{ +resident set size, the non\-swapped physical memory that a task has used (in +kilobytes). (alias +.BR rssize ", " rsz ). +T} + +rssize RSS T{ +see +.BR rss . +(alias +.BR rss ", " rsz ). +T} + +rsz RSZ T{ +see +.BR rss . +(alias +.BR rss ", " rssize ). +T} + +rtprio RTPRIO T{ +realtime priority. +T} + +ruid RUID T{ +real user ID. +T} + +ruser RUSER T{ +real user ID. This will be the textual user ID, if it can be obtained and +the field width permits, or a decimal representation otherwise. +T} + +s S T{ +minimal state display (one character). See section +.B PROCESS STATE CODES +for the different values. See also +.B stat +if you want additional information displayed. (alias +.BR state ). +T} + +sched SCH T{ +scheduling policy of the process. The policies SCHED_OTHER (SCHED_NORMAL), +SCHED_FIFO, SCHED_RR, SCHED_BATCH, SCHED_ISO, SCHED_IDLE and SCHED_DEADLINE are +respectively displayed as 0, 1, 2, 3, 4, 5 and 6. +T} + +seat SEAT T{ +displays the identifier associated with all hardware devices assigned +to a specific workplace, +if systemd support has been included. +T} + +sess SESS T{ +session ID or, equivalently, the process ID of the session leader. (alias +.BR session ", " sid ). +T} + +sgi_p P T{ +processor that the process is currently executing on. Displays "*" if the +process is not currently running or runnable. +T} + +sgid SGID T{ +saved group ID. (alias +.BR svgid ). +T} + +sgroup SGROUP T{ +saved group name. This will be the textual group ID, if it can be obtained +and the field width permits, or a decimal representation otherwise. +T} + +sid SID T{ +see +.BR sess . +(alias +.BR sess ", " session ). +T} + +sig PENDING T{ +see +.BR pending . +(alias +.BR pending ", " sig_pend ). +T} + +sigcatch CAUGHT T{ +see +.BR caught . +(alias +.BR caught ", " sig_catch ). +T} + +sigignore IGNORED T{ +see +.BR ignored . +(alias +.BR ignored ", " sig_ignore ). +T} + +sigmask BLOCKED T{ +see +.BR blocked . +(alias +.BR blocked ", " sig_block ). +T} + +size SIZE T{ +approximate amount of swap space that would be required if the process were +to dirty all writable pages and then be swapped out. This number is very +rough! +T} + +slice SLICE T{ +displays the slice unit which a process belongs to, +if systemd support has been included. +T} + +spid SPID T{ +see +.BR lwp . +(alias +.BR lwp ", " tid ). +T} + +stackp STACKP T{ +address of the bottom (start) of stack for the process. +T} + +start STARTED T{ +time the command started. If the process was started less than 24 hours ago, +the output format is "HH:MM:SS", else it is "\ \ Mmm\ dd" (where Mmm is a +three\-letter month name). See also +.BR bsdstart ", " start ", " start_time ", and " stime . +T} + +start_time START T{ +starting time or date of the process. Only the year will be displayed if the +process was not started the same year +.B ps +was invoked, or "MmmDD" if it was not started the same day, or "HH:MM" +otherwise. See also +.BR bsdstart ", " start ", " lstart ", and " stime . +T} + +stat STAT T{ +multi\-character process state. See section +.B PROCESS STATE CODES +for the different values meaning. See also +.BR s \ and \ state +if you just want the first character displayed. +T} + +state S T{ +see +.BR s ".\& (alias" \ s ). +T} + +stime STIME T{ +see \fBstart_time\fR. (alias \fBstart_time\fR). +T} + +suid SUID T{ +saved user ID. (alias +.BR svuid ). +T} + +supgid SUPGID T{ +group ids of supplementary groups, if any. See +.BR getgroups (2). +T} + +supgrp SUPGRP T{ +group names of supplementary groups, if any. See +.BR getgroups (2). +T} + +suser SUSER T{ +saved user name. This will be the textual user ID, if it can be obtained and +the field width permits, or a decimal representation otherwise. (alias +.BR svuser ). +T} + +svgid SVGID T{ +see +.BR sgid . +(alias +.BR sgid ). +T} + +svuid SVUID T{ +see +.BR suid . +(alias +.BR suid ). +T} + +sz SZ T{ +size in physical pages of the core image of the process. This includes text, +data, and stack space. Device mappings are currently excluded; this is +subject to change. See +.BR vsz \ and \ rss . +T} + +tgid TGID T{ +a number representing the thread group to which a task belongs (alias +.BR pid ). +It is the process ID of the thread group leader. +T} + +thcount THCNT T{ +see +.BR nlwp . +(alias +.BR nlwp ). +number of kernel threads owned by the process. +T} + +tid TID T{ +the unique number representing a dispatchable entity (alias +.BR spid ", " tid ). +This value may also appear as: a process ID (pid); a process group ID (pgrp); +a session ID for the session leader (sid); a thread group ID for the thread +group leader (tgid); and a tty process group ID for the process group leader +(tpgid). +T} + +time TIME T{ +cumulative CPU\ time, "[DD\-]HH:MM:SS" format. (alias +.BR cputime ). +T} + +timens TIMENS T{ +Unique inode number describing the namespace the process belongs to. +See +.IR namespaces (7). +T} + +times TIME T{ +cumulative CPU\ time in seconds (alias +.BR cputimes ). +T} + +tname TTY T{ +controlling tty (terminal). (alias +.BR tt ", " tty ). +T} + +tpgid TPGID T{ +ID of the foreground process group on the tty (terminal) that the process is +connected to, or \-1 if the process is not connected to a tty. +T} + +trs TRS T{ +text resident set size, the amount of physical memory devoted to executable code. +T} + +tt TT T{ +controlling tty (terminal). (alias +.BR tname ", " tty ). +T} + +tty TT T{ +controlling tty (terminal). (alias +.BR tname ", " tt ). +T} + +ucmd CMD T{ +see +.BR comm . +(alias +.BR comm ", " ucomm ). +T} + +ucomm COMMAND T{ +see +.BR comm . +(alias +.BR comm ", " ucmd ). +T} + +uid UID T{ +see +.BR euid . +(alias +.BR euid ). +T} + +uname USER T{ +see +.BR euser . +(alias +.BR euser ", " user ). +T} + +unit UNIT T{ +displays unit which a process belongs to, +if systemd support has been included. +T} + +user USER T{ +see +.BR euser . +(alias +.BR euser ", " uname ). +T} + +userns USERNS T{ +Unique inode number describing the namespace the process belongs to. +See +.IR namespaces (7). +T} + +uss USS T{ +Unique set size, the non-swapped physical memory, which +is not shared with an another task. +T} + +utsns UTSNS T{ +Unique inode number describing the namespace the process belongs to. +See +.IR namespaces (7). +T} + +uunit UUNIT T{ +displays user unit which a process belongs to, +if systemd support has been included. +T} + +vsize VSZ T{ +see +.BR vsz . +(alias +.BR vsz ). +T} + +vsz VSZ T{ +virtual memory size of the process in KiB (1024\-byte units). Device +mappings are currently excluded; this is subject to change. (alias +.BR vsize ). +T} + +wbytes WBYTES T{ +Number of bytes which this process caused to be sent to the storage layer. +T} + +wcbytes WCBYTES T{ +Number of cancelled write bytes. +T} + +wchan WCHAN T{ +name of the kernel function in which the process is sleeping. +T} + +wchars WCHARS T{ +Number of bytes which this task has caused, or shall cause to be written to disk. +T} + +wops WOPS T{ +Number of write I/O operations—that is, system calls such as +.BR write "(2) and " pwrite (2). +T} + +.TE +.SH "ENVIRONMENT VARIABLES" +The following environment variables could affect +.BR ps : +.TP 3 +.B COLUMNS +Override default display width. +.TP +.B LINES +Override default display height. +.TP +.B PS_PERSONALITY +Set to one of posix, old, linux, bsd, sun, digital...\& (see section +.B PERSONALITY +below). +.TP +.B CMD_ENV +Set to one of posix, old, linux, bsd, sun, digital...\& (see section +.B PERSONALITY +below). +.TP +.B I_WANT_A_BROKEN_PS +Force obsolete command line interpretation. +.TP +.B LC_TIME +Date format. +.TP +.B LIBPROC_HIDE_KERNEL +Set this to any value to hide kernel threads normally displayed with the +.B -e +option. This is equivalent to selecting +.B --ppid 2 -p 2 --deselect +instead. Also works in BSD mode. +.TP +.B PS_COLORS +Not currently supported. +.TP +.B PS_FORMAT +Default output format override. You may set this to a format +string of the type used for the +.B \-o +option. +The +.B DefSysV +and +.B DefBSD +values are particularly useful. +.TP +.B POSIXLY_CORRECT +Don't find excuses to ignore bad "features". +.TP +.B POSIX2 +When set to "on", acts as +.BR POSIXLY_CORRECT . +.TP +.B UNIX95 +Don't find excuses to ignore bad "features". +.TP +.B _XPG +Cancel +.BR CMD_ENV =\c +.I irix +non\-standard behavior. +.PP +In general, it is a bad idea to set these variables. The one exception is +.B CMD_ENV +or +.BR PS_PERSONALITY , +which could be set to Linux for normal systems. Without that setting, +.B ps +follows the useless and bad parts of the Unix98 standard. +.SH "PERSONALITY" +.TS +l l. +390 like the OS/390 OpenEdition \fBps\fR +aix like AIX \fBps\fR +bsd like FreeBSD \fBps\fR (totally non\-standard) +compaq like Digital Unix \fBps\fR +debian like the old Debian \fBps\fR +digital like Tru64 (was Digital\ Unix, was OSF/1) \fBps\fR +gnu like the old Debian \fBps\fR +hp like HP\-UX \fBps\fR +hpux like HP\-UX \fBps\fR +irix like Irix \fBps\fR +linux ***** \fBrecommended\fR ***** +old like the original Linux \fBps\fR (totally non\-standard) +os390 like OS/390 Open Edition \fBps\fR +posix standard +s390 like OS/390 Open Edition \fBps\fR +sco like SCO \fBps\fR +sgi like Irix \fBps\fR +solaris2 like Solaris 2+ (SunOS 5) \fBps\fR +sunos4 like SunOS 4 (Solaris 1) \fBps\fR (totally non\-standard) +svr4 standard +sysv standard +tru64 like Tru64 (was Digital Unix, was OSF/1) \fBps\fR +unix standard +unix95 standard +unix98 standard +.TE +.SH BUGS +The fields \fBbsdstart\fR and \fBstart\fR will only show the abbreviated +month name in English. The fields \fBlstart\fR and \fBstime\fR will show +the abbreviated month name in the configured locale but may exceed the +column width due to the different lengths for abbreviated month and day +names across languages. +.PP +.SH "SEE ALSO" +.BR pgrep (1), +.BR pstree (1), +.BR top (1), +.BR strftime (3), +.BR proc (5). +.SH STANDARDS +This +.B ps +conforms to: +.PP +.PD 0 +.IP 1 4 +Version 2 of the Single Unix Specification +.IP 2 4 +The Open Group Technical Standard Base Specifications, Issue\ 6 +.IP 3 4 +IEEE Std 1003.1, 2004\ Edition +.IP 4 4 +X/Open System Interfaces Extension [UP\ XSI] +.IP 5 4 +ISO/IEC 9945:2003 +.PD +.SH AUTHOR +.B ps +was originally written by +.MT lankeste@\:fwi.\:uva.\:nl +Branko Lankester +.ME . +.MT johnsonm@\:redhat.\:com +Michael K. Johnson +.ME +re\-wrote it significantly to use the proc filesystem, changing a few things +in the process. +.MT mjshield@\:nyx.\:cs.\:du.\:edu +Michael Shields +.ME +added the pid\-list feature. +.MT cblake@\:bbn.\:com +Charles Blake +.ME +added multi\-level sorting, the dirent\-style library, the device +name\-to\-number mmaped database, the approximate binary search directly on +System.map, and many code and documentation cleanups. David Mossberger\-Tang +wrote the generic BFD support for psupdate. +.MT albert@\:users.\:sf.\:net +Albert Cahalan +.ME +rewrote ps for full Unix98 and BSD support, along with some ugly hacks for +obsolete and foreign syntax. +.PP +Please send bug reports to +.MT procps@\:freelists.\:org +.ME . +No subscription is required or suggested. diff --git a/man/pwdx.1 b/man/pwdx.1 new file mode 100644 index 0000000..98e7b6e --- /dev/null +++ b/man/pwdx.1 @@ -0,0 +1,40 @@ +.\" +.\" Copyright (c) 2020-2023 Craig Small <csmall@dropbear.xyz> +.\" Copyright (c) 2011-2012 Sami Kerola <kerolasa@iki.fi> +.\" Copyright (c) 2004 Nicholas Miel. +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" +.TH PWDX "1" "2020-06-04" "procps-ng" "User Commands" +.SH NAME +pwdx \- report current working directory of a process +.SH SYNOPSIS +.B pwdx +[\fIoptions\fR] \fIpid\fR [...] +.SH OPTIONS +.TP +\fB\-V\fR, \fB\-\-version\fR +Output version information and exit. +.TP +\fB\-h\fR, \fB\-\-help\fR +Output help screen and exit. +.SH "SEE ALSO" +.BR ps (1), +.BR pgrep (1) +.SH STANDARDS +No standards apply, but +.B pwdx +looks an awful lot like a SunOS command. +.SH AUTHOR +.UR nmiell@gmail.com +Nicholas Miell +.UE +wrote pwdx in 2004. +.SH "REPORTING BUGS" +Please send bug reports to +.UR procps@freelists.org +.UE diff --git a/man/skill.1 b/man/skill.1 new file mode 100644 index 0000000..de95871 --- /dev/null +++ b/man/skill.1 @@ -0,0 +1,128 @@ +.\" +.\" Copyright (c) 2011-2023 Craig Small <csmall@dropbear.xyz> +.\" Copyright (c) 2011-2012 Sami Kerola <kerolasa@iki.fi> +.\" Copyright (c) 2002-2006 Albert Cahalan +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" +.TH SKILL 1 "2023-08-19" "procps-ng" "User Commands" +.SH NAME +skill, snice \- send a signal or report process status +.SH SYNOPSIS +.B skill +.RI [ signal ] +.RI [ options ] +.I expression +.br +.B snice +.RI [ "new priority" ] +.RI [ options ] +.I expression +.SH DESCRIPTION +These tools are obsolete and unportable. The command syntax is +poorly defined. Consider using the +.BR killall , +.BR pkill , +and +.B pgrep +commands instead. +.PP +The default signal for \fBskill\fP is TERM. Use \fB\-l\fP or \fB\-L\fP to list +available signals. Particularly useful signals include HUP, INT, +KILL, STOP, CONT, and 0. Alternate signals may be specified in three +ways: \fB\-9\fP \fB\-SIGKILL\fP \fB\-KILL\fP. +.PP +The default priority for \fBsnice\fP is +4. Priority numbers range from ++20 (slowest) to \-20 (fastest). Negative priority numbers are +restricted to administrative users. +.SH OPTIONS +.TP +.BR \-f , \ \-\-fast +Fast mode. This option has not been implemented. +.TP +.BR \-i , \ \-\-interactive +Interactive use. You will be asked to approve each action. +.TP +.BR \-l , \ \-\-list +List all signal names. +.TP +.BR \-L , \ \-\-table +List all signal names in a nice table. +.TP +.BR \-n , \ \-\-no\-action +No action; perform a simulation of events that would occur but do not +actually change the system. +.TP +.BR \-v , \ \-\-verbose +Verbose; explain what is being done. +.TP +.BR \-w , \ \-\-warnings +Enable warnings. This option has not been implemented. +.TP +\fB\-h\fR, \fB\-\-help\fR +Display help text and exit. +.TP +\fB\-V\fR, \fB\-\-version\fR +Display version information. +.PD +.SH "PROCESS SELECTION OPTIONS" +Selection criteria can be: terminal, user, pid, command. The options +below may be used to ensure correct interpretation. +.TP +\fB\-t\fR, \fB\-\-tty\fR \fItty\fR +The next expression is a terminal (tty or pty). +.TP +\fB\-u\fR, \fB\-\-user\fR \fIuser\fR +The next expression is a username. +.TP +\fB\-p\fR, \fB\-\-pid\fR \fIpid\fR +The next expression is a process ID number. +.TP +\fB\-c\fR, \fB\-\-command\fR \fIcommand\fR +The next expression is a command name. +.TP +\fB\-\-ns \fIpid\fR +Match the processes that belong to the same namespace as pid. +.TP +\fB\-\-nslist \fIns\/\fR,\,\fI...\/\fR +list which namespaces will be considered for the \fB\-\-ns\fP option. +Available namespaces: ipc, mnt, net, pid, user, uts. +.PD +.SH SIGNALS +The behavior of signals is explained in +.BR signal (7) +manual page. +.SH EXAMPLES +.TP +.B snice \-c seti \-c crack +7 ++Slow down \fBseti\fP and \fBcrack\fP commands. +.TP +.B skill \-KILL \-t /dev/pts/* +Kill users on PTY devices. +.TP +.B skill \-STOP \-u viro \-u lm \-u davem +Stop three users. +.SH "SEE ALSO" +.BR kill (1), +.BR kill (2), +.BR killall (1), +.BR nice (1), +.BR pkill (1), +.BR renice (1), +.BR signal (7) +.SH STANDARDS +No standards apply. +.SH AUTHOR +.MT albert@users.sf.net +Albert Cahalan +.ME +wrote skill and snice in 1999 as a replacement for a non-free +version. +.SH "REPORTING BUGS" +Please send bug reports to +.UR procps@freelists.org +.UE diff --git a/man/slabtop.1 b/man/slabtop.1 new file mode 100644 index 0000000..0734348 --- /dev/null +++ b/man/slabtop.1 @@ -0,0 +1,123 @@ +.\" +.\" Copyright (c) 2011-2023 Craig Small <csmall@dropbear.xyz> +.\" Copyright (c) 2013-2023 Jim Warner <james.warner@comcast.net> +.\" Copyright (c) 2011-2012 Sami Kerola <kerolasa@iki.fi> +.\" Copyright (c) 2004-2006 Albert Cahalan +.\" Copyright (C) 2003 Chris Rivera +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU Lesser General Public License as +.\" published by the Free Software Foundation; either version 2.1 of the +.\" License, or (at your option) any later version. +.\" +.\" +.TH SLABTOP "1" "2021-03-11" "procps-ng" "User Commands" +.SH NAME +slabtop \- display kernel slab cache information in real time +.SH SYNOPSIS +.B slabtop +[\fIoptions\fR] +.SH DESCRIPTION +.B slabtop +displays detailed kernel slab cache information in real time. It displays a +listing of the top caches sorted by one of the listed sort criteria. It also +displays a statistics header filled with slab layer information. +.SH OPTIONS +Normal invocation of +.B slabtop +does not require any options. The behavior, however, can be fine-tuned by +specifying one or more of the following flags: +.TP +\fB\-d\fR, \fB\-\-delay\fR=\fIN\fR +Refresh the display every +.I n +in seconds. By default, +.B slabtop +refreshes the display every three seconds. To exit the program, hit +.BR q . +This cannot be combined with the \fB-o\fR option. +.TP +\fB\-s\fR, \fB\-\-sort\fR=\fIS\fR +Sort by \fIS\fR, where \fIS\fR is one of the sort criteria. +.TP +\fB\-o\fR, \fB\-\-once\fR +Display the output once and then exit. +.TP +\fB\-V\fR, \fB\-\-version\fR +Display version information and exit. +.TP +\fB\-h\fR, \fB\-\-help\fR +Display usage information and exit. +.SH SORT CRITERIA +The following are valid sort criteria used to sort the individual slab caches +and thereby determine what are the "top" slab caches to display. The default +sort criteria is to sort by the number of objects ("o"). +.PP +The sort criteria can also be changed while +.B slabtop +is running by pressing the associated character. +.TS +l l l. +\fBcharacter description header\fR +a number of active objects ACTIVE +b objects per slab OBJ/SLAB +c cache size CACHE SIZE +l number of slabs SLABS +v number of active slabs N/A +n name NAME\: +o number of objects OBJS +p pages per slab N/A +s object size OBJ SIZE +u cache utilization USE +.TE +.SH COMMANDS +.B slabtop +accepts keyboard commands from the user during use. The following are +supported. In the case of letters, both cases are accepted. +.PP +Each of the valid sort characters are also accepted, to change the sort +routine. See the section +.BR "SORT CRITERIA" . +.TP +.BR <SPACEBAR> +Refresh the screen. +.TP +.BR Q +Quit the program. +.SH FILES +.TP +.I /proc/slabinfo +slab information +.SH "SEE ALSO" +.BR free (1), +.BR ps (1), +.BR top (1), +.BR vmstat (8) +.SH NOTES +Currently, +.B slabtop +requires a 2.4 or later kernel (specifically, a version 1.1 or later +.IR /proc/slabinfo ). +Kernel 2.2 should be supported in the future. +.PP +The +.B slabtop +statistic header is tracking how many bytes of slabs are being +used and is not a measure of physical memory. The 'Slab' field in the +\fI/proc/meminfo\fR file is tracking information about used slab physical memory. +.PP +The +.B CACHE SIZE +column is not accurate, it's the upper limit of memory used by specific slab. When system +using slub (most common case) is under high memory pressure, there are slab order +fallbacks, which means "pages per slab" is not constant and may decrease. +.SH AUTHORS +Written by Chris Rivera and Robert Love. +.PP +.B slabtop +was inspired by Martin Bligh's perl script, +.BR vmtop . +.SH "REPORTING BUGS" +Please send bug reports to +.UR procps@freelists.org +.UE diff --git a/man/snice.1 b/man/snice.1 new file mode 100644 index 0000000..1595a80 --- /dev/null +++ b/man/snice.1 @@ -0,0 +1 @@ +.so man1/skill.1 diff --git a/man/sysctl.8 b/man/sysctl.8 new file mode 100644 index 0000000..fe555bd --- /dev/null +++ b/man/sysctl.8 @@ -0,0 +1,196 @@ +.\" +.\" Copyright (c) 2011-2023 Craig Small <csmall@dropbear.xyz> +.\" Copyright (c) 2013-2023 Jim Warner <james.warner@comcast.net> +.\" Copyright (c) 2011-2012 Sami Kerola <kerolasa@iki.fi> +.\" Copyright (c) 2004-2006 Albert Cahalan +.\" Copyright (c) 1999 George Staikos <staikos@0wned.org> +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" +.TH SYSCTL "8" "2023-08-19" "procps-ng" "System Administration" +.SH NAME +sysctl \- configure kernel parameters at runtime +.SH SYNOPSIS +.B sysctl +[\fIoptions\fR] [\fIvariable\fR[\fB=\fIvalue\fR]] [...] +.br +.B sysctl \-p +[\fIfile\fR or \fIregexp\fR] [...] +.SH DESCRIPTION +.B sysctl +is used to modify kernel parameters at runtime. The parameters available +are those listed under \fI/proc/sys/\fR. Procfs is required for +.B sysctl +support in Linux. You can use +.B sysctl +to both read and write sysctl data. +.SH PARAMETERS +.TP +.I variable +The name of a key to read from. An example is kernel.ostype. The '/' +separator is also accepted in place of a '.'. +.TP +.IR variable = value +To set a key, use the form +.IR variable = value +where +.I variable +is the key and +.I value +is the value to set it to. If the value contains quotes or characters +which are parsed by the shell, you may need to enclose the value in double +quotes. +.TP +\fB\-n\fR, \fB\-\-values\fR +Use this option to disable printing of the key name when printing values. +.TP +\fB\-e\fR, \fB\-\-ignore\fR +Use this option to ignore errors about unknown keys. +.TP +\fB\-N\fR, \fB\-\-names\fR +Use this option to only print the names. It may be useful with shells that +have programmable completion. +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Use this option to not display the values set to stdout. +.TP +\fB\-w\fR, \fB\-\-write\fR +Force all arguments to be write arguments and print an error if +they cannot be parsed this way. +.TP +\fB\-p\fR[\fIFILE\fR], \fB\-\-load\fR[=\fIFILE\fR] +Load in \fBsysctl\fR settings from the file specified or \fI/etc/sysctl.conf\fR +if none given. Specifying \- as filename means reading data from standard +input. Using this option will mean arguments to +.B sysctl +are files, which are read in the order they are specified. +The file argument may be specified as regular expression. +.TP +\fB\-a\fR, \fB\-\-all\fR +Display all values currently available. +.TP +\fB\-\-deprecated\fR +Include deprecated parameters to +.B \-\-all +values listing. +.TP +\fB\-b\fR, \fB\-\-binary\fR +Print value without new line. +.TP +\fB\-\-system\fR +Load settings from all system configuration files. See the +.B SYSTEM FILE PRECEDENCE +section below. +.TP +\fB\-r\fR, \fB\-\-pattern\fR \fIpattern\fR +Only apply settings that match +.IR pattern . +The +.I pattern +uses extended regular expression syntax. +.TP +\fB\-A\fR +Alias of \fB\-a\fR +.TP +\fB\-d\fR +Alias of \fB\-h\fR +.TP +\fB\-f\fR +Alias of \fB\-p\fR +.TP +\fB\-X\fR +Alias of \fB\-a\fR +.TP +\fB\-o\fR +Does nothing, exists for BSD compatibility. +.TP +\fB\-x\fR +Does nothing, exists for BSD compatibility. +.TP +\fB\-h\fR, \fB\-\-help\fR +Display help text and exit. +.TP +\fB\-V\fR, \fB\-\-version\fR +Display version information and exit. +.SH SYSTEM FILE PRECEDENCE +When using the \fB\-\-system\fR option, +.B sysctl +will read files from directories in the following list in given +order from top to bottom. Once a file of a given filename is loaded, any +file of the same name in subsequent directories is ignored. + +/etc/sysctl.d/*.conf +.br +/run/sysctl.d/*.conf +.br +/usr/local/lib/sysctl.d/*.conf +.br +/usr/lib/sysctl.d/*.conf +.br +/lib/sysctl.d/*.conf +.br +/etc/sysctl.conf + +All configuration files are sorted in lexicographic order, regardless of the +directory they reside in. Configuration files can either be completely +replaced (by having a new configuration file with the same name in a +directory of higher priority) or partially replaced (by having a configuration +file that is ordered later). +.SH EXAMPLES +/sbin/sysctl \-a +.br +/sbin/sysctl \-n kernel.hostname +.br +/sbin/sysctl \-w kernel.domainname="example.com" +.br +/sbin/sysctl \-p/etc/sysctl.conf +.br +/sbin/sysctl \-a \-\-pattern forward +.br +/sbin/sysctl \-a \-\-pattern forward$ +.br +/sbin/sysctl \-a \-\-pattern 'net.ipv4.conf.(eth|wlan)0.arp' +.br +/sbin/sysctl \-\-pattern '\[char94]net.ipv6' \-\-system +.SH DEPRECATED PARAMETERS +The +.B base_reachable_time +and +.B retrans_time +are deprecated. The +.B sysctl +command does not allow changing values of these +parameters. Users who insist to use deprecated kernel interfaces should push values +to \fB/proc\fR file system by other means. For example: +.PP +echo 256 > /proc/sys/net/ipv6/neigh/eth0/base_reachable_time +.SH FILES +.I /proc/sys +.br +.I /etc/sysctl.d/*.conf +.br +.I /run/sysctl.d/*.conf +.br +.I /usr/local/lib/sysctl.d/*.conf +.br +.I /usr/lib/sysctl.d/*.conf +.br +.I /lib/sysctl.d/*.conf +.br +.I /etc/sysctl.conf +.SH SEE ALSO +.BR proc (5), +.BR sysctl.conf (5), +.BR regex (7) +.SH AUTHOR +.UR staikos@0wned.org +George Staikos +.UE +.SH "REPORTING BUGS" +Please send bug reports to +.UR procps@freelists.org +.UE diff --git a/man/sysctl.conf.5 b/man/sysctl.conf.5 new file mode 100644 index 0000000..b64cb3b --- /dev/null +++ b/man/sysctl.conf.5 @@ -0,0 +1,92 @@ +.\" +.\" Copyright (c) 2016-2023 Jim Warner <james.warner@comcast.net> +.\" Copyright (c) 2019-2023 Craig Small <csmall@dropbear.xyz> +.\" Copyright (c) 2011-2012 Sami Kerola <kerolasa@iki.fi> +.\" Copyright (c) 1999 George Staikos <staikos@0wned.org> +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" +.TH SYSCTL.CONF "5" "2021-09-15" "procps-ng" "File Formats" +.SH NAME +sysctl.conf \- sysctl preload/configuration file +.SH DESCRIPTION +.B sysctl.conf +is a simple file containing sysctl values to be read in and set by +.BR sysctl . +The syntax is simply as follows: +.RS +.sp +.nf +.ne 7 +# comment +; comment + +token = value +.fi +.RE +.PP +Note that blank lines are ignored, and whitespace before and after a token or +value is ignored, although a value can contain whitespace within. Lines which +begin with a \fI#\fR or \fI;\fR are considered comments and ignored. + +If a line begins with a single \-, any attempts to set the value that fail will be +ignored. + +.SH NOTES +As the +.BR /etc/sysctl.conf +file is used to override default kernel parameter values, only a small number of parameters is predefined in the file. +Use +.IR /sbin/sysctl\ \-a +or follow +.BR sysctl (8) +to list all possible parameters. The description of individual parameters can be found in the kernel documentation. + +Maximum supported line length of the value is 4096 characters due +to a limitation of \fI/proc\fR entries in Linux kernel. +.SH EXAMPLE +.RS +.sp +.nf +.ne 7 +# sysctl.conf sample +# + kernel.domainname = example.com +; this one has a space which will be written to the sysctl! + kernel.modprobe = /sbin/mod probe +.fi +.RE +.PP +.SH FILES +.I /etc/sysctl.d/*.conf +.br +.I /run/sysctl.d/*.conf +.br +.I /usr/local/lib/sysctl.d/*.conf +.br +.I /usr/lib/sysctl.d/*.conf +.br +.I /lib/sysctl.d/*.conf +.br +.I /etc/sysctl.conf + +The paths where +.B sysctl +preload files usually exist. See also +.B sysctl +option +.IR \-\-system . +.SH SEE ALSO +.BR sysctl (8) +.SH AUTHOR +.UR staikos@0wned.org +George Staikos +.UE +.SH "REPORTING BUGS" +Please send bug reports to +.UR procps@freelists.org +.UE diff --git a/man/tload.1 b/man/tload.1 new file mode 100644 index 0000000..c2a12f5 --- /dev/null +++ b/man/tload.1 @@ -0,0 +1,69 @@ +.\" +.\" Copyright (c) 2011-2023 Craig Small <csmall@dropbear.xyz> +.\" Copyright (c) 2011-2012 Sami Kerola <kerolasa@iki.fi> +.\" Copyright (c) 1993 Matt Welsh <mdw@tc.cornell.edu> +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" +.TH TLOAD "1" "2020-06-04" "procps-ng" "User Commands" +.SH NAME +tload \- graphic representation of system load average +.SH SYNOPSIS +.B tload +[\fIoptions\fR] [\fItty\fR] +.SH DESCRIPTION +.B tload +prints a graph of the current system load average to the specified +.I tty +(or the tty of the +.B tload +process if none is specified). +.SH OPTIONS +.TP +\fB\-s\fR, \fB\-\-scale\fR \fInumber\fR +The scale option allows a vertical scale to be specified for the display (in +characters between graph ticks); thus, a smaller value represents a larger +scale, and vice versa. +.TP +\fB\-d\fR, \fB\-\-delay\fR \fIseconds\fR +The delay sets the delay between graph updates in +.IR seconds . +.TP +\fB\-h\fR, \fB\-\-help\fR +Display this help text. +.TP +\fB\-V\fR, \fB\-\-version\fR +Display version information and exit. +.PP +.SH FILES +.I /proc/loadavg +load average information +.SH "SEE ALSO" +.BR ps (1), +.BR top (1), +.BR uptime (1), +.BR w (1) +.SH BUGS +The +.BI "\-d" " delay" +option sets the time argument for an +.BR alarm (2); +if \-d 0 is specified, the alarm is set to 0, which will never send the +.B SIGALRM +and update the display. +.SH AUTHORS +Branko Lankester, +.UR david@\:ods.\:com +David Engel +.UE , and +.UR johnsonm@\:redhat.\:com +Michael K. Johnson +.UE . +.SH "REPORTING BUGS" +Please send bug reports to +.UR procps@freelists.org +.UE diff --git a/man/top.1 b/man/top.1 new file mode 100644 index 0000000..3791dfe --- /dev/null +++ b/man/top.1 @@ -0,0 +1,2810 @@ +.ig +. manual page for NEW and IMPROVED linux top +. +. Copyright (c) 2002-2023 Jim Warner <james.warner@comcast.net +. +. This file may be copied under the terms of the GNU Public License. +.. +\# Setup //////////////////////////////////////////////////////////////// +\# Commonly used strings (for consistency) ---------- +\# - our em-dashes +.ds Em \fR\ \-\-\ \fR +.ds EM \fB\ \-\-\ \fR +\# - our program name (makes great grammar) +.ds We top +.ds WE \fBtop\fR +\# - other misc strs for consistent usage +.ds F \fIOff\fR +.ds O \fIOn\fR +. +.ds AK asterisk (`*') +.ds AM alternate\-display mode +.ds AS auxiliary storage +.ds CF configuration file +.ds CG `current' window/field group +.ds CI interactive command +.ds CO command\-line option +.ds CT command toggle +.ds CW `current' window +.ds FG field group +.ds FM full\-screen mode +.ds KA arrow key +.ds KS scrolling key +.ds MP physical memory +.ds MS swap file +.ds MV virtual memory +.ds NT \fBNote\fR: +.ds PU CPU +.ds Pu cpu +.ds SA summary area +.ds TA task area +.ds TD task display +.ds TT \fBprocesses\fR or \fBthreads\fR +.ds TW task window +\# Reference to the various widths/sizes ------------ +\# - the max screen width limit +.ds WX 512 +\# - the header width w/ all fields +.ds WF approximately 250 +\# - pid monitoring limit +\# Xref's that depend on/mention other stuff -------- +.ds Xa see +.ds XC See the +.ds Xc see the +.ds XT See topic +.ds Xt see topic +.ds XX See `OVERVIEW, Linux Memory Types' for additional details +.ds ZX Accessing smaps values is 10x more costly than other \ +memory statistics and data for other users requires root privileges +. +.\" Document ///////////////////////////////////////////////////////////// +.\" ---------------------------------------------------------------------- +.TH TOP 1 "August 2023" "procps-ng" "User Commands" +.\" ---------------------------------------------------------------------- +.nh + +.\" ---------------------------------------------------------------------- +.SH NAME +.\" ---------------------------------------------------------------------- +top \- display Linux processes + +.\" ---------------------------------------------------------------------- +.SH SYNOPSIS +.\" ---------------------------------------------------------------------- +\*(WE [options] + +.\" ---------------------------------------------------------------------- +.SH DESCRIPTION +.\" ---------------------------------------------------------------------- +The \*(WE program provides a dynamic real-time view of a running system. +It can display\fB system\fR summary information as well as a list of +\*(TT currently being managed by the Linux kernel. +The types of system summary information shown and the types, order and +size of information displayed for processes are all user configurable +and that configuration can be made persistent across restarts. + +The program provides a limited interactive interface for process +manipulation as well as a much more extensive interface for personal +configuration \*(Em encompassing every aspect of its operation. +And while \*(WE is referred to throughout this document, you are free +to name the program anything you wish. +That new name, possibly an alias, will then be reflected on \*(We's +display and used when reading and writing a \*(CF. + +.\" ---------------------------------------------------------------------- +.SH OVERVIEW +.\" ---------------------------------------------------------------------- +.\" ...................................................................... +.SS Documentation +.\" ---------------------------------------------------------------------- +The remaining Table of Contents + +.nf + OVERVIEW + Operation + Linux Memory Types + 1. COMMAND\-LINE Options + 2. SUMMARY Display + a. UPTIME and LOAD Averages + b. TASK and CPU States + c. MEMORY Usage + 3. FIELDS / Columns Display + a. DESCRIPTIONS of Fields + b. MANAGING Fields + 4. INTERACTIVE Commands + a. GLOBAL Commands + b. SUMMARY AREA Commands + c. TASK AREA Commands + 1. Appearance + 2. Content + 3. Size + 4. Sorting + d. COLOR Mapping + 5. ALTERNATE\-DISPLAY Provisions + a. WINDOWS Overview + b. COMMANDS for Windows + c. SCROLLING a Window + d. SEARCHING in a Window + e. FILTERING in a Window + 6. FILES + a. PERSONAL Configuration File + b. ADDING INSPECT Entries + c. SYSTEM Configuration File + d. SYSTEM Restrictions File + 7. ENVIRONMENT VARIABLE(S) + 8. STUPID TRICKS Sampler + a. Kernel Magic + b. Bouncing Windows + c. The Big Bird Window + d. The Ol' Switcheroo + 9. BUGS, 10. SEE Also +.fi + +.\" ...................................................................... +.SS Operation +.\" ---------------------------------------------------------------------- +When operating \*(We, the two most important keys are the help (h or ?) +key and quit (`q') key. +Alternatively, you could simply use the traditional interrupt key (^C) +when you're done. + +When started for the first time, you'll be presented with these traditional +elements on the main \*(We screen: 1) Summary Area; 2) Fields/Columns Header; +3) Task Area. +Each of these will be explored in the sections that follow. +There is also an Input/Message line between the Summary Area and Columns +Header which needs no further explanation. + +The main \*(We screen is \fIgenerally\fR quite adaptive to changes in +terminal dimensions under X-Windows. +Other \*(We screens may be less so, especially those with static text. +It ultimately depends, however, on your particular window manager and +terminal emulator. +There may be occasions when their view of terminal size and current contents +differs from \*(We's view, which is always based on operating system calls. + +Following any re-size operation, if a \*(We screen is corrupted, appears +incomplete or disordered, simply typing something innocuous like a +punctuation character or cursor motion key will usually restore it. +In extreme cases, the following sequence almost certainly will: +.nf + \fIkey/cmd objective \fR + ^Z \fBsuspend\fR \*(We + fg \fBresume\fR \*(We + <Left> force a screen \fBredraw\fR (if necessary) +.fi + +But if the display is still corrupted, there is one more step you could try. +Insert this command after \*(We has been suspended but before resuming it. +.nf + \fIkey/cmd objective \fR + reset restore your \fBterminal settings\fR +.fi + +\*(NT the width of \*(We's display will be limited to \*(WX positions. +Displaying all fields requires \*(WF characters. +Remaining screen width is usually allocated to any variable width columns +currently visible. +The variable width columns, such as COMMAND, are noted in topic +3a. DESCRIPTIONS of Fields. +Actual output width may also be influenced by the \-w switch, which is +discussed in topic 1. COMMAND\-LINE Options. + +Lastly, some of \*(We's screens or functions require the use of cursor +motion keys like the standard \*(KAs plus the Home, End, PgUp and PgDn keys. +If your terminal or emulator does not provide those keys, the following +combinations are accepted as alternatives: +.nf + \fI key equivalent-keys \fR + Left alt +\fB h \fR + Down alt +\fB j \fR + Up alt +\fB k \fR + Right alt +\fB l \fR + Home alt + ctrl +\fB h \fR + PgDn alt + ctrl +\fB j \fR + PgUp alt + ctrl +\fB k \fR + End alt + ctrl +\fB l \fR +.fi + +The \fBUp\fR and \fBDown\fR \*(KAs have special significance when prompted +for line input terminated with the <Enter> key. +Those keys, or their aliases, can be used to retrieve previous input lines +which can then be edited and re-input. +And there are four additional keys available with line oriented input. +.nf + \fI key special-significance \fR + Up recall \fBolder\fR strings for re-editing + Down recall \fBnewer\fR strings or \fBerase\fR entire line + Insert toggle between \fBinsert\fR and \fBovertype\fR modes + Delete character \fBremoved\fR at cursor, moving others left + Home jump to \fBbeginning\fR of input line + End jump to \fBend\fR of input line +.fi + +.\" ...................................................................... +.SS Linux Memory Types +.\" ---------------------------------------------------------------------- +For our purposes there are three types of memory, and one is optional. +First is \*(MP, a limited resource where code and data must +reside when executed or referenced. +Next is the optional \*(MS, where modified (dirty) memory can be saved +and later retrieved if too many demands are made on \*(MP. +Lastly we have \*(MV, a nearly unlimited resource serving the +following goals: + +.nf + 1. abstraction, free from physical memory addresses/limits + 2. isolation, every process in a separate address space + 3. sharing, a single mapping can serve multiple needs + 4. flexibility, assign a virtual address to a file +.fi + +Regardless of which of these forms memory may take, all are managed as +pages (typically 4096 bytes) but expressed by default in \*(We as +KiB (kibibyte). +The memory discussed under topic `2c. MEMORY Usage' deals with \*(MP +and the \*(MS for the system as a whole. +The memory reviewed in topic `3. FIELDS / Columns Display' +embraces all three memory types, but for individual processes. + +For each such process, every memory page is restricted to a single +quadrant from the table below. +Both \*(MP and \*(MV can include any of the four, while the \*(MS only +includes #1 through #3. +The memory in quadrant #4, when modified, acts as its own dedicated \*(MS. + +.nf + \fBPrivate\fR | \fBShared\fR + \fB1\fR | \fB2\fR + \fBAnonymous\fR . stack | + . malloc() | + . brk()/sbrk() | . POSIX shm* + . mmap(PRIVATE, ANON) | . mmap(SHARED, ANON) + -----------------------+---------------------- + . mmap(PRIVATE, fd) | . mmap(SHARED, fd) + \fBFile-backed\fR . pgms/shared libs | + \fB3\fR | \fB4\fR +.fi + +The following may help in interpreting process level memory values displayed +as scalable columns and discussed under topic `3a. DESCRIPTIONS of Fields'. + +.nf + %MEM \- simply RES divided by total \*(MP + CODE \- the `pgms' portion of quadrant \fB3\fR + DATA \- the entire quadrant \fB1\fR portion of VIRT plus all + explicit mmap file-backed pages of quadrant \fB3\fR + RES \- anything occupying \*(MP which, beginning with + Linux-4.5, is the sum of the following three fields: + RSan \- quadrant \fB1\fR pages, which include any + former quadrant \fB3\fR pages if modified + RSfd \- quadrant \fB3\fR and quadrant \fB4\fR pages + RSsh \- quadrant \fB2\fR pages + RSlk \- subset of RES which cannot be swapped out (any quadrant) + SHR \- subset of RES (excludes \fB1\fR, includes all \fB2\fR & \fB4\fR, some \fB3\fR) + SWAP \- potentially any quadrant except \fB4\fR + USED \- simply the sum of RES and SWAP + VIRT \- everything in-use and/or reserved (all quadrants) +.fi + +\*(NT Even though program images and shared libraries are considered +\fIprivate\fR to a process, they will be accounted for as \fIshared\fR +(SHR) by the kernel. + +.\" ---------------------------------------------------------------------- +.SH 1. COMMAND-LINE Options +.\" ---------------------------------------------------------------------- +Mandatory\fI arguments\fR to long options are mandatory for short +options too. + +Although not required, the equals sign can be used with either option +form and whitespace before and/or after the `=' is permitted. + +.TP 3 +\-\fBb\fR, \fB\-\-batch\fR +Starts \*(We in Batch mode, which could be useful for sending output +from \*(We to other programs or to a file. +In this mode, \*(We will not accept input and runs until the iterations +limit you've set with the `\-n' \*(CO or until killed. + +.TP 3 +\-\fBc\fR, \fB\-\-cmdline\-toggle\fR +Starts \*(We with the last remembered `c' state reversed. +Thus, if \*(We was displaying command lines, now that field will show program +names, and vice versa. +\*(XC `c' \*(CI for additional information. + +.TP 3 +\-\fBd\fR, \fB\-\-delay\fR = \fISECS\fR [\fI.TENTHS\fR]\fR +Specifies the delay between screen updates, and overrides the corresponding +value in one's personal \*(CF or the startup default. +Later this can be changed with the `d' or `s' \*(CIs. + +Fractional seconds are honored, but a negative number is not allowed. +In all cases, however, such changes are prohibited if \*(We is running +in Secure mode, except for root (unless the `s' \*(CO was used). +For additional information on Secure mode \*(Xt 6d. SYSTEM Restrictions File. + +.TP 3 +\-\fBE\fR, \fB\-\-scale-summary-mem\fR = \fIk\fR | \fIm\fR | \fIg\fR | \fIt\fR | \fIp\fR | \fIe\fR +Instructs \*(We to force \*(SA memory to be scaled as: +.nf + k \- kibibytes + m \- mebibytes + g \- gibibytes + t \- tebibytes + p \- pebibytes + e \- exbibytes +.fi + +Later this can be changed with the `E' \*(CT. + +.TP 3 +\-\fBe\fR, \fB\-\-scale-task-mem\fR = \fIk\fR | \fIm\fR | \fIg\fR | \fIt\fR | \fIp\fR +Instructs \*(We to force \*(TA memory to be scaled as: +.nf + k \- kibibytes + m \- mebibytes + g \- gibibytes + t \- tebibytes + p \- pebibytes +.fi + +Later this can be changed with the `e' \*(CT. + +.TP 3 +\-\fBH\fR, \fB\-\-threads-show\fR +Instructs \*(We to display individual threads. +Without this \*(CO a summation of all threads in each process is shown. +Later this can be changed with the `H' \*(CI. + +.TP 3 +\-\fBh\fR, \fB\-\-help\fR +Display usage help text, then quit. + +.TP 3 +\-\fBi\fR, \fB\-\-idle-toggle\fR +Starts \*(We with the last remembered `i' state reversed. +When this toggle is \*F, tasks that have not used any \*(PU since the +last update will not be displayed. +For additional information regarding this toggle +\*(Xt 4c. TASK AREA Commands, SIZE. + +.TP 3 +\-\fBn\fR, \fB\-\-iterations\fR = \fINUMBER\fR +Specifies the maximum number of iterations, or frames, \*(We should +produce before ending. + +.TP 3 +\-\fBO\fR, \fB\-\-list-fields\fR +This option acts as a form of help for the \-o option shown below. +It will cause \*(We to print each of the available field names on a +separate line, then quit. +Such names are subject to NLS (National Language Support) translation. + +.TP 3 +\-\fBo\fR, \fB\-\-sort-override\fR = \fIFIELDNAME\fR +Specifies the name of the field on which tasks will be sorted, independent +of what is reflected in the configuration file. +You can prepend a `+' or `\-' to the field name to also override the sort +direction. +A leading `+' will force sorting high to low, whereas a `\-' will ensure +a low to high ordering. + +This option exists primarily to support automated/scripted batch mode +operation. + +.TP 3 +\-\fBp\fR, \fB\-\-pid\fR = \fIPIDLIST\fR \ +(as: \fI1\fR,\fI2\fR,\fI3\fR, ...\fR or \fR-p\fI1\fR -p\fI2\fR -p\fI3\fR ...) +Monitor only processes with specified process IDs. +However, when combined with Threads mode (`H'), all processes in the +thread group (\*(Xa TGID) of each monitored PID will also be shown. + +This option can be given up to 20 times, or you can provide a comma delimited +list with up to 20 pids. +Co-mingling both approaches is permitted. + +A pid value of zero will be treated as the process id of the \*(We program +itself once it is running. + +This is a \*(CO only and should you wish to return to normal operation, +it is not necessary to quit and restart \*(We \*(Em just issue any +of these \*(CIs: `=', `u' or `U'. + +The `p', `u' and `U' \*(COs are mutually exclusive. + +.TP 3 +\-\fBS\fR, \fB\-\-accum-time-toggle\fR +Starts \*(We with the last remembered `S' state reversed. +When Cumulative time mode is \*O, each process is listed with the \*(Pu +time that it and its dead children have used. +\*(XC `S' \*(CI for additional information regarding this mode. + +.TP 3 +\-\fBs\fR, \fB\-\-secure-mode\fR +Starts \*(We with secure mode forced, even for root. +This mode is far better controlled through a system \*(CF +(\*(Xt 6. FILES). + +.TP 3 +\-\fBU\fR, \fB\-\-filter-any-user\fR = \fIUSER\fR (as: \fInumber\fR or \fIname\fR) +Display only processes with a user id or user name matching that given. +This option matches on\fI any\fR user (\fIreal\fR, \fIeffective\fR, +\fIsaved\fR, or \fIfilesystem\fR). + +Prepending an exclamation point (`!') to the user id or name instructs \*(We +to display only processes with users not matching the one provided. + +The `p', `U' and `u' \*(COs are mutually exclusive. + +.TP 3 +\-\fBu\fR, \fB\-\-filter-only-euser\fR = \fIUSER\fR (as: \fInumber\fR or \fIname\fR) +Display only processes with a user id or user name matching that given. +This option matches on the\fI effective\fR user id only. + +Prepending an exclamation point (`!') to the user id or name instructs \*(We +to display only processes with users not matching the one provided. + +The `p', `U' and `u' \*(COs are mutually exclusive. + +.TP 3 +\-\fBV\fR, \fB\-\-version\fR +Display version information, then quit. + +.TP 3 +\-\fBw\fR, \fB\-\-width\fR [=\fICOLUMNS\fR] +In Batch mode, when used without an argument \*(We will format +output using the COLUMNS= and LINES= environment variables, if set. +Otherwise, width will be fixed at the maximum \*(WX columns. +With an argument, output width can be decreased or increased (up to \*(WX) +but the number of rows is considered unlimited. + +In normal display mode, when used without an argument \*(We will\fI attempt\fR +to format output using the COLUMNS= and LINES= environment variables, if set. +With an argument, output width can only be decreased, not increased. +Whether using environment variables or an argument with \-w, when\fI not\fR +in Batch mode actual terminal dimensions can never be exceeded. + +\*(NT Without the use of this \*(CO, output width is always based on the +terminal at which \*(We was invoked whether or not in Batch mode. + +.TP 3 +\-\fB1\fR, \fB\-\-single-cpu-toggle\fR +Starts \*(We with the last remembered Cpu States portion of the \*(SA reversed. +Either all \*(Pu information will be displayed in a single line or +each \*(Pu will be displayed separately, depending on the state of the NUMA Node +\*(CT (`2'). + +\*(XC `1' and `2' \*(CIs for additional information. + +.\" ---------------------------------------------------------------------- +.SH 2. SUMMARY Display +.\" ---------------------------------------------------------------------- +Each of the following three areas are individually controlled through +one or more \*(CIs. +\*(XT 4b. SUMMARY AREA Commands for additional information regarding +these provisions. + +.\" ...................................................................... +.SS 2a. UPTIME and LOAD Averages +.\" ---------------------------------------------------------------------- +This portion consists of a single line containing: +.nf + \fBprogram\fR or\fB window\fR name, depending on display mode + current time and length of time since last boot + total number of users + system load avg over the last 1, 5 and 15 minutes +.fi + +.\" ...................................................................... +.SS 2b. TASK and CPU States +.\" ---------------------------------------------------------------------- +This portion consists of a minimum of two lines. +In an SMP environment, additional lines can reflect individual \*(PU +state percentages. + +Line 1 shows total\fB tasks\fR or\fB threads\fR, depending on the state +of the Threads-mode toggle. +That total is further classified as: +.nf + running; sleeping; stopped; zombie +.fi + +Line 2 shows \*(PU state percentages based on the interval since the +last refresh. + +As a default, percentages for these individual categories are displayed. +Depending on your kernel version, the \fBst\fR field may not be shown. +.nf + \fBus\fR : time running un-niced user processes + \fBsy\fR : time running kernel processes + \fBni\fR : time running niced user processes + \fBid\fR : time spent in the kernel idle handler + \fBwa\fR : time waiting for I/O completion + \fBhi\fR : time spent servicing hardware interrupts + \fBsi\fR : time spent servicing software interrupts + \fBst\fR : time stolen from this vm by the hypervisor +.fi + +The `sy' value above also reflects the time running a virtual \*(Pu +for guest operating systems, including those that have been niced. + +Beyond the first tasks/threads line, there are alternate \*(PU display +modes available via the 4-way `t' \*(CT. +They show an abbreviated summary consisting of these elements: +.nf + \fR a \fR b \fR c \fR d + %Cpu(s): \fB75.0\fR/25.0 \fB100\fR[ ... ] + +.fi + +Where: a) is the `user' (us + ni) percentage; b) is the `system' +(sy + hi + si + guests) percentage; c) is the total percentage; +and d) is one of two visual graphs of those representations. +Such graphs also reflect separate `user' and `system' portions. + +If the `4' \*(CT is used to yield more than two cpus per line, +results will be further abridged eliminating the a) and b) elements. +However, that information is still reflected in the graph itself +assuming color is active or, if not, bars vs. blocks are being shown. + +\*(XT 4b. SUMMARY AREA Commands for additional information on the `t' +and `4' \*(CTs. + +.\" ...................................................................... +.SS 2c. MEMORY Usage +.\" ---------------------------------------------------------------------- +This portion consists of two lines which may express values in kibibytes (KiB) +through exbibytes (EiB) depending on the scaling factor enforced +with the `E' \*(CI. The /proc/meminfo source fields are shown in parenthesis. + +Line 1 reflects \*(MP, classified as: +.nf + total ( MemTotal ) + free ( MemFree ) + used ( MemTotal - MemAvailable ) + buff/cache ( Buffers + Cached + SReclaimable ) +.fi + +Line 2 reflects mostly \*(MV, classified as: +.nf + total ( SwapTotal ) + free ( SwapFree ) + used ( SwapTotal - SwapFree ) + avail ( MemAvailable, which is \*(MP ) +.fi + +The \fBavail\fR number on line 2 is an estimation of \*(MP available for +starting new applications, without swapping. +Unlike the \fBfree\fR field, it attempts to account for readily reclaimable +page cache and memory slabs. +It is available on kernels 3.14, emulated on kernels 2.6.27+, otherwise +the same as \fBfree\fR. + +In the alternate memory display modes, two abbreviated summary lines +are shown consisting of these elements: +.nf + \fR a \fR b c + GiB Mem : \fB18.7\fR/15.738 [ ... ] + GiB Swap: \fB 0.0\fR/7.999 [ ... ] +.fi + +Where: a) is the percentage used; b) is the total available; and c) is one of two +visual graphs of those representations. + +In the case of \*(MP, the percentage represents the \fBtotal\fR minus the estimated +\fBavail\fR noted above. +The `Mem' graph itself is divided between the non-cached portion of \fBused\fR and +any remaining memory not otherwise accounted for by \fBavail\fR. +\*(XT 4b. SUMMARY AREA Commands and the `m' command for additional information +on that special 4-way toggle. + +This table may help in interpreting the scaled values displayed: +.nf + KiB = kibibyte = 1024 bytes + MiB = mebibyte = 1024 KiB = 1,048,576 bytes + GiB = gibibyte = 1024 MiB = 1,073,741,824 bytes + TiB = tebibyte = 1024 GiB = 1,099,511,627,776 bytes + PiB = pebibyte = 1024 TiB = 1,125,899,906,842,624 bytes + EiB = exbibyte = 1024 PiB = 1,152,921,504,606,846,976 bytes +.fi + +.\" ---------------------------------------------------------------------- +.SH 3. FIELDS / Columns +.\" ---------------------------------------------------------------------- +.\" ...................................................................... +.SS 3a. DESCRIPTIONS of Fields +.\" ---------------------------------------------------------------------- +Listed below are \*(We's available process fields (columns). +They are shown in strict ascii alphabetical order. +You may customize their position and whether or not they are displayable +with the `f' (Fields Management) \*(CI. + +Any field is selectable as the sort field, and you control whether they +are sorted high-to-low or low-to-high. +For additional information on sort provisions +\*(Xt 4c. TASK AREA Commands, SORTING. + +The fields related to \*(MP or \*(MV reference `(KiB)' which is the +unsuffixed display mode. +Such fields may, however, be scaled from KiB through PiB. +That scaling is influenced via the `e' \*(CI or established for startup +through a build option. + +.TP 4 +\fB%CPU \*(Em \*(PU Usage \fR +The task's share of the elapsed \*(PU time since the last screen update, +expressed as a percentage of total \*(PU time. + +In a true SMP environment, if a process is multi-threaded and \*(We is +\fInot\fR operating in Threads mode, amounts greater than 100% may be +reported. +You toggle Threads mode with the `H' \*(CI. + +Also for multi-processor environments, if Irix mode is \*F, \*(We +will operate in Solaris mode where a task's \*(Pu usage will be +divided by the total number of \*(PUs. +You toggle Irix/Solaris modes with the `I' \*(CI. + +\*(NT When running in forest view mode (`V') with children +collapsed (`v'), this field will also include the \*(PU time of +those unseen children. +\*(XT 4c. TASK AREA Commands, CONTENT for more information regarding +the `V' and `v' toggles. + +.TP 4 +\fB%CUC \*(Em \*(PU Utilization \fR +This field is identical to %CUU below, except the percentage also +reflects reaped child processes. + +.TP 4 +\fB%CUU \*(Em \*(PU Utilization \fR +A task's total \*(PU usage divided by its elapsed running time, +expressed as a percentage. + +If a process currently displays high \*(PU usage, this field can help +determine if such behavior is normal. +Conversely, if a process has low \*(PU usage currently, %CUU may reflect +historically higher demands over its lifetime. + +.TP 4 +\fB%MEM \*(Em Memory Usage (RES) \fR +A task's currently resident share of available \*(MP. + +\*(XX. + +.TP 4 +\fBAGID \*(Em Autogroup Identifier \fR +The autogroup identifier associated with a process. +This feature operates in conjunction with the CFS scheduler +to improve interactive desktop performance. + +When /proc/sys/kernel/sched_autogroup_enabled is set, a new +autogroup is created with each new session (\*(Xa SID). +All subsequently forked processes in that session inherit membership in +this autogroup. +The kernel then attempts to equalize distribution of CPU cycles +across such groups. +Thus, an autogroup with many \*(PU intensive processes (e.g make -j) +will not dominate an autogroup with only one or two processes. + +When -1 is displayed it means this information is not available. + +.TP 4 +\fBAGNI \*(Em Autogroup Nice Value \fR +The autogroup nice value which affects scheduling of all processes +in that group. +A negative nice value means higher priority, whereas a positive nice +value means lower priority. + +.TP 4 +\fBCGNAME \*(Em Control Group Name \fR +The name of the control group to which a process belongs, +or `\-' if not applicable for that process. + +This will typically be the last entry in the full list of control +groups as shown under the next heading (CGROUPS). +And as is true there, this field is also variable width. + +.TP 4 +\fBCGROUPS \*(Em Control Groups \fR +The names of the control group(s) to which a process belongs, +or `\-' if not applicable for that process. + +Control Groups provide for allocating resources (cpu, memory, network +bandwidth, etc.) among installation-defined groups of processes. +They enable fine-grained control over allocating, denying, prioritizing, +managing and monitoring those resources. + +Many different hierarchies of cgroups can exist simultaneously on a system +and each hierarchy is attached to one or more subsystems. +A subsystem represents a single resource. + +\*(NT The CGROUPS field, unlike most columns, is not fixed-width. +When displayed, it plus any other variable width columns will be allocated +all remaining screen width (up to the maximum \*(WX characters). +Even so, such variable width fields could still suffer truncation. +\*(XT 5c. SCROLLING a Window for additional information on accessing +any truncated data. + +.TP 4 +\fBCODE \*(Em Code Size (KiB) \fR +The amount of \*(MP currently devoted to executable code, also known +as the Text Resident Set size or TRS. + +\*(XX. + +.TP 4 +\fBCOMMAND \*(Em Command\fB Name\fR or Command\fB Line \fR +Display the command line used to start a task or the name of the associated +program. +You toggle between command\fI line\fR and\fI name\fR with `c', which is both +a \*(CO and an \*(CI. + +When you've chosen to display command lines, processes without a command +line (like kernel threads) will be shown with only the program name in +brackets, as in this example: + \fR[kthreadd] + +This field may also be impacted by the forest view display mode. +\*(XC `V' \*(CI for additional information regarding that mode. + +\*(NT The COMMAND field, unlike most columns, is not fixed-width. +When displayed, it plus any other variable width columns will be allocated +all remaining screen width (up to the maximum \*(WX characters). +Even so, such variable width fields could still suffer truncation. +This is especially true for this field when command lines are being +displayed (the `c' \*(CI.) +\*(XT 5c. SCROLLING a Window for additional information on accessing +any truncated data. + +.TP 4 +\fBDATA \*(Em Data + Stack Size (KiB) \fR +The amount of private memory \fIreserved\fR by a process. +It is also known as the Data Resident Set or DRS. +Such memory may not yet be mapped to \*(MP (RES) but will always be +included in the \*(MV (VIRT) amount. + +\*(XX. + +.TP 4 +\fBELAPSED \*(Em Elapsed Running Time\fR +The length of time since a process was started. +Thus, the most recently started task will display the smallest time interval. + +The value will be expressed as `HH,MM' (hours,minutes) but is subject to +additional scaling if the interval becomes too great to fit column width. +At that point it will be scaled to `DD+HH' (days+hours) and possibly +beyond. + +.TP 4 +\fBENVIRON \*(Em Environment variables \fR +Display all of the environment variables, if any, as seen by the +respective processes. +These variables will be displayed in their raw native order, not the +sorted order you are accustomed to seeing with an unqualified `set'. + +\*(NT The ENVIRON field, unlike most columns, is not fixed-width. +When displayed, it plus any other variable width columns will be allocated +all remaining screen width (up to the maximum \*(WX characters). +Even so, such variable width fields could still suffer truncation. +This is especially true for this field. +\*(XT 5c. SCROLLING a Window for additional information on accessing +any truncated data. + +.TP 4 +\fBEXE \*(Em Executable Path \fR +Where available, this is the full path to the executable, +including the program name. + +\*(NT The EXE field, unlike most columns, is not fixed-width. +When displayed, it plus any other variable width columns will be allocated +all remaining screen width (up to the maximum \*(WX characters). + +.TP 4 +\fBFlags \*(Em Task Flags \fR +This column represents the task's current scheduling flags which are +expressed in hexadecimal notation and with zeros suppressed. +These flags are officially documented in <linux/sched.h>. + +.TP 4 +\fBGID \*(Em Group Id \fR +The\fI effective\fR group ID. + +.TP 4 +\fBGROUP \*(Em Group Name \fR +The\fI effective\fR group name. + +.TP 4 +\fBLOGID \*(Em Login User Id \fR +The user ID used at\fI login\fR. +When -1 is displayed it means this information is not available. + +.TP 4 +\fBLXC \*(Em Lxc Container Name \fR +The name of the lxc container within which a task is running. +If a process is not running inside a container, a dash (`\-') will be shown. + +.TP 4 +\fBNI \*(Em Nice Value \fR +The nice value of the task. +A negative nice value means higher priority, whereas a positive nice value +means lower priority. +Zero in this field simply means priority will not be adjusted in determining +a task's dispatch-ability. + +\*(NT This value only affects scheduling priority relative to other processes +in the same autogroup. +\*(XC `AGID' and `AGNI' fields for additional information on autogroups. + +.TP 4 +\fBNU \*(Em Last known NUMA node \fR +A number representing the NUMA node associated with the last used processor (`P'). +When -1 is displayed it means that NUMA information is not available. + +\*(XC `2' and `3' \*(CIs for additional NUMA provisions affecting the \*(SA. + +.TP 4 +\fBOOMa \*(Em Out of Memory Adjustment Factor \fR +The value, ranging from -1000 to +1000, added to the current out of memory +score (OOMs) which is then used to determine which task to kill when memory +is exhausted. + +.TP 4 +\fBOOMs \*(Em Out of Memory Score \fR +The value, ranging from 0 to +1000, used to select task(s) to kill when memory +is exhausted. +Zero translates to `never kill' whereas 1000 means `always kill'. + +.TP 4 +\fBP \*(Em Last used \*(PU (SMP) \fR +A number representing the last used processor. +In a true SMP environment this will likely change frequently since the kernel +intentionally uses weak affinity. +Also, the very act of running \*(We may break this weak affinity and cause more +processes to change \*(PUs more often (because of the extra demand for +\*(Pu time). + +.TP 4 +\fBPGRP \*(Em Process Group Id \fR +Every process is member of a unique process group which is used for +distribution of signals and by terminals to arbitrate requests for their +input and output. +When a process is created (forked), it becomes a member of the process +group of its parent. +By convention, this value equals the process ID (\*(Xa PID) of the first +member of a process group, called the process group leader. + +.TP 4 +\fBPID \*(Em Process Id \fR +The task's unique process ID, which periodically wraps, though never +restarting at zero. +In kernel terms, it is a dispatchable entity defined by a task_struct. + +This value may also be used as: a process group ID (\*(Xa PGRP); +a session ID for the session leader (\*(Xa SID); +a thread group ID for the thread group leader (\*(Xa TGID); +and a TTY process group ID for the process group leader (\*(Xa TPGID). + +.TP 4 +\fBPPID \*(Em Parent Process Id \fR +The process ID (pid) of a task's parent. + +.TP 4 +\fBPR \*(Em Priority \fR +The scheduling priority of the task. +If you see `rt' in this field, it means the task is running +under real time scheduling priority. + +Under linux, real time priority is somewhat misleading since traditionally +the operating itself was not preemptible. +And while the 2.6 kernel can be made mostly preemptible, it is not always so. + +.TP 4 +\fBPSS \*(Em Proportional Resident Memory, smaps (KiB) \fR +The proportion of this task's share of `RSS' where each page is divided by +the number of processes sharing it. +It is also the sum of the `PSan', `PSfd' and `PSsh' fields. + +For example, if a process has 1000 resident pages alone and 1000 resident +pages shared with another process, its `PSS' would be 1500 (times page size). + +\*(ZX. + +.PP +\fBPSan \*(Em Proportional Anonymous Memory, smaps (KiB) \fR +.br +\fBPSfd \*(Em Proportional File Memory, smaps (KiB) \fR +.br +\fBPSsh \*(Em Proportional Shmem Memory, smaps (KiB) \fR +.RS 4 +As was true for `PSS' above (total proportional resident memory), +these fields represent the proportion of this task's share of each type +of memory divided by the number of processes sharing it. + +\*(ZX. +.RE + +.TP 4 +\fBRES \*(Em Resident Memory Size (KiB) \fR +A subset of the virtual address space (VIRT) representing the non-swapped +\*(MP a task is currently using. +It is also the sum of the `RSan', `RSfd' and `RSsh' fields. + +It can include private anonymous pages, private pages mapped to files +(including program images and shared libraries) plus shared anonymous pages. +All such memory is backed by the \*(MS represented separately under SWAP. + +Lastly, this field may also include shared file-backed pages which, when +modified, act as a dedicated \*(MS and thus will never impact SWAP. + +\*(XX. + +.TP 4 +\fBRSS \*(Em Resident Memory, smaps (KiB) \fR +Another, more precise view of process non-swapped \*(MP. +It is obtained from the `smaps_rollup' file and is +generally slightly larger than that shown for `RES'. + +\*(ZX. + +.TP 4 +\fBRSan \*(Em Resident Anonymous Memory Size (KiB) \fR +A subset of resident memory (RES) representing private pages not +mapped to a file. + +.TP 4 +\fBRSfd \*(Em Resident File-Backed Memory Size (KiB) \fR +A subset of resident memory (RES) representing the implicitly shared +pages supporting program images and shared libraries. +It also includes explicit file mappings, both private and shared. + +.TP 4 +\fBRSlk \*(Em Resident Locked Memory Size (KiB) \fR +A subset of resident memory (RES) which cannot be swapped out. + +.TP 4 +\fBRSsh \*(Em Resident Shared Memory Size (KiB) \fR +A subset of resident memory (RES) representing the explicitly shared +anonymous shm*/mmap pages. + +.TP 4 +\fBRUID \*(Em Real User Id \fR +The\fI real\fR user ID. + +.TP 4 +\fBRUSER \*(Em Real User Name \fR +The\fI real\fR user name. + +.TP 4 +\fBS \*(Em Process Status \fR +The status of the task which can be one of: + \fBD\fR = uninterruptible sleep + \fBI\fR = idle + \fBR\fR = running + \fBS\fR = sleeping + \fBT\fR = stopped by job control signal + \fBt\fR = stopped by debugger during trace + \fBZ\fR = zombie + +Tasks shown as running should be more properly thought of as ready to run +\*(Em their task_struct is simply represented on the Linux run-queue. +Even without a true SMP machine, you may see numerous tasks in this state +depending on \*(We's delay interval and nice value. + +.TP 4 +\fBSHR \*(Em Shared Memory Size (KiB) \fR +A subset of resident memory (RES) that may be used by other processes. +It will include shared anonymous pages and shared file-backed pages. +It also includes private pages mapped to files representing +program images and shared libraries. + +\*(XX. + +.TP 4 +\fBSID \*(Em Session Id \fR +A session is a collection of process groups (\*(Xa PGRP), +usually established by the login shell. +A newly forked process joins the session of its creator. +By convention, this value equals the process ID (\*(Xa PID) of the first +member of the session, called the session leader, which is usually the +login shell. + +.TP 4 +\fBSTARTED \*(Em Start Time Interval\fR +The length of time since system boot when a process started. +Thus, the most recently started task will display the largest time interval. + +The value will be expressed as `MM:SS' (minutes:seconds). +But if the interval is too great to fit column width it will be scaled +as `HH,MM' (hours,minutes) and possibly beyond. + +.TP 4 +\fBSUID \*(Em Saved User Id \fR +The\fI saved\fR user ID. + +.TP 4 +\fBSUPGIDS \*(Em Supplementary Group IDs \fR +The IDs of any supplementary group(s) established at login or +inherited from a task's parent. +They are displayed in a comma delimited list. + +\*(NT The SUPGIDS field, unlike most columns, is not fixed-width. +When displayed, it plus any other variable width columns will be allocated +all remaining screen width (up to the maximum \*(WX characters). + +.TP 4 +\fBSUPGRPS \*(Em Supplementary Group Names \fR +The names of any supplementary group(s) established at login or +inherited from a task's parent. +They are displayed in a comma delimited list. + +\*(NT The SUPGRPS field, unlike most columns, is not fixed-width. +When displayed, it plus any other variable width columns will be allocated +all remaining screen width (up to the maximum \*(WX characters). + +.TP 4 +\fBSUSER \*(Em Saved User Name \fR +The\fI saved\fR user name. + +.TP 4 +\fBSWAP \*(Em Swapped Size (KiB) \fR +The formerly resident portion of a task's address space written +to the \*(MS when \*(MP becomes over committed. + +\*(XX. + +.TP 4 +\fBTGID \*(Em Thread Group Id \fR +The ID of the thread group to which a task belongs. +It is the PID of the thread group leader. +In kernel terms, it represents those tasks that share an mm_struct. + +.TP 4 +\fBTIME \*(Em \*(PU Time \fR +Total \*(PU time the task has used since it started. +When Cumulative mode is \*O, each process is listed with the \*(Pu +time that it and its dead children have used. +You toggle Cumulative mode with `S', which is both a \*(CO and an \*(CI. +\*(XC `S' \*(CI for additional information regarding this mode. + +.TP 4 +\fBTIME+ \*(Em \*(PU Time, hundredths \fR +The same as TIME, but reflecting more granularity through hundredths +of a second. + +.TP 4 +\fBTPGID \*(Em Tty Process Group Id \fR +The process group ID of the foreground process for the connected tty, +or \-1 if a process is not connected to a terminal. +By convention, this value equals the process ID (\*(Xa PID) of the +process group leader (\*(Xa PGRP). + +.TP 4 +\fBTTY \*(Em Controlling Tty \fR +The name of the controlling terminal. +This is usually the device (serial port, pty, etc.) from which the +process was started, and which it uses for input or output. +However, a task need not be associated with a terminal, in which case +you'll see `?' displayed. + +.TP 4 +\fBUID \*(Em User Id \fR +The\fI effective\fR user ID of the task's owner. + +.TP 4 +\fBUSED \*(Em Memory in Use (KiB) \fR +This field represents the non-swapped \*(MP a task is using (RES) plus +the swapped out portion of its address space (SWAP). + +\*(XX. + +.TP 4 +\fBUSER \*(Em User Name \fR +The\fI effective\fR user name of the task's owner. + +.TP 4 +\fBUSS \*(Em Unique Set Size \fR +The non-swapped portion of \*(MP (`RSS') not shared with +any other process. +It is derived from the `smaps_rollup' file. + +\*(ZX. + +.TP 4 +\fBVIRT \*(Em Virtual Memory Size (KiB) \fR +The total amount of \*(MV used by the task. +It includes all code, data and shared libraries plus pages that have been +swapped out and pages that have been mapped but not used. + +\*(XX. + +.TP 4 +\fBWCHAN \*(Em Sleeping in Function \fR +This field will show the name of the kernel function in which the task +is currently sleeping. +Running tasks will display a dash (`\-') in this column. + +.TP 4 +\fBioR \*(Em I/O Bytes Read \fR +The number of bytes a process caused to be fetched from the storage layer. + +Root privileges are required to display `io' data for other users. + +.TP 4 +\fBioRop \*(Em I/O Read Operations \fR +The number of read I/O operations (syscalls) for a process. +Such calls might not result in actual physical disk I/O. + +.TP 4 +\fBioW \*(Em I/O Bytes Written \fR +The number of bytes a process caused to be sent to the storage layer. + +.TP 4 +\fBioWop \*(Em I/O Write Operations \fR +The number of write I/O operations (syscalls) for a process. +Such calls might not result in actual physical disk I/O. + +.TP 4 +\fBnDRT \*(Em Dirty Pages Count \fR +The number of pages that have been modified since they were last +written to \*(AS. +Dirty pages must be written to \*(AS before the corresponding physical +memory location can be used for some other virtual page. + +This field was deprecated with linux 2.6 and is always zero. + +.TP 4 +\fBnMaj \*(Em Major Page Fault Count \fR +The number of\fB major\fR page faults that have occurred for a task. +A page fault occurs when a process attempts to read from or write to a +virtual page that is not currently present in its address space. +A major page fault is when \*(AS access is involved in making that +page available. + +.TP 4 +\fBnMin \*(Em Minor Page Fault count \fR +The number of\fB minor\fR page faults that have occurred for a task. +A page fault occurs when a process attempts to read from or write to a +virtual page that is not currently present in its address space. +A minor page fault does not involve \*(AS access in making that +page available. + +.TP 4 +\fBnTH \*(Em Number of Threads \fR +The number of threads associated with a process. + +.TP 4 +\fBnsCGROUP \*(Em CGROUP namespace \fR +The Inode of the namespace used to hide the identity of the control group of +which process is a member. + +.TP 4 +\fBnsIPC \*(Em IPC namespace \fR +The Inode of the namespace used to isolate interprocess communication (IPC) +resources such as System V IPC objects and POSIX message queues. + +.TP 4 +\fBnsMNT \*(Em MNT namespace \fR +The Inode of the namespace used to isolate filesystem mount points thus +offering different views of the filesystem hierarchy. + +.TP 4 +\fBnsNET \*(Em NET namespace \fR +The Inode of the namespace used to isolate resources such as network devices, +IP addresses, IP routing, port numbers, etc. + +.TP 4 +\fBnsPID \*(Em PID namespace \fR +The Inode of the namespace used to isolate process ID numbers +meaning they need not remain unique. +Thus, each such namespace could have its own `init/systemd' (PID #1) to +manage various initialization tasks and reap orphaned child processes. + +.TP 4 +\fBnsTIME \*(Em TIME namespace \fR +The Inode of the namespace which allows processes to see different system +times in a way similar to the UTS namespace. + +.TP 4 +\fBnsUSER \*(Em USER namespace \fR +The Inode of the namespace used to isolate the user and group ID numbers. +Thus, a process could have a normal unprivileged user ID outside a user +namespace while having a user ID of 0, with full root privileges, inside +that namespace. + +.TP 4 +\fBnsUTS \*(Em UTS namespace \fR +The Inode of the namespace used to isolate hostname and NIS domain name. +UTS simply means "UNIX Time-sharing System". + +.TP 4 +\fBvMj \*(Em Major Page Fault Count Delta\fR +The number of\fB major\fR page faults that have occurred since the +last update (see nMaj). + +.TP 4 +\fBvMn \*(Em Minor Page Fault Count Delta\fR +The number of\fB minor\fR page faults that have occurred since the +last update (see nMin). + +.\" ...................................................................... +.SS 3b. MANAGING Fields +.\" ---------------------------------------------------------------------- +After pressing the \*(CI `f' (Fields Management) you will be presented +with a screen showing: 1) the \*(CW name; 2) the designated sort field; +3) all fields in their current order along with descriptions. +Entries marked with an asterisk are the currently displayed fields, +screen width permitting. + +.RS +4 +.IP \(bu 3 +As the on screen instructions indicate, you navigate among the fields with +the\fB Up\fR and\fB Down\fR \*(KAs. +The PgUp, PgDn, Home and End keys can also be used to quickly reach the +first or last available field. + +.IP \(bu 3 +The\fB Right\fR \*(KA selects a field for repositioning and +the\fB Left\fR \*(KA or the <\fBEnter\fR> key commits that field's +placement. + +.IP \(bu 3 +The `\fBd\fR' key or the <\fBSpace\fR> bar toggles a field's display +status, and thus the presence or absence of the asterisk. + +.IP \(bu 3 +The `\fBs\fR' key designates a field as the sort field. +\*(XT 4c. TASK AREA Commands, SORTING for additional information regarding +your selection of a sort field. + +.IP \(bu 3 +The `\fBa\fR' and `\fBw\fR' keys can be used to cycle through all available +windows and the `\fBq\fR' or <\fBEsc\fR> keys exit Fields Management. +.RS -4 + +.PP +The Fields Management screen can also be used to change the \*(CG in +either \*(FM or \*(AM. +Whatever was targeted when `q' or <Esc> was pressed will be made current +as you return to the \*(We display. +\*(XT 5. ALTERNATE\-DISPLAY Provisions and the `g' \*(CI for insight +into \*(CWs and \*(FGs. + +.PP +\*(NT Any window that has been scrolled\fI horizontally\fR will be reset if any +field changes are made via the Fields Management screen. +Any\fI vertical\fR scrolled position, however, will not be affected. +\*(XT 5c. SCROLLING a Window for additional information regarding vertical +and horizontal scrolling. + +.\" ---------------------------------------------------------------------- +.SH 4. INTERACTIVE Commands +.\" ---------------------------------------------------------------------- +Listed below is a brief index of commands within categories. +Some commands appear more than once \*(Em their meaning or scope may vary +depending on the context in which they are issued. + +.nf + 4a.\fI Global-Commands \fR + <Ent/Sp> ?, =, 0, + A, B, d, E, e, g, H, h, I, k, q, r, s, W, X, Y, Z, + ^G, ^K, ^N, ^P, ^U, ^L, ^R + 4b.\fI Summary-Area-Commands \fR + C, l, t, m, 1, 2, 3, 4, 5, ! + 4c.\fI Task-Area-Commands \fR + Appearance: b, J, j, x, y, z + Content: c, F, f, O, o, S, U, u, V, v, ^E + Size: #, i, n + Sorting: <, >, f, R + 4d.\fI Color-Mapping \fR + <Ret>, a, B, b, H, M, q, S, T, w, z, 0 \- 7 + 5b.\fI Commands-for-Windows \fR + \-, _, =, +, A, a, G, g, w + 5c.\fI Scrolling-a-Window \fR + C, Up, Dn, Left, Right, PgUp, PgDn, Home, End + 5d.\fI Searching-in-a-Window \fR + L, & + 5e.\fI Filtering-in-a-Window + O, o, ^O, =, + +.fi + +.\" ...................................................................... +.SS 4a. GLOBAL Commands +.\" ---------------------------------------------------------------------- +The global \*(CIs are\fB always\fR available\fR in both \*(FM and \*(AM. +However, some of these \*(CIs are\fB not available\fR when running +in Secure mode. + +If you wish to know in advance whether or not your \*(We has been +secured, simply ask for help and view the system summary on the second +line. + +.TP 7 +\ \ <\fBEnter\fR> or <\fBSpace\fR>\ \ :\fIRefresh-Display \fR +These commands awaken \*(We and following receipt of any input +the entire display will be repainted. +They also force an update of any hotplugged \*(Pu or \*(MP changes. + +Use either of these keys if you have a large delay interval and wish +to see current status, + +.TP 7 +\ \ \ \fB?\fR | \fBh\fR\ \ :\fIHelp \fR +There are two help levels available. +The first will provide a reminder of all the basic \*(CIs. +If \*(We is\fI secured\fR, that screen will be abbreviated. + +Typing `h' or `?' on that help screen will take you to help for +those \*(CIs applicable to \*(AM. + +.TP 7 +\ \ \ \fB=\fR\ \ :\fIExit-Display-Limits \fR +Removes restrictions on what is shown. +This command will reverse any `i' (idle tasks), `n' (max tasks), +`v' (hide children) and `F' focus commands that might be active. +It also provides for an exit from PID monitoring, User filtering, +Other filtering, Locate processing and Combine Cpus mode. + +Additionally, if the window has been scrolled it will be reset with +this command. + +.TP 7 +\ \ \ \fB0\fR\ \ :\fIZero-Suppress\fR toggle \fR +This command determines whether zeros are shown or suppressed for many +of the fields in a \*(TW. +Fields like UID, GID, NI, PR or P are not affected by this toggle. + +.TP 7 +\ \ \ \fBA\fR\ \ :\fIAlternate-Display-Mode\fR toggle \fR +This command will switch between \*(FM and \*(AM. +\*(XT 5. ALTERNATE\-DISPLAY Provisions and the `g' \*(CI for insight +into \*(CWs and \*(FGs. + +.TP 7 +\ \ \ \fBB\fR\ \ :\fIBold-Disable/Enable\fR toggle \fR +This command will influence use of the bold terminfo capability and +alters\fB both\fR the \*(SA and \*(TA for the \*(CW. +While it is intended primarily for use with dumb terminals, it can be +applied anytime. + +\*(NT When this toggle is \*O and \*(We is operating in monochrome mode, +the\fB entire display\fR will appear as normal text. +Thus, unless the `x' and/or `y' toggles are using reverse for emphasis, +there will be no visual confirmation that they are even on. + +.TP 7 +*\ \ \fBd\fR | \fBs\fR\ \ :\fIChange-Delay-Time-interval \fR +You will be prompted to enter the delay time, in seconds, between +display updates. + +Fractional seconds are honored, but a negative number is not allowed. +Entering 0 causes (nearly) continuous updates, with an unsatisfactory +display as the system and tty driver try to keep up with \*(We's demands. +The delay value is inversely proportional to system loading, +so set it with care. + +If at any time you wish to know the current delay time, simply ask for +help and view the system summary on the second line. + +.TP 7 +\ \ \ \fBE\fR\ \ :\fIEnforce-Summary-Memory-Scale\fR in Summary Area +With this command you can cycle through the available \*(SA memory scaling +which ranges from KiB (kibibytes or 1,024 bytes) through EiB (exbibytes or +1,152,921,504,606,846,976 bytes). + +If you see a `+' between a displayed number and the following label, it +means that \*(We was forced to truncate some portion of that number. +By raising the scaling factor, such truncation can be avoided. + +.TP 7 +\ \ \ \fBe\fR\ \ :\fIEnforce-Task-Memory-Scale\fR in Task Area +With this command you can cycle through the available \*(TA memory scaling +which ranges from KiB (kibibytes or 1,024 bytes) through PiB (pebibytes or +1,125,899,906,842,624 bytes). + +While \*(We will try to honor the selected target range, additional +scaling might still be necessary in order to accommodate current values. +If you wish to see a more homogeneous result in the memory columns, +raising the scaling range will usually accomplish that goal. +Raising it too high, however, is likely to produce an all zero result +which cannot be suppressed with the `0' \*(CI. + +.TP 7 +\ \ \ \fBg\fR\ \ :\fIChoose-Another-Window/Field-Group \fR +You will be prompted to enter a number between 1 and 4 designating the +\*(FG which should be made the \*(CW. +You will soon grow comfortable with these 4 windows, especially after +experimenting with \*(AM. + +.TP 7 +\ \ \ \fBH\fR\ \ :\fIThreads-mode\fR toggle \fR +When this toggle is \*O, individual threads will be displayed for all +processes in all visible \*(TWs. +Otherwise, \*(We displays a summation of all threads in each process. + +.TP 7 +\ \ \ \fBI\fR\ \ :\fIIrix/Solaris-Mode\fR toggle \fR +When operating in Solaris mode (`I' toggled \*F), a task's \*(Pu usage +will be divided by the total number of \*(PUs. +After issuing this command, you'll be told the new state of this toggle. + +.TP 7 +*\ \ \fBk\fR\ \ :\fIKill-a-task \fR +You will be prompted for a PID and then the signal to send. + +Entering no PID or a negative number will be interpreted as +the default shown in the prompt (the first task displayed). +A PID value of zero means the \*(We program itself. + +The default signal, as reflected in the prompt, is SIGTERM. +However, you can send any signal, via number or name. + +If you wish to abort the kill process, do one of the following +depending on your progress: +.nf + 1) at the pid prompt, type an invalid number + 2) at the signal prompt, type 0 (or any invalid signal) + 3) at any prompt, type <Esc> +.fi + +.TP 7 +\ \ \ \fBq\fR\ \ :\fIQuit \fR + +.TP 7 +*\ \ \fBr\fR\ \ :\fIRenice-a-Task \fR +You will be prompted for a PID and then the value to nice it to. + +Entering no PID or a negative number will be interpreted as +the default shown in the prompt (the first task displayed). +A PID value of zero means the \*(We program itself. + +A positive nice value will cause a process to lose priority. +Conversely, a negative nice value will cause a process to be viewed +more favorably by the kernel. +As a general rule, ordinary users can only increase the nice value +and are prevented from lowering it. + +If you wish to abort the renice process, do one of the following +depending on your progress: +.nf + 1) at the pid prompt, type an invalid number + 2) at the nice prompt, type <Enter> with no input + 3) at any prompt, type <Esc> +.fi + +.TP 7 +\ \ \ \fBW\fR\ \ :\fIWrite-the-Configuration-File \fR +This will save all of your options and toggles plus the current +display mode and delay time. +By issuing this command just before quitting \*(We, you will be able +restart later in exactly that same state. + +.TP 7 +\ \ \ \fBX\fR\ \ :\fIExtra-Fixed-Width \fR +Some fields are fixed width and not scalable. +As such, they are subject to truncation which would be indicated +by a `+' in the last position. + +This \*(CI can be used to alter the widths of the following fields: + +.nf + \fI field default field default field default \fR + GID 5 GROUP 8 WCHAN 10 + LOGID 5 LXC 8 nsCGROUP 10 + RUID 5 RUSER 8 nsIPC 10 + SUID 5 SUSER 8 nsMNT 10 + UID 5 TTY 8 nsNET 10 + USER 8 nsPID 10 + nsTIME 10 + nsUSER 10 + nsUTS 10 +.fi + +You will be prompted for the amount to be added to the default +widths shown above. +Entering zero forces a return to those defaults. + +If you enter a negative number, \*(We will automatically increase +the column size as needed until there is no more truncated data. + +\*(NT Whether explicitly or automatically increased, the widths for +these fields are never decreased by \*(We. +To narrow them you must specify a smaller number or restore the defaults. + +.TP 7 +\ \ \ \fBY\fR\ \ :\fIInspect-Other-Output \fR +After issuing the `Y' \*(CI, you will be prompted for a target PID. +Typing a value or accepting the default results in a separate screen. +That screen can be used to view a variety of files or piped command output +while the normal \*(We iterative display is paused. + +\*(NT This \*(CI is only fully realized when supporting entries have been +manually added to the end of the \*(We \*(CF. +For details on creating those entries, \*(Xt 6b. ADDING INSPECT Entries. + +Most of the keys used to navigate the Inspect feature are reflected in +its header prologue. +There are, however, additional keys available once you have selected a +particular file or command. +They are familiar to anyone who has used the pager `less' and are +summarized here for future reference. + +.nf + \fI key function \fR + = alternate status\-line, file or pipeline + / find, equivalent to `L' locate + n find next, equivalent to `&' locate next + <Space> scroll down, equivalent to <PgDn> + b scroll up, equivalent to <PgUp> + g first line, equivalent to <Home> + G last line, equivalent to <End> +.fi + +.TP 7 +\ \ \ \fBZ\fR\ \ :\fIChange-Color-Mapping \fR +This key will take you to a separate screen where you can change the +colors for the \*(CW, or for all windows. +For details regarding this \*(CI \*(Xt 4d. COLOR Mapping. + +.P +\ \ \fB^G\fR\ \ :\fIDisplay-Control-Groups \fR (Ctrl key + `g') +.br +\ \ \fB^K\fR\ \ :\fIDisplay-Cmdline \fR (Ctrl key + `k') +.br +\ \ \fB^N\fR\ \ :\fIDisplay-Environment \fR (Ctrl key + `n') +.br +\ \ \fB^P\fR\ \ :\fIDisplay-Namesspaces \fR (Ctrl key + `p') +.br +\ \ \fB^U\fR\ \ :\fIDisplay-Supplementary-Groups \fR (Ctrl key + `u') +.br +.RS +7 +Applied to the first process displayed, these commands will show +that task's full (potentially wrapped) information. +Such data will be displayed in a separate window at the bottom of +the screen while normal \*(We monitoring continues. + +Keying the\fI same\fR `Ctrl' command a second time removes that +separate window as does the `=' command. +Keying a different `Ctrl' combination, while one is already active, +immediately transitions to the new information. + +Notable among these provisions is the Ctrl+N (environment) command. +Its output can be extensive and not easily read when line wrapped. +A more readable version can be achieved with an `Inspect' entry +in the rcfile like the following. + +.nf + pipe ^I Environment ^I cat /proc/%d/environ | tr '\\0' '\\n' +.fi + +\*(XC `Y' \*(CI above and topic 6b. ADDING INSPECT Entries for +additional information. + +As an alternative to `Inspect', and available to all of these `Ctrl' +commands, the tab key can be used to highlight individual elements +in the bottom window. +.RS -7 + +.TP 7 +\ \ \fB^L\fR\ \ :\fILogged-Messages \fR (Ctrl key + `l') +The 10 most recent messages are displayed in a separate window at +the bottom of the screen while normal \*(We monitoring continues. +Keying `^L' a second time removes that window as does the `=' command. +Use the tab key to highlight individual messages. + +.TP 7 +*\ \fB^R\fR\ \ :\fIRenice-an-Autogroup \fR (Ctrl key + `r') +You will be prompted for a PID and then the value for its +autogroup AGNI. + +Entering no PID will be interpreted as the default shown in +the prompt (the first task displayed). + +A positive AGNI value will cause processes in that autogroup +to lose priority. +Conversely, a negative value causes them to be viewed more +favorably by the kernel. +Ordinary users are not allowed to set negative AGNI values. + +If you wish to abort the renice process type <Esc>. + +.IP "*" 3 +The commands shown with an \*(AK are not available in Secure mode, +nor will they be shown on the level-1 help screen. + +.\" ...................................................................... +.SS 4b. SUMMARY AREA Commands +.\" ---------------------------------------------------------------------- +The \*(SA \*(CIs are\fB always available\fR in both \*(FM and \*(AM. +They affect the beginning lines of your display and will determine the +position of messages and prompts. + +These commands always impact just the \*(CG. +\*(XT 5. ALTERNATE\-DISPLAY Provisions and the `g' \*(CI for insight into +\*(CWs and \*(FGs. + +.TP 7 +\ \ \ \fBC\fR\ \ :\fIShow-scroll-coordinates\fR toggle \fR +Toggle an informational message which is displayed whenever the message +line is not otherwise being used. +For additional information \*(Xt 5c. SCROLLING a Window. + +.TP 7 +\ \ \ \fBl\fR\ \ :\fILoad-Average/Uptime\fR toggle \fR +This is also the line containing the program name (possibly an alias) +when operating in \*(FM or the \*(CW name when operating in \*(AM. + +.TP 7 +\ \ \ \fBt\fR\ \ :\fITask/Cpu-States\fR toggle \fR +This command affects from 2 to many \*(SA lines, depending on the state +of the `1', `2' or `3' \*(CTs and whether or not \*(We is running under +true SMP. + +This portion of the \*(SA is also influenced by the `H' \*(CI toggle, +as reflected in the total label which shows either Tasks or Threads. + +This command serves as a 4-way toggle, cycling through these modes: +.nf + 1. detailed percentages by category + 2. abbreviated user/system and total % + bar graph + 3. abbreviated user/system and total % + block graph + 4. turn off task and cpu states display +.fi + +When operating in either of the graphic modes, the display becomes much +more meaningful when individual CPUs or NUMA nodes are also displayed. +\*(XC the `1', `2' and `3' commands below for additional information. + +.TP 7 +\ \ \ \fBm\fR\ \ :\fIMemory/Swap-Usage\fR toggle \fR +This command affects the two \*(SA lines dealing with physical +and virtual memory. + +This command serves as a 4-way toggle, cycling through these modes: +.nf + 1. detailed percentages by memory type + 2. abbreviated % used/total available + bar graph + 3. abbreviated % used/total available + block graph + 4. turn off memory display +.fi + +.TP 7 +\ \ \ \fB1\fR\ \ :\fISingle/Separate-Cpu-States\fR toggle \fR +This command affects how the `t' command's Cpu States portion is shown. +Although this toggle exists primarily to serve massively-parallel SMP +machines, it is not restricted to solely SMP environments. + +When you see `%Cpu(s):' in the \*(SA, the `1' toggle is \*O and all +\*(Pu information is gathered in a single line. +Otherwise, each \*(Pu is displayed separately as: `%Cpu0, %Cpu1, ...' +up to available screen height. + +.TP 7 +\ \ \ \fB2\fR\ \ :\fINUMA-Nodes/Cpu-Summary\fR toggle \fR +This command toggles between the `1' command cpu summary display (only) +or a summary display plus the cpu usage statistics for each NUMA Node. +It is only available if a system has the requisite NUMA support. + +.TP 7 +\ \ \ \fB3\fR\ \ :\fIExpand-NUMA-Node \fR +You will be invited to enter a number representing a NUMA Node. +Thereafter, a node summary plus the statistics for each cpu in that +node will be shown until the `1', `2' or `4' \*(CT is pressed. +This \*(CI is only available if a system has the requisite NUMA support. + +.TP 7 +\ \ \ \fB4\fR\ \ :\fIDisplay-Multiple-Elements-Adjacent\fR toggle \fR +This \*(CT turns the `1' toggle \*F and shows multiple \*(PU and +Memory results on each line. +Each successive `4' key adds another \*(PU until again reverting +to separate lines for \*(PU and Memory results. + +A maximum of 8 \*(PUs per line can be displayed in this manner. +However, data truncation may occur before reaching the maximum. +That is definitely true when displaying detailed statistics via +the `t' \*(CT since such data cannot be scaled like the graphic +representations. + +If one wished to quickly exit adjacent mode without cycling all the +way to 8, simply use the `1' \*(CT. + +.TP 7 +\ \ \ \fB5\fR\ \ :\fIDisplay-P-Cores-and-E-Cores\fR toggle \fR +This \*(CT is only active when the `t' toggle is \*O and the `1', `2', +`3' and `!' toggles are \*F, thus showing individual \*(PU results. +It assumes a platform has multiple cores of two distinct types, +either multi-threaded (P-Core) or single-threaded (E-Core). + +While normally each \*(Pu is displayed as `%Cpu0, %Cpu1, ...', this +toggle can be used to identify and/or filter those \*(Pus by their +core type, either P-Core (performance) or E-Core (efficient). + +The 1st time `5' is struck, each \*(PU is displayed as `%Cp\fBP\fR' +or `%Cp\fBE\fR' representing the two core types. +The 2nd time, only P-Cores (%Cp\fBP\fR) will be shown. +The 3rd time, only E-Cores (%Cp\fBE\fR) are displayed. +When this \*(CT is struck for the 4th time, the \*(PU display +returns to the normal `%Cpu' convention. + +If separate\fI performance\fR and\fI efficient\fR categories are +not present, this \*(CT will have no effect. + +.TP 7 +\ \ \ \fB!\fR\ \ :\fICombine-Cpus-Mode\fR toggle \fR +This \*(CT is intended for massively parallel SMP environments where, +even with the `4' \*(CT, not all processors can be displayed. +With each press of `!' the number of \*(Pus combined is doubled thus +reducing the total number of \*(Pu lines displayed. + +For example, with the first press of `!' two \*(Pus will be combined and +displayed as `0-1, 2-3, ...' instead of the normal `%Cpu0, %Cpu1, %Cpu2, +%Cpu3, ...'. With a second `!' \*(CT four \*(Pus are combined and shown +as `0-3, 4-7, ...'. +Then the third `!' press, combining eight \*(Pus, shows as `0-7, 8-15, ...', +etc. + +Such progression continues until individual \*(Pus are again displayed +and impacts both the `1' and `4' toggles (one or multiple columns). +Use the `=' command to exit \fBCombine Cpus\fR mode. + +.PP +\*(NT If the entire \*(SA has been toggled \*F for any window, you would +be left with just the\fB message line\fR. +In that way, you will have maximized available task rows but (temporarily) +sacrificed the program name in \*(FM or the \*(CW name when in \*(AM. + +.\" ...................................................................... +.SS 4c. TASK AREA Commands +.\" ---------------------------------------------------------------------- +The \*(TA \*(CIs are\fB always\fR available in \*(FM. + +The \*(TA \*(CIs are\fB never available\fR in \*(AM\fI if\fR the \*(CW's +\*(TD has been toggled \*F (\*(Xt 5. ALTERNATE\-DISPLAY Provisions). + +.\" .................................................. +.PP +.B APPEARANCE\fR of \*(TW + +.TP 7 +\ \ \ \fBJ\fR\ \ :\fIJustify-Numeric-Columns\fR toggle \fR +Alternates between right-justified (the default) and +left-justified numeric data. +If the numeric data completely fills the available column, this +\*(CT may impact the column header only. + +.TP 7 +\ \ \ \fBj\fR\ \ :\fIJustify-Character-Columns\fR toggle \fR +Alternates between left-justified (the default) and +right-justified character data. +If the character data completely fills the available column, this +\*(CT may impact the column header only. + +.PP +.RS +2 +The following commands will also be influenced by the state of the +global `B' (bold enable) toggle. +.RS -2 + +.TP 7 +\ \ \ \fBb\fR\ \ :\fIBold/Reverse\fR toggle \fR +This command will impact how the `x' and `y' toggles are displayed. +It may also impact the \*(SA when a bar graph has been selected for \*(Pu +states or memory usage via the `t' or `m' toggles. + +.TP 7 +\ \ \ \fBx\fR\ \ :\fIColumn-Highlight\fR toggle \fR +Changes highlighting for the current sort field. +If you forget which field is being sorted this command can serve as a quick +visual reminder, providing the sort field is being displayed. +The sort field might\fI not\fR be visible because: + 1) there is insufficient\fI Screen Width \fR + 2) the `f' \*(CI turned it \*F + +.TP 7 +\ \ \ \fBy\fR\ \ :\fIRow-Highlight\fR toggle \fR +Changes highlighting for "running" tasks. +For additional insight into this task state, +\*(Xt 3a. DESCRIPTIONS of Fields, the `S' field (Process Status). + +Use of this provision provides important insight into your system's health. +The only costs will be a few additional tty escape sequences. + +.TP 7 +\ \ \ \fBz\fR\ \ :\fIColor/Monochrome\fR toggle \fR +Switches the \*(CW between your last used color scheme and the older form +of black-on-white or white-on-black. +This command will alter\fB both\fR the \*(SA and \*(TA but does not affect +the state of the `x', `y' or `b' toggles. + +.\" .................................................. +.PP +.B CONTENT\fR of \*(TW + +.TP 7 +\ \ \ \fBc\fR\ \ :\fICommand-Line/Program-Name\fR toggle \fR +This command will be honored whether or not the COMMAND column +is currently visible. +Later, should that field come into view, the change you applied will be seen. + +.TP 7 +\ \ \ \fBF\fR\ \ :\fIMaintain-Parent-Focus\fR toggle \fR +When in forest view mode, this key serves as a toggle to retain focus +on a target task, presumably one with forked children. +If forest view mode is \*F this key has no effect. + +The toggle is applied to the first (topmost) process in the \*(CW. +Once established, that task is always displayed as the first (topmost) +process along with its forked children. +All other processes will be suppressed. + +\*(NT keys like `i' (idle tasks), `n' (max tasks), `v' (hide children) +and User/Other filtering remain accessible and can impact what is displayed. + +.TP 7 +\ \ \ \fBf\fR\ \ :\fIFields-Management \fR +This key displays a separate screen where you can change which fields are +displayed, their order and also designate the sort field. +For additional information on this \*(CI +\*(Xt 3b. MANAGING Fields. + +.TP 7 +\ \ \ \fBO\fR | \fBo\fR\ \ :\fIOther-Filtering \fR +You will be prompted for the selection criteria which then determines +which tasks will be shown in the \*(CW. +Your criteria can be made case sensitive or case can be ignored. +And you determine if \*(We should include or exclude matching tasks. + +\*(XT 5e. FILTERING in a window for details on these and additional +related \*(CIs. + +.TP 7 +\ \ \ \fBS\fR\ \ :\fICumulative-Time-Mode\fR toggle \fR +When Cumulative mode is \*O, each process is listed with the \*(Pu +time that it and its dead children have used. + +When \*F, programs that fork into many separate tasks will appear +less demanding. +For programs like `init' or a shell this is appropriate but for others, +like compilers, perhaps not. +Experiment with two \*(TWs sharing the same sort field but with different `S' +states and see which representation you prefer. + +After issuing this command, you'll be informed of the new state of this toggle. +If you wish to know in advance whether or not Cumulative mode is in +effect, simply ask for help and view the window summary on the second line. + +.TP 7 +\ \ \ \fBU\fR | \fBu\fR\ \ :\fIShow-Specific-User-Only \fR +You will be prompted for the\fB uid\fR or\fB name\fR of the user to display. +The \-u option matches on \fB effective\fR user whereas the \-U option +matches on\fB any\fR user (real, effective, saved, or filesystem). + +Thereafter, in that \*(TW only matching users will be shown, or possibly +no processes will be shown. +Prepending an exclamation point (`!') to the user id or name instructs \*(We +to display only processes with users not matching the one provided. + +Different \*(TWs can be used to filter different users. +Later, if you wish to monitor all users again in the \*(CW, re-issue this +command but just press <Enter> at the prompt. + +.TP 7 +\ \ \ \fBV\fR\ \ :\fIForest-View-Mode\fR toggle \fR +In this mode, processes are reordered according to their parents and +the layout of the COMMAND column resembles that of a tree. +In forest view mode it is still possible to toggle between program +name and command line (\*(Xc `c' \*(CI) or between processes and +threads (\*(Xc `H' \*(CI). + +\*(NT Typing any key affecting the sort order will exit forest view +mode in the \*(CW. +\*(XT 4c. TASK AREA Commands, SORTING for information on those keys. + +.TP 7 +\ \ \ \fBv\fR\ \ :\fIHide/Show-Children\fR toggle \fR +When in forest view mode, this key serves as a toggle to collapse or +expand the children of a parent. + +The toggle is applied against the first (topmost) process in the \*(CW. +\*(XT 5c. SCROLLING a Window for additional information regarding +vertical scrolling. + +If the target process has not forked any children, this key has no effect. +It also has no effect when not in forest view mode. + +.TP 7 +\ \ \fB^E\fR\ \ :\fIScale-CPU-Time-fields\fR (Ctrl key + `e') +The `time' fields are normally displayed with the greatest +precision their widths permit. +This toggle reduces that precision until it wraps. +It also illustrates the scaling those fields \fImight\fR experience +automatically, which usually depends on how long the system runs. + +For example, if `MMM:SS.hh' is shown, each ^E keystroke would change +it to: `MM:SS', `Hours,MM', `Days+Hours' and finally `Weeks+Days'. + +Not all time fields are subject to the full range of such scaling. + +.\" .................................................. +.PP +.B SIZE\fR of \*(TW + +.TP 7 +\ \ \ \fBi\fR\ \ :\fIIdle-Process\fR toggle \fR +Displays all tasks or just active tasks. +When this toggle is \*F, tasks that have not used any \*(PU since the +last update will not be displayed. +However, due to the granularity of the %CPU and TIME+ fields, +some processes may still be displayed that\fI appear\fR to have +used\fI no\fR \*(PU. + +If this command is applied to the last \*(TD when in \*(AM, then it will not +affect the window's size, as all prior \*(TDs will have already been painted. + +.TP 7 +\ \ \ \fBn\fR | \fB#\fR\ \ :\fISet-Maximum-Tasks \fR +You will be prompted to enter the number of tasks to display. +The lessor of your number and available screen rows will be used. + +When used in \*(AM, this is the command that gives you precise control over +the size of each currently visible \*(TD, except for the very last. +It will not affect the last window's size, as all prior \*(TDs will have +already been painted. + +\*(NT If you wish to increase the size of the last visible \*(TD when in \*(AM, +simply decrease the size of the \*(TD(s) above it. + +.\" .................................................. +.PP +.B SORTING\fR of \*(TW +.PP +.RS +3 +For compatibility, this \*(We supports most of the former \*(We sort keys. +Since this is primarily a service to former \*(We users, these commands do +not appear on any help screen. +.nf + \fI command sorted-field supported \fR + A start time (non-display) \fB No \fR + M %MEM Yes + N PID Yes + P %CPU Yes + T TIME+ Yes +.fi + +Before using any of the following sort provisions, \*(We suggests that you +temporarily turn on column highlighting using the `x' \*(CI. +That will help ensure that the actual sort environment matches your intent. + +The following \*(CIs will\fB only\fR be honored when the current sort field +is\fB visible\fR. +The sort field might\fI not\fR be visible because: + 1) there is insufficient\fI Screen Width \fR + 2) the `f' \*(CI turned it \*F + +.TP 7 +\ \ \ \fB<\fR\ \ :\fIMove-Sort-Field-Left \fR +Moves the sort column to the left unless the current sort field is +the first field being displayed. + +.TP 7 +\ \ \ \fB>\fR\ \ :\fIMove-Sort-Field-Right \fR +Moves the sort column to the right unless the current sort field is +the last field being displayed. + +.PP +The following \*(CIs will\fB always\fR be honored whether or not +the current sort field is visible. + +.TP 7 +\ \ \ \fBf\fR\ \ :\fIFields-Management \fR +This key displays a separate screen where you can change which field +is used as the sort column, among other functions. +This can be a convenient way to simply verify the current sort field, +when running \*(We with column highlighting turned \*F. + +.TP 7 +\ \ \ \fBR\fR\ \ :\fIReverse/Normal-Sort-Field\fR toggle \fR +Using this \*(CI you can alternate between high-to-low and low-to-high sorts. + +.\" ...................................................................... +.SS 4d. COLOR Mapping +.\" ---------------------------------------------------------------------- +When you issue the `Z' \*(CI, you will be presented with a separate screen. +That screen can be used to change the colors in just the \*(CW or +in all four windows before returning to the \*(We display. + +.P +The following \*(CIs are available. +.nf + \fB4\fR upper case letters to select a\fB target \fR + \fB8\fR numbers to select a\fB color \fR + normal toggles available \fR + B :bold disable/enable + b :running tasks "bold"/reverse + z :color/mono + other commands available \fR + a/w :apply, then go to next/prior + <Enter> :apply and exit + q :abandon current changes and exit +.fi + +If you use `a' or `w' to cycle the targeted window, you will +have applied the color scheme that was displayed when you left that window. +You can, of course, easily return to any window and reapply different +colors or turn colors \*F completely with the `z' toggle. + +The Color Mapping screen can also be used to change the \*(CG in +either \*(FM or \*(AM. +Whatever was targeted when `q' or <Enter> was pressed will be made current +as you return to the \*(We display. + +.\" ---------------------------------------------------------------------- +.SH 5. ALTERNATE\-DISPLAY Provisions +.\" ---------------------------------------------------------------------- +.\" ...................................................................... +.SS 5a. WINDOWS Overview +.\" ---------------------------------------------------------------------- +.TP 3 +.B Field Groups/Windows\fR: +In \*(FM there is a single window represented by the entire screen. +That single window can still be changed to display 1 of 4 different\fB field +groups\fR (\*(Xc `g' \*(CI, repeated below). +Each of the 4 \*(FGs has a unique separately configurable\fB \*(SA \fR +and its own configurable\fB \*(TA\fR. + +In \*(AM, those 4 underlying \*(FGs can now be made visible +simultaneously, or can be turned \*F individually at your command. + +The \*(SA will always exist, even if it's only the message line. +At any given time only\fI one\fR \*(SA can be displayed. +However, depending on your commands, there could be from\fI zero \fR +to\fI four\fR separate \*(TDs currently showing on the screen. + +.TP 3 +.B Current Window\fR: +The \*(CW is the window associated with the \*(SA and the window to which +task related commands are always directed. +Since in \*(AM you can toggle the \*(TD \*F, some commands might be +restricted for the \*(CW. + +A further complication arises when you have toggled the first \*(SA +line \*F. +With the loss of the window name (the `l' toggled line), you'll not easily +know what window is the \*(CW. + +.\" ...................................................................... +.SS 5b. COMMANDS for Windows +.\" ---------------------------------------------------------------------- +.TP 7 +\ \ \ \fB-\fR | \fB_\fR\ \ :\fIShow/Hide-Window(s)\fR toggles \fR +The `\-' key turns the \*(CW's \*(TD \*O and \*F. +When \*O, that \*(TA will show a minimum of the columns header you've +established with the `f' \*(CI. +It will also reflect any other \*(TA options/toggles you've applied +yielding zero or more tasks. + +The `_' key does the same for all \*(TDs. +In other words, it switches between the currently visible \*(TD(s) and any +\*(TD(s) you had toggled \*F. +If all 4 \*(TDs are currently visible, this \*(CI will leave the \*(SA +as the only display element. + +.TP 7 +*\ \ \fB=\fR | \fB+\fR\ \ :\fIEqualize/Reset-Window(s) \fR +The `=' key forces the \*(CW's \*(TD to be visible. +It also reverses any active `i' (idle tasks), `n' (max tasks), `u/U' +(user filter), `o/O' (other filter), `v' (hide children), `F' focused, +`L' (locate) and `!' (combine cpus) commands. +Also, if the window had been scrolled, it will be reset with this command. +\*(XT 5c. SCROLLING a Window for additional information regarding vertical +and horizontal scrolling. + +The `+' key does the same for all windows. +The four \*(TDs will reappear, evenly balanced, while retaining +any customizations previously applied beyond those noted +for the `=' \*(CT. + +.TP 7 +*\ \ \fBA\fR\ \ :\fIAlternate-Display-Mode\fR toggle \fR +This command will switch between \*(FM and \*(AM. + +The first time you issue this command, all four \*(TDs will be shown. +Thereafter when you switch modes, you will see only the \*(TD(s) you've +chosen to make visible. + +.TP 7 +*\ \ \fBa\fR | \fBw\fR\ \ :\fINext-Window-Forward/Backward \fR +This will change the \*(CW, which in turn changes the window to which +commands are directed. +These keys act in a circular fashion so you can reach any desired window +using either key. + +Assuming the window name is visible (you have not toggled `l' \*F), +whenever the \*(CW name loses its emphasis/color, that's a reminder +the \*(TD is \*F and many commands will be restricted. + +.TP 7 +\ \ \ \fBG\fR\ \ :\fIChange-Window/Field-Group-Name \fR +You will be prompted for a new name to be applied to the \*(CW. +It does not require that the window name be visible +(the `l' toggle to be \*O). + +.IP "*" 3 +The \*(CIs shown with an \*(AK have use beyond \*(AM. +.nf + =, A, g are always available + a, w act the same with color mapping + and fields management +.fi + +.TP 7 +*\ \ \fBg\fR\ \ :\fIChoose-Another-Window/Field-Group \fR +You will be prompted to enter a number between 1 and 4 designating the +\*(FG which should be made the \*(CW. + +In \*(FM, this command is necessary to alter the \*(CW. +In \*(AM, it is simply a less convenient alternative to the `a' and `w' +commands. + +.\" ...................................................................... +.SS 5c. SCROLLING a Window +.\" ---------------------------------------------------------------------- +Typically a \*(TW is a partial view into a system's total tasks/threads +which shows only some of the available fields/columns. +With these \*(KSs, you can move that view vertically or horizontally to +reveal any desired task or column. + +.TP 4 +\fBUp\fR,\fBPgUp\fR\ \ :\fIScroll-Tasks \fR +Move the view up toward the first task row, until the first task is +displayed at the top of the \*(CW. +The \fIUp\fR \*(KA moves a single line while \fIPgUp\fR scrolls the +entire window. + +.TP 4 +\fBDown\fR,\fBPgDn\fR\ \ :\fIScroll-Tasks \fR +Move the view down toward the last task row, until the last task is +the only task displayed at the top of the \*(CW. +The \fIDown\fR \*(KA moves a single line while \fIPgDn\fR scrolls the +entire window. + +.TP 4 +\fBLeft\fR,\fBRight\fR\ \ :\fIScroll-Columns \fR +Move the view of displayable fields horizontally one column at a time. + +\*(NT As a reminder, some fields/columns are not fixed-width but +allocated all remaining screen width when visible. +When scrolling right or left, that feature may produce some +unexpected results initially. + +Additionally, there are special provisions for any variable width field +when positioned as the last displayed field. +Once that field is reached via the right arrow key, and is thus the only +column shown, you can continue scrolling horizontally within such a field. +\*(XC `C' \*(CI below for additional information. + +.TP 4 +\fBHome\fR\ \ :\fIJump-to-Home-Position \fR +Reposition the display to the un-scrolled coordinates. + +.TP 4 +\fBEnd\fR\ \ :\fIJump-to-End-Position \fR +Reposition the display so that the rightmost column reflects the last +displayable field and the bottom task row represents the last task. + +\*(NT From this position it is still possible to scroll\fI down\fR +and\fI right\fR using the \*(KAs. +This is true until a single column and a single task is left as the only +display element. + +.TP 4 +\fBC\fR\ \ :\fIShow-scroll-coordinates\fR toggle \fR +Toggle an informational message which is displayed whenever the message +line is not otherwise being used. +That message will take one of two forms depending on whether or not a +variable width column has also been scrolled. + +.nf + \fBscroll coordinates: y = n/n (tasks), x = n/n (fields)\fR + \fRscroll coordinates: y = n/n (tasks), x = n/n (fields)\fB + nn\fR +.fi + +The coordinates shown as \fBn\fR/\fBn\fR are relative to the upper left +corner of the \*(CW. +The additional `\fB+\ nn\fR' represents the displacement into a variable +width column when it has been scrolled horizontally. +Such displacement occurs in normal 8 character tab stop amounts via +the right and left arrow keys. + +.RS +4 +.TP 4 +\fBy = n/n (tasks) \fR +The first \fBn\fR represents the topmost visible task and is controlled +by \*(KSs. +The second \fBn\fR is updated automatically to reflect total tasks. + +.TP 4 +\fBx = n/n (fields) \fR +The first \fBn\fR represents the leftmost displayed column and is +controlled by \*(KSs. +The second \fBn\fR is the total number of displayable fields and is +established with the `\fBf\fR' \*(CI. +.RS -4 + +.PP +The above \*(CIs are\fB always\fR available in \*(FM but\fB never\fR +available in \*(AM if the \*(CW's \*(TD has been toggled \*F. + +\*(NT When any form of filtering is active, you can expect some slight +aberrations when scrolling since not all tasks will be visible. +This is particularly apparent when using the Up/Down \*(KAs. + +.\" ...................................................................... +.SS 5d. SEARCHING in a Window +.\" ---------------------------------------------------------------------- +You can use these \*(CIs to locate a task row containing a particular value. + +.TP 4 +\fBL\fR\ \ :\fILocate-a-string\fR +You will be prompted for the case-sensitive string to locate starting from +the current window coordinates. +There are no restrictions on search string content. + +Searches are not limited to values from a single field or column. +All of the values displayed in a task row are allowed in a search string. +You may include spaces, numbers, symbols and even forest view artwork. + +Keying <Enter> with no input will effectively disable the `&' key until +a new search string is entered. + +.TP 4 +\fB&\fR\ \ :\fILocate-next\fR +Assuming a search string has been established, \*(We will attempt to locate +the next occurrence. + +.PP +When a match is found, the current window is repositioned vertically so the +task row containing that string is first. +The scroll coordinates message can provide confirmation of such vertical +repositioning (\*(Xc `C' \*(CI). +Horizontal scrolling, however, is never altered via searching. + +The availability of a matching string will be influenced by the following +factors. +.RS +3 +.TP 3 +a. Which fields are displayable from the total available, +\*(Xt 3b. MANAGING Fields. +.TP 3 +b. Scrolling a window vertically and/or horizontally, +\*(Xt 5c. SCROLLING a Window. +.TP 3 +c. The state of the command/command-line toggle, +\*(Xc `c' \*(CI. +.TP 3 +d. The stability of the chosen sort column, +for example PID is good but %CPU bad. +.RS -3 + +.PP +If a search fails, restoring the \*(CW home (unscrolled) position, scrolling +horizontally, displaying command-lines or choosing a more stable sort field +could yet produce a successful `&' search. + +The above \*(CIs are\fB always\fR available in \*(FM but\fB never\fR +available in \*(AM if the \*(CW's \*(TD has been toggled \*F. + +.\" ...................................................................... +.SS 5e. FILTERING in a Window +.\" ---------------------------------------------------------------------- +You can use this `Other Filter' feature to establish selection criteria which +will then determine which tasks are shown in the \*(CW. +Such filters can be made persistent if preserved in the rcfile via +the `W' \*(CI. + +Establishing a filter requires: 1) a field name; 2) an operator; and +3) a selection value, as a minimum. +This is the most complex of \*(We's user input requirements so, when you make +a mistake, command recall will be your friend. +Remember the Up/Down \*(KAs or their aliases when prompted for input. + +.B Filter Basics +.RS +3 +.TP 3 +1. field names are case sensitive and spelled as in the header +.TP 3 +2. selection values need not comprise the full displayed field +.TP 3 +3. a selection is either case insensitive or sensitive to case +.TP 3 +4. the default is inclusion, prepending `!' denotes exclusions +.TP 3 +5. multiple selection criteria can be applied to a \*(TW +.TP 3 +6. inclusion and exclusion criteria can be used simultaneously +.TP 3 +7. the 1 equality and 2 relational filters can be freely mixed +.TP 3 +8. separate unique filters are maintained for each \*(TW + +.PP +If a field is not turned on or is not currently in view, then your selection +criteria will not affect the display. +Later, should a filtered field become visible, the selection criteria will +then be applied. +.RE + +.B Keyboard Summary +.TP 6 +\ \ \fBO\fR\ \ :\fIOther-Filter\fR (upper case) +You will be prompted to establish a \fBcase sensitive\fR filter. + +.TP 6 +\ \ \fBo\fR\ \ :\fIOther-Filter\fR (lower case) +You will be prompted to establish a filter that \fBignores case\fR when +matching. + +.TP 6 +\ \fB^O\fR\ \ :\fIShow-Active-Filters\fR (Ctrl key + `o') +This can serve as a reminder of which filters are active in the \*(CW. +A summary will be shown on the message line until you press the <Enter> key. + +.TP 6 +\ \ \fB=\fR\ \ :\fIReset-Filtering\fR in current window +This clears all of your selection criteria in the \*(CW. +It also has additional impact so please \*(Xt 4a. GLOBAL Commands. + +.TP 6 +\ \ \fB+\fR\ \ :\fIReset-Filtering\fR in all windows +This clears the selection criteria in all windows, assuming you are in \*(AM. +As with the `=' \*(CI, it too has additional consequences so you might wish to +\*(Xt 5b. COMMANDS for Windows. + +.PP +.B Input Requirements +.RS +3 +.P +When prompted for selection criteria, the data you provide must take one +of two forms. +There are 3 required pieces of information, with a 4th as optional. +These examples use spaces for clarity but your input generally would not. +.nf + #1 \fB#2\fR #3 ( required ) + Field\-Name ? include\-if\-value + \fB!\fR Field\-Name ? \fBexclude\fR\-if\-value + #4 ( optional ) +.fi + +Items #1, #3 and #4 should be self\-explanatory. +Item \fB#2\fR represents both a required \fIdelimiter\fR and the \fIoperator\fR +which must be one of either equality (`=') or relation (`<' or `>'). + +The `=' equality operator requires only a partial match and that +can reduce your `if\-value' input requirements. +The `>' or `<' relational operators always employ string comparisons, +even with numeric fields. +They are designed to work with a field's default \fIjustification\fR and +with homogeneous data. +When some field's numeric amounts have been subjected to \fIscaling\fR +while others have not, that data is no longer homogeneous. + +If you establish a relational filter and you \fBhave\fR changed the +default Numeric or Character \fIjustification\fR, that filter is likely to fail. +When a relational filter is applied to a memory field and you \fBhave not\fR +changed the \fIscaling\fR, it may produce misleading results. +This happens, for example, because `100.0m' (MiB) would appear greater +than `1.000g' (GiB) when compared as strings. + +If your filtered results appear suspect, simply altering justification or +scaling may yet achieve the desired objective. +See the `j', `J' and `e' \*(CIs for additional information. +.RE + +.B Potential Problems +.RS +3 +.P +These \fBGROUP\fR filters could produce the exact same results or the +second one might not display anything at all, just a blank \*(TW. +.nf + GROUP=root ( only the same results when ) + GROUP=ROOT ( invoked via lower case `o' ) +.fi + +Either of these \fBRES\fR filters might yield inconsistent and/or +misleading results, depending on the current memory scaling factor. +Or both filters could produce the exact same results. +.nf + RES>9999 ( only the same results when ) + !RES<10000 ( memory scaling is at `KiB' ) +.fi + +This \fBnMin\fR filter illustrates a problem unique to scalable fields. +This particular field can display a maximum of 4 digits, beyond which values +are automatically scaled to KiB or above. +So while amounts greater than 9999 exist, they will appear as 2.6m, 197k, etc. +.nf + nMin>9999 ( always a blank \*(TW ) +.fi +.RE + +.B Potential Solutions +.RS +3 +.P +These examples illustrate how Other Filtering can be creatively +applied to achieve almost any desired result. +Single quotes are sometimes shown to delimit the spaces which are part of +a filter or to represent a request for status (^O) accurately. +But if you used them with if-values in real life, no matches would be found. + +Assuming field \fBnTH\fR is displayed, the first filter will result in +only multi-threaded processes being shown. +It also reminds us that a trailing space is part of every displayed field. +The second filter achieves the exact same results with less typing. +.nf + !nTH=` 1 ' ( ` for clarity only ) + nTH>1 ( same with less i/p ) +.fi + +With Forest View mode active and the \fBCOMMAND\fR column in view, this +filter effectively collapses child processes so that just 3 levels are shown. +.nf + !COMMAND=` `- ' ( ` for clarity only ) +.fi + +The final two filters appear as in response to the status request key (^O). +In reality, each filter would have required separate input. +The \fBPR\fR example shows the two concurrent filters necessary to display +tasks with priorities of 20 or more, since some might be negative. +Then by exploiting trailing spaces, the \fBnMin\fR series of filters could +achieve the failed `9999' objective discussed above. +.nf + `PR>20' + `!PR=-' ( 2 for right result ) + `!nMin=0 ' + `!nMin=1 ' + `!nMin=2 ' + `!nMin=3 ' ... +.fi +.RS -3 + +.\" ---------------------------------------------------------------------- +.SH 6. FILES +.\" ---------------------------------------------------------------------- +.SS 6a. PERSONAL Configuration File +.\" ---------------------------------------------------------------------- +This file is created or updated via the `W' \*(CI. + +The legacy version is written as `$HOME/.your\-name\-4\-\*(We' + `rc' +with a leading period. + +A newly created \*(CF is written as procps/your\-name\-4\-\*(We' + `rc' +without a leading period. +The procps directory will be subordinate to either $XDG_CONFIG_HOME when +set as an absolute path or the $HOME/.config directory. + +While not intended to be edited manually, here is the general layout: +.nf + global # line 1: the program name/alias notation + " # line 2: id,altscr,irixps,delay,curwin + per ea # line a: winname,fieldscur + window # line b: winflags,sortindx,maxtasks,etc + " # line c: summclr,msgsclr,headclr,taskclr + global # line 15: additional miscellaneous settings + " # any remaining lines are devoted to optional + " # active `other filters' discussed in section 5e above + " # plus `inspect' entries discussed in section 6b below +.fi + +If a valid absolute path to the rcfile cannot be established, customizations +made to a running \*(We will be impossible to preserve. + +.\" ...................................................................... +.SS 6b. ADDING INSPECT Entries +.\" ---------------------------------------------------------------------- +To exploit the `Y' \*(CI, you must add entries at the\fB end\fR of the +\*(We personal \*(CF. +Such entries simply reflect a file to be read or command/pipeline to be +executed whose results will then be displayed in a separate scrollable, +searchable window. + +If you don't know the location or name of your \*(We rcfile, use the `W' +\*(CI to rewrite it and note those details. + +Inspect entries can be added with a redirected echo or by editing the \*(CF. +Redirecting an echo risks overwriting the rcfile should it replace (>) +rather than append (>>) to that file. +Conversely, when using an editor care must be taken not to corrupt existing +lines, some of which could contain unprintable data or unusual characters +depending on the \*(We version under which that \*(CF was saved. + +Those Inspect entries beginning with a `#' character are ignored, regardless +of content. +Otherwise they consist of the following 3 elements, each of which\fI must\fR +be separated by a tab character (thus 2 `\\t' total): + +.nf + .type: literal `file' or `pipe' + .name: selection shown on the Inspect screen + .fmts: string representing a path or command +.fi + +The two types of Inspect entries are\fI not\fR interchangeable. +Those designated `\fBfile\fR' will be accessed using fopen and +must reference a single file in the `.fmts' element. +Entries specifying `\fBpipe\fR' will employ popen, their `.fmts' element +could contain many pipelined commands and, none can be interactive. + +If the file or pipeline represented in your `.fmts' deals with the specific PID +input or accepted when prompted, then the format string must also contain +the `\fB%d\fR' specifier, as these examples illustrate. + +.nf + .fmts= /proc/\fI%d\fR/numa_maps + .fmts= lsof -P -p\fI %d\fR +.fi + +For `\fBpipe\fR' type entries only, you may also wish to redirect stderr to +stdout for a more comprehensive result. +Thus the format string becomes: + +.nf + .fmts= pmap -x %d\fI 2>&1\fR +.fi + +Here are examples of both types of Inspect entries as they might appear +in the rcfile. +The first entry will be ignored due to the initial `#' character. +For clarity, the pseudo tab depictions (^I) are surrounded by an +extra space but the actual tabs would not be. +.nf + + # pipe ^I Sockets ^I lsof -n -P -i 2>&1 + pipe ^I Open Files ^I lsof -P -p %d 2>&1 + file ^I NUMA Info ^I /proc/%d/numa_maps + pipe ^I Log ^I tail -n100 /var/log/syslog | sort -Mr +.fi + +Except for the commented entry above, these next examples show what could +be echoed to achieve similar results, assuming the rcfile name was `.toprc'. +However, due to the embedded tab characters, each of these lines should be +preceded by `\fB/bin/echo \-e\fR', not just a simple an `echo', to +enable backslash interpretation regardless of which shell you use. + +.nf + "pipe\\tOpen Files\\tlsof -P -p %d 2>&1" >> ~/.toprc + "file\\tNUMA Info\\t/proc/%d/numa_maps" >> ~/.toprc + "pipe\\tLog\\ttail -n200 /var/log/syslog | sort -Mr" >> ~/.toprc +.fi + +If any inspect entry you create produces output with unprintable characters +they will be displayed in either the ^C notation or hexadecimal <FF> form, +depending on their value. +This applies to tab characters as well, which will show as `^I'. +If you want a truer representation, any embedded tabs should be expanded. +The following example takes what could have been a `file' entry but employs +a `pipe' instead so as to expand the embedded tabs. + +.nf + # next would have contained `\\t' ... + # file ^I <your_name> ^I /proc/%d/status + # but this will eliminate embedded `\\t' ... + pipe ^I <your_name> ^I cat /proc/%d/status | expand \- +.fi + +\*(NT Some programs might rely on \fISIGINT\fR to end. +Therefore, if a `\fBpipe\fR' such as the following is established, one must +use Ctrl-C to terminate it in order to review the results. +This is the single occasion where a `^C' will not also terminate \*(We. + +.nf + pipe ^I Trace ^I /usr/bin/strace -p %d 2>&1 +.fi + +Lastly, while `\fBpipe\fR' type entries have been discussed in terms of pipelines +and commands, there is nothing to prevent you from including \fI shell scripts\fR +as well. +Perhaps even newly created scripts designed specifically for the `Y' \*(CI. + +For example, as the number of your Inspect entries grows over time, the `Options:' +row will be truncated when screen width is exceeded. +That does not affect operation other than to make some selections invisible. +However, if some choices are lost to truncation but you want to see more options, +there is an easy solution hinted at below. + +.nf + Inspection Pause at pid ... + Use: left/right then <Enter> ... + Options: help 1 2 3 4 5 6 7 8 9 10 11 ... +.fi + +The entries in the \*(We rcfile would have a number for the `.name' element and +the `help' entry would identify a shell script you've written explaining what +those numbered selections actually mean. +In that way, many more choices can be made visible. + +.\" ...................................................................... +.SS 6c. SYSTEM Configuration File +.\" ---------------------------------------------------------------------- +This \*(CF represents defaults for users who have not saved their own \*(CF. +The format mirrors exactly the personal \*(CF and can also include `inspect' +entries as explained above. + +Creating it is a simple process. + +1. Configure \*(We appropriately for your installation and preserve that +configuration with the `W' \*(CI. + +2. Add and test any desired `inspect' entries. + +3. Copy that \*(CF to the \fI/etc/\fR directory as `\fBtopdefaultrc\fR'. + +.\" ...................................................................... +.SS 6d. SYSTEM Restrictions File +.\" ---------------------------------------------------------------------- +The presence of this file will influence which version of the help screen +is shown to an ordinary user. + +More importantly, it will limit what ordinary users are allowed +to do when \*(We is running. +They will not be able to issue the following commands. +.nf + k Kill a task + r Renice a task + d or s Change delay/sleep interval +.fi + +This \*(CF is not created by \*(We. +Rather, it is created manually and placed it in the \fI/etc/\fR +directory as `\fBtoprc\fR'. + +It should have exactly two lines, as shown in this example: +.nf + s # line 1: secure mode switch + 5.0 # line 2: delay interval in seconds +.fi + +.\" ---------------------------------------------------------------------- +.SH 7. ENVIRONMENT VARIABLE(S) +.\" ---------------------------------------------------------------------- +The value set for the following is unimportant, just its presence. + +.IP LIBPROC_HIDE_KERNEL +This will prevent display of any kernel threads and exclude such processes +from the \*(SA Tasks/Threads counts. + +.\" ---------------------------------------------------------------------- +.SH 8. STUPID TRICKS Sampler +.\" ---------------------------------------------------------------------- +Many of these tricks work best when you give \*(We a scheduling boost. +So plan on starting him with a nice value of \-10, assuming you've got +the authority. + +.\" ...................................................................... +.SS 7a. Kernel Magic +.\" ---------------------------------------------------------------------- +.\" sorry, just can't help it -- don't ya love the sound of this? +For these stupid tricks, \*(We needs \*(FM. +.\" ( apparently AM static was a potential concern ) + +.IP \(bu 3 +The user interface, through prompts and help, intentionally implies +that the delay interval is limited to tenths of a second. +However, you're free to set any desired delay. +If you want to see Linux at his scheduling best, try a delay of .09 +seconds or less. + +For this experiment, under x-windows open an xterm and maximize it. +Then do the following: +.nf + . provide a scheduling boost and tiny delay via: + nice -n -10 \*(We -d.09 + . keep sorted column highlighting \*F so as to + minimize path length + . turn \*O reverse row highlighting for emphasis + . try various sort columns (TIME/MEM work well), + and normal or reverse sorts to bring the most + active processes into view +.fi + +What you'll see is a very busy Linux doing what he's always done for you, +but there was no program available to illustrate this. + +.IP \(bu 3 +Under an xterm using `white-on-black' colors, on \*(We's Color Mapping screen +set the task color to black and be sure that task highlighting is set to bold, +not reverse. +Then set the delay interval to around .3 seconds. + +After bringing the most active processes into view, what you'll see are +the ghostly images of just the currently running tasks. + +.IP \(bu 3 +Delete the existing rcfile, or create a new symlink. +Start this new version then type `T' (a secret key, +\*(Xt 4c. Task Area Commands, SORTING) followed by `W' and `q'. +Finally, restart the program with \-d0 (zero delay). + +Your display will be refreshed at three times the rate of the former \*(We, +a 300% speed advantage. +As \*(We climbs the TIME ladder, be as patient as you can while speculating +on whether or not \*(We will ever reach the \*(We. + +.\" ...................................................................... +.SS 7b. Bouncing Windows +.\" ---------------------------------------------------------------------- +For these stupid tricks, \*(We needs \*(AM. + +.IP \(bu 3 +With 3 or 4 \*(TDs visible, pick any window other than the last +and turn idle processes \*F using the `i' \*(CT. +Depending on where you applied `i', sometimes several \*(TDs are bouncing and +sometimes it's like an accordion, as \*(We tries his best to allocate space. + +.IP \(bu 3 +Set each window's summary lines differently: one with no memory (`m'); another +with no states (`t'); maybe one with nothing at all, just the message line. +Then hold down `a' or `w' and watch a variation on bouncing windows \*(Em +hopping windows. + +.IP \(bu 3 +Display all 4 windows and for each, in turn, set idle processes to \*F using +the `i' \*(CT. +You've just entered the "extreme bounce" zone. + +.\" ...................................................................... +.SS 7c. The Big Bird Window +.\" ---------------------------------------------------------------------- +This stupid trick also requires \*(AM. + +.IP \(bu 3 +Display all 4 windows and make sure that 1:Def is the \*(CW. +Then, keep increasing window size with the `n' \*(CI until all the other +\*(TDs are "pushed out of the nest". + +When they've all been displaced, toggle between all visible/invisible windows +using the `_' \*(CT. +Then ponder this: +.br + is \*(We fibbing or telling honestly your imposed truth? + +.\" ...................................................................... +.SS 7d. The Ol' Switcheroo +.\" ---------------------------------------------------------------------- +This stupid trick works best without \*(AM, since justification is active +on a per window basis. + +.IP \(bu 3 +Start \*(We and make COMMAND the last (rightmost) column displayed. +If necessary, use the `c' \*(CT to display command lines and ensure +that forest view mode is active with the `V' \*(CT. + +Then use the up/down arrow keys to position the display so that some +truncated command lines are shown (`+' in last position). +You may have to resize your xterm to produce truncation. + +Lastly, use the `j' \*(CT to make the COMMAND column right justified. + +Now use the right arrow key to reach the COMMAND column. +Continuing with the right arrow key, watch closely the direction +of travel for the command lines being shown. + +.br + some lines travel left, while others travel right + + eventually all lines will Switcheroo, and move right + +.\" ---------------------------------------------------------------------- +.SH 9. BUGS +.\" ---------------------------------------------------------------------- +Please send bug reports to +.UR procps@freelists.org +.UE . + + \" ---------------------------------------------------------------------- +.SH 10. SEE Also +.\" ---------------------------------------------------------------------- +.BR free (1), +.BR ps (1), +.BR uptime (1), +.BR atop (1), +.BR slabtop (1), +.BR vmstat (8), +.BR w (1) diff --git a/man/uptime.1 b/man/uptime.1 new file mode 100644 index 0000000..eb8cc9f --- /dev/null +++ b/man/uptime.1 @@ -0,0 +1,74 @@ +.\" +.\" Copyright (c) 2011-2023 Craig Small <csmall@dropbear.xyz> +.\" Copyright (c) 2011-2023 Jim Warner <james.warner@comcast.net> +.\" Copyright (c) 2011-2012 Sami Kerola <kerolasa@iki.fi> +.\" Copyright (c) 2002 Albert Cahalan +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" +.TH UPTIME "1" "December 2012" "procps-ng" "User Commands" +.SH NAME +uptime \- Tell how long the system has been running. +.SH SYNOPSIS +.B uptime +[\fIoptions\fR] +.SH DESCRIPTION +.B uptime +gives a one line display of the following information. The current time, how +long the system has been running, how many users are currently logged on, and +the system load averages for the past 1, 5, and 15 minutes. +.PP +This is the same information contained in the header line displayed by +.BR w (1). +.PP +System load averages is the average number of processes that are either in a +runnable or uninterruptable state. A process in a runnable state is either +using the CPU or waiting to use the CPU. A process in uninterruptable state +is waiting for some I/O access, eg waiting for disk. The averages are taken +over the three time intervals. Load averages are not normalized for the +number of CPUs in a system, so a load average of 1 means a single CPU system +is loaded all the time while on a 4 CPU system it means it was idle 75% of +the time. +.SH OPTIONS +.TP +\fB\-p\fR, \fB\-\-pretty\fR +show uptime in pretty format +.TP +\fB\-h\fR, \fB\-\-help\fR +display this help text +.TP +\fB\-s\fR, \fB\-\-since\fR +system up since, in yyyy-mm-dd HH:MM:SS format +.TP +\fB\-V\fR, \fB\-\-version\fR +display version information and exit +.SH FILES +.TP +.I /var/run/utmp +information about who is currently logged on +.TP +.I /proc +process information +.SH AUTHORS +.B uptime +was written by +.UR greenfie@gauss.\:rutgers.\:edu +Larry Greenfield +.UE +and +.UR johnsonm@sunsite.\:unc.\:edu +Michael K. Johnson +.UE +.SH "SEE ALSO" +.BR ps (1), +.BR top (1), +.BR utmp (5), +.BR w (1) +.SH "REPORTING BUGS" +Please send bug reports to +.UR procps@freelists.org +.UE diff --git a/man/vmstat.8 b/man/vmstat.8 new file mode 100644 index 0000000..bfaba27 --- /dev/null +++ b/man/vmstat.8 @@ -0,0 +1,202 @@ +.\" +.\" Copyright (c) 2002-2023 Craig Small <csmall@dropbear.xyz> +.\" Copyright (c) 2012-2023 Jim Warner <james.warner@comcast.net> +.\" Copyright (c) 2011-2012 Sami Kerola <kerolasa@iki.fi> +.\" Copyright (c) 1994 Henry Ware <al172@yfn.ysu.edu> +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" +.TH VMSTAT 8 "2023-01-18" "procps-ng" "System Administration" +.SH NAME +vmstat \- Report virtual memory statistics +.SH SYNOPSIS +.B vmstat +[options] +.RI [ delay " [" count ]] +.SH DESCRIPTION +.B vmstat +reports information about processes, memory, paging, block IO, traps, disks +and cpu activity. +.PP +The first report produced gives averages since the last reboot. Additional +reports give information on a sampling period of length +.IR delay . +The process and memory reports are instantaneous in either case. +.SH OPTIONS +.TP +.I delay +The +.I delay +between updates in seconds. If no +.I delay +is specified, only one report is printed with the average values since boot. +.TP +.I count +Number of updates. In absence of +.IR count , +when +.I delay +is defined, default is infinite. +.TP +\fB\-a\fR, \fB\-\-active\fR +Display active and inactive memory, given a 2.5.41 kernel or better. +.TP +\fB\-f\fR, \fB\-\-forks\fR +The +.B \-f +switch displays the number of forks since boot. This includes the fork, +vfork, and clone system calls, and is equivalent to the total number of tasks +created. Each process is represented by one or more tasks, depending on +thread usage. This display does not repeat. +.TP +\fB\-m\fR, \fB\-\-slabs\fR +Displays slabinfo. +.TP +\fB\-n\fR, \fB\-\-one-header\fR +Display the header only once rather than periodically. +.TP +\fB\-s\fR, \fB\-\-stats\fR +Displays a table of various event counters and memory statistics. This +display does not repeat. +.TP +\fB\-d\fR, \fB\-\-disk\fR +Report disk statistics (2.5.70 or above required). +.TP +\fB\-D\fR, \fB\-\-disk-sum\fR +Report some summary statistics about disk activity. +.TP +\fB\-p\fR, \fB\-\-partition\fR \fIdevice\fR +Detailed statistics about partition (2.5.70 or above required). +.TP +\fB\-S\fR, \fB\-\-unit\fR \fIcharacter\fR +Switches outputs between 1000 +.RI ( k ), +1024 +.RI ( K ), +1000000 +.RI ( m ), +or 1048576 +.RI ( M ) +bytes. Note this does not change the swap (si/so) or block (bi/bo) +fields. +.TP +\fB\-t\fR, \fB\-\-timestamp\fR +Append timestamp to each line +.TP +\fB\-w\fR, \fB\-\-wide\fR +Wide output mode (useful for systems with higher amount of memory, +where the default output mode suffers from unwanted column breakage). +The output is wider than 80 characters per line. +.TP +\fB\-y\fR, \fB\-\-no-first\fR +Omits first report with statistics since system boot. +.TP +\fB\-V\fR, \fB\-\-version\fR +Display version information and exit. +.TP +\fB\-h\fR, \fB\-\-help\fR +Display help and exit. +.PD +.SH FIELD DESCRIPTION FOR VM MODE +.SS Procs +.nf +r: The number of runnable processes (running or waiting for run time). +b: The number of processes blocked waiting for I/O to complete. +.fi +.SS Memory +These are affected by the \fB\-\-unit\fR option. +.nf +swpd: the amount of swap memory used. +free: the amount of idle memory. +buff: the amount of memory used as buffers. +cache: the amount of memory used as cache. +inact: the amount of inactive memory. (\fB\-a\fR option) +active: the amount of active memory. (\fB\-a\fR option) +.fi +.SS Swap +These are affected by the \fB\-\-unit\fR option. +.nf +si: Amount of memory swapped in from disk (/s). +so: Amount of memory swapped to disk (/s). +.fi +.SS IO +.nf +bi: Kibibyte received from a block device (KiB/s). +bo: Kibibyte sent to a block device (KiB/s). +.fi +.SS System +.nf +in: The number of interrupts per second, including the clock. +cs: The number of context switches per second. +.fi +.SS CPU +These are percentages of total CPU time. +.nf +us: Time spent running non\-kernel code. (user time, including nice time) +sy: Time spent running kernel code. (system time) +id: Time spent idle. Prior to Linux 2.5.41, this includes IO\-wait time. +wa: Time spent waiting for IO. Prior to Linux 2.5.41, included in idle. +st: Time stolen from a virtual machine. Prior to Linux 2.6.11, unknown. +gu: Time spent running KVM guest code (guest time, including guest nice). +.fi +.SH FIELD DESCRIPTION FOR DISK MODE +.SS Reads +.nf +total: Total reads completed successfully +merged: grouped reads (resulting in one I/O) +sectors: Sectors read successfully +ms: milliseconds spent reading +.fi +.SS Writes +.nf +total: Total writes completed successfully +merged: grouped writes (resulting in one I/O) +sectors: Sectors written successfully +ms: milliseconds spent writing +.fi +.SS IO +.nf +cur: I/O in progress +s: seconds spent for I/O +.fi +.SH FIELD DESCRIPTION FOR DISK PARTITION MODE +.nf +reads: Total number of reads issued to this partition +read sectors: Total read sectors for partition +writes : Total number of writes issued to this partition +requested writes: Total number of write requests made for partition +.fi +.SH FIELD DESCRIPTION FOR SLAB MODE +Slab mode shows statistics per slab, for more information +about this information see +.BR slabinfo (5) +.PP +.nf +cache: Cache name +num: Number of currently active objects +total: Total number of available objects +size: Size of each object +pages: Number of pages with at least one active object +.fi +.SH NOTES +.B vmstat +requires read access to files under \fI/proc\fR. The \fB\-m\fR requires read +access to \fI/proc/slabinfo\fR which may not be available to standard users. +Mount options for \fI/proc\fR such as \fIsubset=pid\fR may also impact what +is visible. +.SH "SEE ALSO" +.BR free (1), +.BR iostat (1), +.BR mpstat (1), +.BR ps (1), +.BR sar (1), +.BR top (1), +.BR slabinfo (5) +.SH "REPORTING BUGS" +Please send bug reports to +.UR procps@freelists.org +.UE @@ -0,0 +1,115 @@ +.\" +.\" Copyright (c) 2009-2023 Craig Small <csmall@dropbear.xyz> +.\" Copyright (c) 2015-2023 Jim Warner <james.warner@comcast.net> +.\" Copyright (c) 2012-2013 Jaromir Capik <jcapik@redhat.com> +.\" Copyright (c) 2011-2012 Sami Kerola <kerolasa@iki.fi> +.\" Copyright (c) 2002-2004 Albert Cahalan +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" +.TH W "1" "2023-01-15" "procps-ng" "User Commands" +.SH NAME +w \- Show who is logged on and what they are doing. +.SH SYNOPSIS +.B w +[\fIoptions\fR] [\fIuser\fR] +.SH DESCRIPTION +.B w +displays information about the users currently on the machine, and their +processes. The header shows, in this order, the current time, how long the +system has been running, how many users are currently logged on, and the +system load averages for the past 1, 5, and 15 minutes. +.PP +The following entries are displayed for each user: login name, the tty name, +the remote host, login time, idle time, JCPU, PCPU, and the command line of +their current process. +.PP +The JCPU time is the time used by all processes attached to the tty. It does +not include past background jobs, but does include currently running +background jobs. +.PP +The PCPU time is the time used by the current process, named in the "what" +field. +.SH "COMMAND\-LINE OPTIONS" +.TP +\fB\-h\fR, \fB\-\-no\-header\fR +Don't print the header. +.TP +\fB\-u\fR, \fB\-\-no\-current\fR +Ignores the username while figuring out the +current process and cpu times. To demonstrate this, do a +.B su +and do a +.B w +and a +.BR "w \-u". +.TP +\fB\-s\fR, \fB\-\-short\fR +Use the short format. Don't print the login time, JCPU or PCPU times. +.TP +\fB\-f\fR, \fB\-\-from\fR +Toggle printing the +.B from +(remote hostname) field. The default as released is for the +.B from +field to not be printed, although your system administrator or distribution +maintainer may have compiled a version in which the +.B from +field is shown by default. +.TP +\fB\-\-help\fR +Display help text and exit. +.TP +\fB\-i\fR, \fB\-\-ip\-addr\fR +Display IP address instead of hostname for \fBfrom\fR field. +.TP +\fB\-p\fR, \fB\-\-pids\fR +Display pid of the login process/the "what" process in the "what" field. +.TP +\fB\-V\fR, \fB\-\-version\fR +Display version information. +.TP +\fB\-o\fR, \fB\-\-old\-style\fR +Old style output. Prints blank space for idle times less than one minute. +.TP +.B "user " +Show information about the specified user only. +.SH ENVIRONMENT +.TP +PROCPS_USERLEN +Override the default width of the username column. Defaults to 8. +.TP +PROCPS_FROMLEN +Override the default width of the from column. Defaults to 16. +.SH FILES +.TP +.I /var/run/utmp +information about who is currently logged on +.TP +.I /proc +process information +.SH "SEE ALSO" +.BR free (1), +.BR ps (1), +.BR top (1), +.BR uptime (1), +.BR utmp (5), +.BR who (1) +.SH AUTHORS +.B w +was re-written almost entirely by Charles Blake, based on the version by +.UR greenfie@\:gauss.\:rutgers.\:edu +Larry Greenfield +.UE +and +.UR johnsonm@\:redhat.\:com +Michael K. Johnson +.UE +.SH "REPORTING BUGS" +Please send bug reports to +.UR procps@freelists.org +.UE diff --git a/man/watch.1 b/man/watch.1 new file mode 100644 index 0000000..01685e6 --- /dev/null +++ b/man/watch.1 @@ -0,0 +1,232 @@ +.\" +.\" Copyright (c) 2009-2023 Craig Small <csmall@dropbear.xyz> +.\" Copyright (c) 2018-2023 Jim Warner <james.warner@comcast.net> +.\" Copyright (c) 2011-2012 Sami Kerola <kerolasa@iki.fi> +.\" Copyright (c) 2003 Albert Cahalan +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" +.TH WATCH 1 "2023-01-17" "procps-ng" "User Commands" +.SH NAME +watch \- execute a program periodically, showing output fullscreen +.SH SYNOPSIS +.B watch +[\fIoptions\fR] \fIcommand\fR +.SH DESCRIPTION +.B watch +runs +.I command +repeatedly, displaying its output and errors (the first screenfull). This +allows you to watch the program output change over time. By default, +\fIcommand\fR is run every 2 seconds and \fBwatch\fR will run until interrupted. +.SH OPTIONS +.TP +\fB\-b\fR, \fB\-\-beep\fR +Beep if command has a non-zero exit. +.TP +\fB\-c\fR, \fB\-\-color\fR +Interpret ANSI color and style sequences. +.TP +\fB\-C\fR, \fB\-\-no-color\fR +Do not interpret ANSI color and style sequences. +.TP +\fB\-d\fR, \fB\-\-differences\fR[=\fIpermanent\fR] +Highlight the differences between successive updates. If the optional +\fIpermanent\fR argument is specified then +.B watch +will show all changes since the first iteration. +.TP +\fB\-e\fR, \fB\-\-errexit\fR +Freeze updates on command error, and exit after a key press. +.TP +\fB\-g\fR, \fB\-\-chgexit\fR +Exit when the output of +.I command +changes. +.TP +\fB\-n\fR, \fB\-\-interval\fR \fIseconds\fR +Specify update interval. The command will not allow quicker than 0.1 second +interval, in which the smaller values are converted. Both '.' and ',' work +for any locales. The \fBWATCH_INTERVAL\fR environment can be used to persistently +set a non-default interval (following the same rules and formatting). +.TP +\fB\-p\fR, \fB\-\-precise\fR +Make +.BR watch +attempt to run +.I command +every +.B \-\-interval +.IR seconds . +Try it with +.B ntptime +(if present) and notice how the fractional seconds stays (nearly) the same, as opposed to +normal mode where they continuously increase. +.TP +\fB\-q\fR, \fB\-\-equexit\fR <cycles> +Exit when output of +.I command +does not change for the given number of cycles. +.TP +\fB\-r\fR, \fB\-\-no-rerun\fR +Do not run the program on terminal resize, the output of the program will re-appear at the next +regular run time. +.TP +\fB\-t\fR, \fB\-\-no\-title\fR +Turn off the header showing the interval, command, and current time at the +top of the display, as well as the following blank line. +.TP +\fB\-w\fR, \fB\-\-no\-wrap\fR +Turn off line wrapping. Long lines will be truncated instead of wrapped to the next line. +.TP +\fB\-x\fR, \fB\-\-exec\fR +Pass +.I command +to +.BR exec (2) +instead of +.B sh \-c +which reduces the need to use extra quoting to get the desired effect. +.TP +\fB\-h\fR, \fB\-\-help\fR +Display help text and exit. +.TP +\fB\-v\fR, \fB\-\-version\fR +Display version information and exit. +.SH "EXIT STATUS" +.PP +.RS +.PD 0 +.TP +.B 0 +Success. +.TP +.B 1 +Various failures. +.TP +.B 2 +Forking the process to watch failed. +.TP +.B 3 +Replacing child process stdout with write side pipe failed. +.TP +.B 4 +Command execution failed. +.TP +.B 5 +Closing child process write pipe failed. +.TP +.B 7 +IPC pipe creation failed. +.TP +.B 8 +Getting child process return value with +.BR waitpid (2) +failed, or command exited up on error. +.TP +.B other +The watch will propagate command exit status as child exit status. +.SH ENVIRONMENT +The behavior of +.B watch +is affected by the following environment variables. + +.TP +.B WATCH_INTERVAL +Update interval, follows the same rules as the +.B \-\-interval +command line option. +.sp +.SH NOTES +POSIX option processing is used (i.e., option processing stops at +the first non\-option argument). This means that flags after +.I command +don't get interpreted by +.BR watch +itself. +.sp +.SH BUGS +Upon terminal resize, the screen will not be correctly repainted until the +next scheduled update. All +.B \-\-differences +highlighting is lost on that update as well. When using the +.B \-\-no\-rerun +option, no output of will be visible. + +Non-printing characters are stripped from program output. Use \fBcat -v\fR as +part of the command pipeline if you want to see them. + +Combining Characters that are supposed to display on the character at the +last column on the screen may display one column early, or they may not +display at all. + +Combining Characters never count as different in +.B \-\-differences +mode. Only the base character counts. + +Blank lines directly after a line which ends in the last column do not +display. + +.B \-\-precise +mode doesn't yet have advanced temporal distortion technology to compensate +for a +.I command +that takes more than +.B \-\-interval +.I seconds +to execute. +.B watch +also can get into a state where it rapid-fires as many executions of +.I command +as it can to catch up from a previous executions running longer than +.B \-\-interval +(for example, +.BR netstat (8) +taking ages on a DNS lookup). +.sp +.SH EXAMPLES +.PP +To watch for mail, you might do +.IP +watch \-n 60 from +.PP +To watch the contents of a directory change, you could use +.IP +watch \-d ls \-l +.PP +If you're only interested in files owned by user joe, you might use +.IP +watch \-d 'ls \-l | fgrep joe' +.PP +To see the effects of quoting, try these out +.IP +watch echo $$ +.br +watch echo '$$' +.br +watch echo "'"'$$'"'" +.PP +To see the effect of precision time keeping, try adding +.B \-p +to +.IP +watch \-n 10 sleep 1 +.PP +You can watch for your administrator to install the latest kernel with +.IP +watch uname \-r +.PP +(Note that +.B \-p +isn't guaranteed to work across reboots, especially in the face of +.B ntpdate +(if present) or other bootup time-changing mechanisms) +.sp +.SH "REPORTING BUGS" +Please send bug reports to +.UR procps@freelists.org +.UE |