src/usr.bin/top/top.1 - diff

Return to top.1 CVS log

Up to [local] / src / usr.bin / top

Diff for /src/usr.bin/top/top.1 between version 1.12 and 1.13

version 1.12, 1999/10/17 20:24:36

version 1.13, 2000/03/11 21:40:05

Line 47

.Sh DESCRIPTION

.Nm

displays the top processes on the system and periodically updates this

information. If standard output is an intelligent terminal (see below) then

information.

If standard output is an intelligent terminal (see below) then

as many processes as will fit on the terminal screen are displayed

by default. Otherwise, a good number of them are shown (around 20).

by default.

Raw CPU percentage is used to rank the processes. If

Otherwise, a good number of them are shown (around 20).

Raw CPU percentage is used to rank the processes.

.Ar number

is given, then the top

.Ar number

Line 58

Line 61

.Pp

.Nm

makes a distinction between terminals that support advanced capabilities

and those that do not. This

and those that do not.

distinction affects the choice of defaults for certain options. In the

This distinction affects the choice of defaults for certain options.

remainder of this document, an

In the remainder of this document, an

.Em intelligent

terminal is one that supports cursor addressing, clear screen, and clear

to end of line. Conversely, a

to end of line.

.Em dumb

Conversely, a

terminal is one that does not support such features. If the output of

.Dq dumb

terminal is one that does not support such features.

If the output of

.Nm

is redirected to a file, it acts as if it were being run on a dumb

terminal.

Line 73

Line 78

The options are as follows:

.Bl -tag -width XxXXXXXXXXX

.It Fl S

Show system processes in the display. Normally, system processes such as

Show system processes in the display.

the pager and the swapper are not shown. This option makes them visible.

Normally, system processes such as the pager and the swapper are not shown.

This option makes them visible.

.It Fl b

Use

.Em batch

mode. In this mode, all input from the terminal is

mode.

ignored. Interrupt characters (such as ^C and ^\e) still have an effect.

In this mode, all input from the terminal is ignored.

Interrupt characters (such as

.Ql ^C

and

.Ql ^\e )

still have an effect.

This is the default on a dumb terminal, or when the output is not a terminal.

.It Fl i

Use

.Em interactive

mode. In this mode, any input is immediately read for processing. See the

mode.

section on

In this mode, any input is immediately read for processing.

See the section on

.Sx INTERACTIVE MODE

for an explanation of which keys perform what functions. After the command

for an explanation of which keys perform what functions.

After the command

is processed, the screen will immediately be updated, even if the command was

not understood. This mode is the default when standard output is an

not understood.

intelligent terminal.

This mode is the default when standard output is an intelligent terminal.

.It Fl I

Do not display idle processes.

By default, top displays both active and idle processes.

.It Fl n

Use

.Em non-interactive

mode. This is identical to

mode.

This is identical to

.Em batch

mode.

.It Fl q

Renice

.Nm

to -20 so that it will run faster. This can be used when the system is

to -20 so that it will run faster.

This can be used when the system is

being very sluggish to improve the possibility of discovering the problem.

This option can only be used by root.

.It Fl u

Do not take the time to map UID numbers to usernames. Normally,

Do not take the time to map UID numbers to usernames.

Normally,

.Nm

will read as much of the password database as is necessary to map

all the user ID numbers it encounters into login names. This option

all the user ID numbers it encounters into login names.

disables all that, while possibly decreasing execution time. The UID

This option

numbers are displayed instead of the names.

disables all that, while possibly decreasing execution time.

The UID numbers are displayed instead of the names.

.It Fl d Ar count

Show only

.Ar count

displays, then exit. A display is considered to be one update of the

displays, then exit.

screen. This option allows the user to select the number of displays

A display is considered to be one update of the screen.

This option allows the user to select the number of displays

to be shown before

.Nm

automatically exits. For intelligent terminals, no upper limit

automatically exits.

is set. The default is 1 for dumb terminals.

For intelligent terminals, no upper limit is set.

The default is 1 for dumb terminals.

.It Fl s Ar time

Set the delay between screen updates to

.Ar time

seconds. The default delay between updates is 5 seconds.

seconds.

The default delay between updates is 5 seconds.

.It Fl o Ar field

Sort the process display area using the specified field as the primary

Sort the process display area using the specified field as the primary key.

key. The field name is the name of the column as seen in the output,

The field name is the name of the column as seen in the output,

but in lower case. The

but in lower case.

The

.Ox

version of top supports

.Ar cpu ,

Line 151

Line 172

.Ar number

fields can be specified as

.Li infinite ,

indicating that they can stretch as far as possible. This is accomplished

indicating that they can stretch as far as possible.

by using any proper prefix of the keywords

This is accomplished by using any proper prefix of the keywords

.Li infinity ,

.Li maximum ,

Line 164

Line 185

.Pp

The environment variable

.Ev TOP

is examined for options before the command line is scanned. This enables

is examined for options before the command line is scanned.

a user to set his or her own defaults. The number of processes to display

This enables a user to set his or her own defaults.

The number of processes to display

can also be specified in the environment variable

.Ev TOP .

.Pp

Line 174

Line 196

.Fl S ,

and

.Fl u

are actually toggles. A second specification of any of these options

are actually toggles.

will negate the first. Thus a user who has the environment variable

A second specification of any of these options

will negate the first.

Thus a user who has the environment variable

.Ev TOP

set to

.Dq -I

Line 187

Line 211

.Nm

is running in

.Em interactive mode ,

it reads commands from the terminal and acts upon them accordingly. In this

it reads commands from the terminal and acts upon them accordingly.

mode, the terminal is put in

In this mode, the terminal is put in

.Dv CBREAK ,

so that a character will be processed as soon as it is typed. Almost always,

so that a character will be processed as soon as it is typed.

a key will be pressed when

Almost always, a key will be pressed when

.Nm

is between displays; that is, while it is waiting for

.Ar time

seconds to elapse. If this is the case, the command will be

seconds to elapse.

If this is the case, the command will be

processed and the display will be updated immediately thereafter

(reflecting any changes that the command may have specified). This

(reflecting any changes that the command may have specified).

happens even if the command was incorrect. If a key is pressed while

This happens even if the command was incorrect.

If a key is pressed while

.Nm

is in the middle of updating the display, it will finish the update and

then process the command. Some commands require additional information,

then process the command.

and the user will be prompted accordingly. While typing this information

Some commands require additional information,

and the user will be prompted accordingly.

While typing this information

in, the user's erase and kill keys (as set up by the command

.Xr stty 1 )

are recognized, and a newline terminates the input.

Line 231

Line 259

.It k

Send a signal

.Ns ( Dv TERM

by default) to a list of processes. This acts similarly to the command

by default) to a list of processes.

This acts similarly to the command

.Xr kill 1 .

.It r

Change the priority (the

.Em nice )

of a list of processes. This acts similarly to the command

of a list of processes.

This acts similarly to the command

.Xr renice 8 .

.It u

Display only processes owned by a specific username (prompt for username).

Line 272

Line 302

It also includes information about physial and virtual memory allocation.

.Pp

The remainder of the screen displays information about individual

processes. This display is similar in spirit to

processes.

This display is similar in spirit to

.Xr ps 1

but it is not exactly the same. PID is the process ID, USERNAME is the name

but it is not exactly the same.

PID is the process ID, USERNAME is the name

of the process's owner (if

.Fl u

is specified, a UID column will be substituted for USERNAME),

Line 306

Line 338

.Em ABANDONED

state (known in the kernel as

.Em SWAIT Ns )

was abandoned, thus the name. A process should never end up in this state.

was abandoned, thus the name.

A process should never end up in this state.

.Sh AUTHOR

William LeFebvre, EECS Department, Northwestern University

.Sh ENVIRONMENT

Line 322

Line 355

physical memory

.It Pa /bsd

kernel image

.Sh SEE ALSO

.Xr kill 1 ,

.Xr ps 1 ,

.Xr stty 1 ,

.Xr systat 1 ,

.Xr mem 4 ,

.Xr renice 8

.Sh BUGS

Don't shoot me, but the default for

.Fl I

has changed once again. So many people were confused by the fact that

has changed once again.

So many people were confused by the fact that

.Nm

wasn't showing them all the processes that I have decided to make the

default behavior show idle processes, just like it did in version 2.

Line 336

Line 377

.Ev TOP

(see the

.Sx OPTIONS

section). Those who want the behavior that version 3.0 had need only set

section).

Those who want the behavior that version 3.0 had need only set

the environment variable

.Ev TOP

Line 349

Line 391

.Xr ps 1 ,

things can change while

.Nm

is collecting information for an update. The picture it gives is only a

is collecting information for an update.

The picture it gives is only a

close approximation to reality.

.Sh SEE ALSO

.Xr kill 1 ,

.Xr ps 1 ,

.Xr stty 1 ,

.Xr systat 1 ,

.Xr mem 4 ,

.Xr renice 8