diff options
Diffstat (limited to 'static/freebsd/man1/top.1')
| -rw-r--r-- | static/freebsd/man1/top.1 | 539 |
1 files changed, 539 insertions, 0 deletions
diff --git a/static/freebsd/man1/top.1 b/static/freebsd/man1/top.1 new file mode 100644 index 00000000..9b186024 --- /dev/null +++ b/static/freebsd/man1/top.1 @@ -0,0 +1,539 @@ +.Dd June 9, 2025 +.Dt TOP 1 +.Os +.Sh NAME +.Nm top +.Nd display and update information about the top cpu processes +.Sh SYNOPSIS +.Nm +.Op Fl abCHIijnPqSTtuvwz +.Op Fl d Ar count +.Op Fl J Ar jail +.Op Fl m Ar cpu | io +.Op Fl o Ar field +.Op Fl p Ar pid +.Op Fl s Ar time +.Op Fl U Ar username +.Op Ar number +.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 +as many processes as will fit on the terminal screen are displayed +by default. +Otherwise, a good number of them are shown (around 20). +Raw cpu percentage is used to rank the processes. +If +.Ar number +is given, then the top +.Ar number +processes will be displayed instead of the default. +.Pp +.Nm +makes a distinction between terminals that support advanced capabilities +and those that do not. +This distinction affects the choice of defaults for certain options. +In the remainder of this document, an +.Dq intelligent +terminal is one that +supports cursor addressing, clear screen, and clear to end of line. +Conversely, a +.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. +.Pp +The options are as follows: +.Bl -tag -width indent +.It Fl a +Display command names derived from the argv[] vector, rather than real +executable name. +It it useful when you want to watch applications, that +puts their status information there. +If the real name differs from argv[0], +it will be displayed in parenthesis. +Non-printable characters in the command line are +encoded in C-style backslash sequences or +a three digit octal sequences. +.It Fl b +Use +.Dq batch +mode. +In this mode, all input from the terminal is +ignored. +Interrupt characters (such as ^C and ^\e) still have an effect. +This is the default on a dumb terminal, or when the output is not a terminal. +.It Fl C +Toggle CPU display mode. +By default top displays the weighted CPU percentage in the WCPU column +(this is the same value that +.Xr ps 1 +displays as CPU). +Each time +.Fl C +flag is passed it toggles between +.Dq raw cpu +mode and +.Dq weighted cpu +mode, showing the +.Dq CPU +or the +.Dq WCPU +column respectively. +.It Fl d Ar count +Show only +.Ar count +displays, then exit. +A display is considered to be one update of the +screen. +The default is 1 for dumb terminals. +Note that for +.Ar count += 1 +no information is available about the percentage of time spent by the CPU in every state. +.It Fl H +Display each thread for a multithreaded process individually. +By default a single summary line is displayed for each process. +.It Fl I +Do not display idle processes. +By default, top displays both active and idle processes. +.It Fl i +Use +.Dq interactive +mode. +In this mode, any input is immediately +read for processing. +See the section on +.Dq Interactive Mode +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 +intelligent terminal. +.It Fl J Ar jail +Show only those processes owned by +.Ar jail . +This may be either the +.Ar jid +or +.Ar name +of the jail. +Use +0 +to limit to host processes. +Using this option implies +.Fl j . +.It Fl j +Display the +.Xr jail 8 +ID. +.It Fl m Ar mode +Display statistics in the specified +.Ar mode . +Available modes are +.Cm cpu +and +.Cm io . +Default is +.Cm cpu . +.It Fl n +Use +.Dq non-interactive +mode. +This is identical to +.Dq batch +mode. +.It Fl o Ar field +Sort the process display area on the specified field. +The field name +is the name of the column as seen in the output, but in lower case: +.Dq cpu , +.Dq size , +.Dq res , +.Dq time , +.Dq pri , +.Dq threads , +.Dq total , +.Dq read , +.Dq write , +.Dq fault , +.Dq vcsw , +.Dq ivcsw , +.Dq jid , +.Dq swap , +or +.Dq pid . +.It Fl P +Display per-cpu CPU usage statistics. +.It Fl p Ar pid +Show only the process +.Ar pid . +.It Fl q +Renice +.Nm +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 S +Show system processes in the display. +Normally, system processes such as the pager and the swapper are not shown. +This option makes them visible. +.It Fl s Ar time +Set the delay between screen updates to +.Ar time +seconds, which may be fractional. +The default delay between updates is 2 seconds. +.It Fl T +Toggle displaying thread ID (tid) instead of process id (pid). +.It Fl t +Do not display the +.Nm +process itself. +.It Fl U Ar username +Show only those processes owned by +.Ar username . +This option currently only accepts usernames and will not understand +uid numbers. +.It Fl u +Do not map uid numbers to usernames. +Normally, +.Nm +will read as much of the file +.Pa /etc/passwd +as is necessary to map +all the user id numbers it encounters into login names. +This option disables all that, while possibly decreasing execution time. +The uid numbers are displayed instead of the names. +.It Fl v +Write version number information to stderr then exit immediately. +.It Fl w +Display approximate swap usage for each process. +.It Fl z +Do not display the system idle process. +.El +.Pp +Both +.Ar count +and +.Ar number +fields can be specified as +.Dq infinite , +indicating that they can +stretch as far as possible. +This is accomplished by using any proper +prefix of the keywords +.Dq infinity , +.Dq maximum , +or +.Dq all . +Boolean flags are toggles. +A second specification of any of these options will negate the first. +.Sh INTERACTIVE MODE +When +.Nm +is running in +.Dq interactive mode , +it reads commands from the +terminal and acts upon them accordingly. +In this mode, the terminal is +put in +.Dq CBREAK , +so that a character will be +processed as soon as it is typed. +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 +processed and the display will be updated immediately thereafter +.Pq reflecting any changes that the command may have specified . +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, +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. +.Pp +The bindings are as follows: +.Bl -tag -width indent +.It Ic space +Update the display. +.It Ic / +Filter by command name. +Prompt for +.Ar string +or +.Ql Ic + +to show all processes. +.It Ic a +Toggle display of process titles. +.It Ic C +Toggle display of raw or weighted CPU percentage. +.It Ic d +Change the number of remaining displays to show before exit. +Prompt for new number. +.It Ic e +Display a list of system errors (if any) generated by the last command. +.It Ic H +Toggle display of threads. +.It Ic h No or Ic \&? +Display a summary of the commands (help screen) and version information. +.It Ic i No or Ic I +Toggle display of idle processes. +.It Ic J +Filter processes owned by a specific jail. +Prompt for jail name or +.Ql Ic + +for all processes belonging to all jails and the host. +This will also enable the display of JID. +.It Ic j +Toggle display of +.Xr jail 8 +ID. +.It Ic k +Send a signal +.Pq SIGKILL by default +to a list of processes. +This acts similarly to the command +.Xr kill 1 . +.It Ic m +Toggle the display between 'cpu' and 'io' modes. +.It Ic n No or Ic # +Change the number of processes to display. +Prompt for new number. +.It Ic o +Change the order in which the display is sorted. +The sort key names include +.Dq cpu , +.Dq res , +.Dq size , +and +.Dq time. +The default is cpu. +.It Ic P +Toggle display of per-CPU statistics. +.It Ic p +Filter by exact process ID. +Prompt for +.Ar PID +or +.Ql Ic + +to show all processes. +.It Ic q +Quit +.Nm . +.It Ic r +Change the priority +.Pq the Dq nice +of a list of processes. +This acts similarly to +.Xr renice 8 . +.It Ic S +Toggle the display of system processes. +.It Ic s +Change the number of seconds to delay between displays. +Prompt for new number. +.It Ic T +Toggle display between thread ID and process ID. +.It Ic t +Toggle display of the +.Nm +process. +.It Ic u +Filter by exact process owner username. +Prompt for +.Ar username +or +.Ql Ic - Ns +.No / Ns +.Ql Ic + +for all users. +Usernames can be added +to and removed from the set by prepending them with +.Ql + +and +.Ql - , +respectively. +.It Ic w +Toggle display of swap usage. +.It Ic z +Toggle display of the system idle process. +.El +.Sh "THE DISPLAY" +The top few lines of the display show general information +about the state of the system, including +the last process id assigned to a process (on most systems), +the three load averages, +the current time, +the number of existing processes, +the number of processes in each state +(sleeping, running, starting, zombies, and stopped), +and a percentage of time spent in each of the processor states +(user, nice, system, and idle). +It also includes information about physical and virtual memory allocation. +.Pp +The remainder of the screen displays information about individual +processes. +This display is similar in spirit to +.Xr ps 1 +but it is not exactly the same. +PID is the process id, +JID, when displayed, is the +.Xr jail 8 +ID corresponding to the process, +USERNAME is the name of the process's owner (if +.Fl u +is specified, a UID column will be substituted for USERNAME), +THR is the thread count, showing the number of threads a process has, +PRI is the current priority of the process, +NICE is the +.Xr nice 1 +amount, +SIZE is the total size of the process (text, data, and stack), +RES is the current amount of resident memory, +SWAP is the approximate amount of swap, if enabled +(SIZE, RES and SWAP are given in kilobytes), +STATE is the current state (one of +.Dq START , +.Dq RUN +(shown as +.Dq CPUn +on SMP systems), +.Dq SLEEP , +.Dq STOP , +.Dq ZOMB , +.Dq WAIT , +.Dq LOCK , +or the event on which the process waits), +C is the processor number on which the process is executing +(visible only on SMP systems), +TIME is the number of system and user cpu seconds that the process has used, +WCPU, when displayed, is the weighted cpu percentage (this is the same +value that +.Xr ps 1 +displays as CPU), +CPU is the raw percentage and is the field that is sorted to determine +the order of the processes, and +COMMAND is the name of the command that the process is currently running +(if the process is swapped out, this column is marked +.Dq <swapped> ) . +.Pp +If a process is in the +.Dq SLEEP +or +.Dq LOCK +state, +the state column will report the name of the event or lock on which the +process is waiting. +Lock names are prefixed with an asterisk +.Dq * +while sleep events +are not. +.Sh DESCRIPTION OF MEMORY +.Bd -literal +Mem: 61M Active, 86M Inact, 368K Laundry, 22G Wired, 102G Free +ARC: 15G Total, 9303M MFU, 6155M MRU, 1464K Anon, 98M Header, 35M Other + 15G Compressed, 27G Uncompressed, 1.75:1 Ratio, 174M Overhead +Swap: 4096M Total, 532M Free, 13% Inuse, 80K In, 104K Out +.Ed +.Ss Physical Memory Stats +.Bl -tag -width "Uncompressed" -compact +.It Em Active +number of bytes active +.It Em Inact +number of clean bytes inactive +.It Em Laundry +number of dirty bytes queued for laundering +.It Em Wired +number of bytes wired down, including IO-level cached file data pages +.It Em Buf +number of bytes used for IO-level disk caching +.It Em Free +number of bytes free +.El +.Ss ZFS ARC Stats +These stats are only displayed when the ARC is in use. +.Pp +.Bl -tag -width "Uncompressed" -compact +.It Em Total +number of wired bytes used for the ZFS ARC +.It Em MRU +number of ARC bytes holding most recently used data +.It Em MFU +number of ARC bytes holding most frequently used data +.It Em Anon +number of ARC bytes holding in flight data +.It Em Header +number of ARC bytes holding headers +.It Em Other +miscellaneous ARC bytes +.It Em Compressed +bytes of memory used by ARC caches +.It Em Uncompressed +bytes of data stored in ARC caches before compression +.It Em Ratio +compression ratio of data cached in the ARC +.El +.Ss Swap Stats +.Bl -tag -width "Uncompressed" -compact +.It Em Total +total available swap usage +.It Em Free +total free swap usage +.It Em Inuse +swap usage +.It Em \&In +bytes paged in from swap devices (last interval) +.It Em Out +bytes paged out to swap devices (last interval) +.El +.Sh ENVIRONMENT +.Bl -tag -width "Uncompressed" +.It Ev TOP +Default set of arguments to +.Nm . +.It Ev LC_CTYPE +The locale to use when displaying the +.Va argv +vector when +.Fl a +flag is specified. +.El +.Sh SEE ALSO +.Xr kill 1 , +.Xr ps 1 , +.Xr stty 1 , +.Xr getrusage 2 , +.Xr humanize_number 3 , +.Xr mem 4 , +.Xr renice 8 +.Sh HISTORY +.Nm +first appeared in +.Fx 2.2.2 . +.Sh AUTHORS +.An William LeFebvre, EECS Department, Northwestern University +.Sh BUGS +The command name for swapped processes should be tracked down, but this +would make the program run slower. +.Pp +As with +.Xr ps 1 , +things can change while +.Nm +is collecting information for an update. +The picture it gives is only a close approximation to reality. |