emo/procps
1
0
Fork 0
Code Issues Pull Requests Packages Releases Activity

top: update man document with new long cmdline options

Browse Source 
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit is contained in:
Jim Warner 2021-09-05 00:00:00 -05:00 committed by Craig Small
parent 016ddc6bff
commit dbc6532128
1 changed files with 87 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

166
top/top.1
View File

@ -23,10 +23,6 @@
.ds CF configuration file
.ds CG `current' window/field group
.ds CI interactive command
\# - Note: our 'Command Line' used in 2 places
\# ( and managed to fit in an 80x24 terminal )
.ds CL \-\fBhv\fR|\-\fBbcEeHiOSs1\fR \-\fBd\fR secs \-\fBn\fR max \
\-\fBu\fR|\fBU\fR user \-\fBp\fR pids \-\fBo\fR field \-\fBw\fR [cols] \fR
.ds CO command\-line option
.ds CT command toggle
.ds CW `current' window
@ -61,7 +57,7 @@
.
.\" Document /////////////////////////////////////////////////////////////
.\" ----------------------------------------------------------------------
.TH TOP 1 "August 2021" "procps-ng" "User Commands"
.TH TOP 1 "September 2021" "procps-ng" "User Commands"
.\" ----------------------------------------------------------------------
.nh
@ -73,9 +69,7 @@ top \- display Linux processes
.\" ----------------------------------------------------------------------
.SH SYNOPSIS
.\" ----------------------------------------------------------------------
\*(WE \*(CL
The traditional switches `\-' and whitespace are optional.
\*(WE [options]
.\" ----------------------------------------------------------------------
.SH DESCRIPTION
@ -297,33 +291,27 @@ as scalable columns and discussed under topic `3a. DESCRIPTIONS of Fields'.
.\" ----------------------------------------------------------------------
.SH 1. COMMAND-LINE Options
.\" ----------------------------------------------------------------------
The command-line syntax for \*(We consists of:
Mandatory\fI arguments\fR to long options are mandatory for short
options too.
The equals sign can be used with either option form and whitespace
before and/or after the `=' is permitted.
\*(CL
The typically mandatory switch (`\-') and even whitespace are completely
optional.
.TP 5
\-\fBh\fR | \-\fBv\fR\ \ :\fIHelp/Version \fR
Show library version and the usage prompt, then quit.
.TP 5
\-\fBb\fR\ \ :\fIBatch-mode\fR operation \fR
.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 5
\-\fBc\fR\ \ :\fICommand-line/Program-name\fR toggle \fR
.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 5
\-\fBd\fR\ \ :\fIDelay-time\fR interval as:\ \ \fB-d ss.t\fR (\fIsecs\fR.\fItenths\fR) \fR
.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.
@ -333,21 +321,8 @@ 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 5
\-\fBe\fR\ \ :\fIEnforce-Task-Memory-Scaling\fR as:\ \ \fB-e k\fR | \fBm\fR | \fBg\fR | \fBt\fR | \fBp\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 5
\-\fBE\fR\ \ :\fIEnforce-Summary-Memory-Scaling\fR as:\ \ \fB-E k\fR | \fBm\fR | \fBg\fR | \fBt\fR | \fBp\fR | \fBe\fR
.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
@ -360,45 +335,64 @@ Instructs \*(We to force \*(SA memory to be scaled as:
Later this can be changed with the `E' \*(CT.
.TP 5
\-\fBH\fR\ \ :\fIThreads-mode\fR operation \fR
.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 5
\-\fBi\fR\ \ :\fIIdle-process\fR toggle \fR
.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 5
\-\fBn\fR\ \ :\fINumber-of-iterations\fR limit as:\fB\ \ \-n number \fR
.TP 3
\-\fBn\fR, \fB\-\-iterations\fR = \fINUMBER\fR
Specifies the maximum number of iterations, or frames, \*(We should
produce before ending.
.TP 5
\-\fBo\fR\ \ :\fIOverride-sort-field\fR as:\fB\ \ \-o fieldname \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 5
\-\fBO\fR\ \ :\fIOutput-field-names \fR
This option acts as a form of help for the above \-o option.
.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 5
\-\fBp\fR\ \ :\fIMonitor-PIDs\fR mode as:\fB\ \ \-pN1 -pN2 ...\fR\ \ or\fB\ \ \-pN1,N2,N3 ... \fR
.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.
@ -416,32 +410,46 @@ of these \*(CIs: `=', `u' or `U'.
The `p', `u' and `U' \*(COs are mutually exclusive.
.TP 5
\-\fBs\fR\ \ :\fISecure-mode\fR operation \fR
Starts \*(We with secure mode forced, even for root.
This mode is far better controlled through a system \*(CF
(\*(Xt 6. FILES).
.TP 5
\-\fBS\fR\ \ :\fICumulative-time\fR toggle \fR
.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 5
\-\fBu\fR | \-\fBU\fR\ \ :\fIUser-filter-mode\fR as:\ \ \fB-u\fR | \fB-U number\fR or\fB name \fR
.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.
The `\-u' option matches on \fI effective\fR user whereas the `\-U' option
matches on\fI any\fR user (real, effective, saved, or filesystem).
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.
The `p', `U' and `u' \*(COs are mutually exclusive.
.TP 5
\-\fBw\fR\ \ :\fIOutput-width-override\fR as:\ \ \fB-w\fR [\fB number\fR ] \fR
.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
Show library version, 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.
@ -452,13 +460,13 @@ 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.
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 5
\-\fB1\fR\ \ :\fISingle/Separate-Cpu-States\fR toggle \fR
.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