ftop (1) - Linux Manuals

ftop: show progress of open files and file systems

Command to display ftop manual in Linux: $ man 1 ftop

NAME

ftop - show progress of open files and file systems

SYNOPSIS

ftop [options]

COPYRIGHT

DESCRIPTION

The ftop program displays progress information for the open files and file systems in a Linux system. As processes read and write files, ftop displays data rates and time estimates. Its feature-rich interface is similar to top, and includes extensive run-time configuration options.

While this manual page contains the full documentation for ftop, the built-in online help is the best source for the most up to date documentation. To access the online help, run ftop with the -h command line option, or simply press 'h' while ftop is running.

OPTIONS

Every option listed below is supported as a command-line argument (for example, -f) and as a run-time keyboard command (f). Thus, any option can be set when ftop is started, and can be changed later while it is running. Options with uppercase characters are boolean values (enabled or disabled), and lowercase option characters require other types of values.

Boolean options are disabled by default. When supplied as a command-line argument, the option is enabled. If the corresponding key is pressed while ftop is running, the option's value is toggled.

Non-boolean options accept values of the type shown next to their option characters. List values accept one or more values, separated by comma characters (with no spaces). Values of type num are numeric, and values of type user can be specified as either a valid login or numeric UID.

Please refer to the additional details following the list of options.

-a list: Additional files/fs
: Manually specify files or file systems to monitor. These are in addition to all currently open files. If any directories are specified, their file system usage is displayed. This option is useful for monitoring files written by NFS clients, or for observing the addition of a large number of files to a file system (for example, while extracting a large archive or restoring from a backup).

-A: Addl. files/fs only
: Only show the files and file systems specified in 'Additional files/fs' (see above) and 'File system types' (see below).

-B: Expand at-beginning
: Show the progress bar for files that are still at the beginning. When this option is disabled, a file's progress bar doesn't appear until there has been some activity. Often, there are processes that hold log files open for append, but haven't yet written anything new. Leaving this disabled reduces the clutter in the presence of those (and similar) situations.

-c num: Closed files count
: Additionally show the specified number of most recently closed files for each displayed process.

-d num: Delay
: Change the time between updates. The value is specified in seconds, with optional tenths or hundredths (for example: 1 or 0.5 or 1.25 are all valid).

-D: Hide path directories
: Hide all leading directory components of each file path. If the file path refers to an unnamed pipe or socket, or otherwise is not valid, then the full path will still be displayed.

-E: Expand at-end
: Show the progress bar for files that are at the end. When this option is disabled, a file's progress bar disappears once the process reaches the end of the file. Whenever a process writes to a file, the resulting position is at the end. Processes that write to log files tend to have several files open in this state. Leaving this disabled "reduces the clutter in the presence of those (and similar) situations. See also 'File keywords & sizes' below.

-f list: File keywords
: Only show files whose path contains, anywhere within, one of the specified keywords. For instance, if a file /tmp/live-cd.iso is open, and the keyword list contains cd.i, then that file will be shown.

-F: Show un-expanded files
: Show all files that are open within the displayed processes. See also

ow un-expanded procs' below.


-h: Help
: Toggle the help screen.

-l list: Log types
: Specify the type(s) of messages to log. Valid types are none, all, or one or more of the following: err, warn, info, debug. The value none disables logging. If logging is enabled, and 'Limited output mode' (see below) is enabled, the log is output on stderr. See also 'View log' below.

-L: View log
: Toggle the log screen, if logging is enabled.

-m list: Access modes
: Specify the access mode(s) of files to show. Valid modes are one or more of the following: r, w, rw. If r is specified, files open for read-only access will be shown. If w is specified, files open for write-only access will be shown. If rw is specified, then files open for read and write will be shown. Note, rw does not include read-only or write-only files.

-n num: Iterations
: Specify the total number of update iterations to run, after which ftop will exit.

-N: Show all FDs numeric
: Display all file descriptors as their numeric values. When this option is disabled, file descriptors 0, 1, and 2 are given the symbolic names in, out, and err, respectively, to reflect stdin, stdout, and stderr.

-o: View options
: Toggle the options summary screen.

-O: Limited output mode
: Toggle between full output mode and limited output mode. By default, full mode is selected if the ncurses library is available and stdout is a terminal (e.g. not redirected or piped). If neither of the above is true, then only limited mode will be available. If this option is specified on the command line, limited mode will be used initially. In limited mode, all control keys can still be used, but scrolling is not available.

-p list: Process keywords/PIDs
: Show only processes whose command line contains, anywhere within, one the specified keywords, or whose PID equals a specified value. For instance, the list 1,bash,X will show the init process, all instances of bash, and any running X servers (if X is within their command line). Note, processes with no open files that match any of the other criteria will still not be shown. See also 'Show un-expanded procs' below.

-P: Show un-expanded procs
: Show all processes. See also 'Show un-expanded files' and 'Process keywords/PIDs' above.

-q: Quit
: Exit from ftop.

-Q: Hide tput & est. time
: Do not show any throughput or estimated time remaining calculations. This is useful when simply monitoring how far into files the processes are, especially if used with a very small delay (see 'Delay' above).

-r: Refresh display
: Force a refresh of the display.

-t list: File types
: Specify the type(s) of files to show. Valid types are all, or one or more of the following: f, d, c, b, p, s, x. Also allowed is r, an alias for f. The meaning of each is: f (regular file), d (directory), c (character device), b (block device), p (pipe/FIFO), s (socket), and x (miscellaneous - unknown or unclassifiable).

-u user: User name/UID
: Only show processes with the given real user id. The user can be specified either as a name or as a UID.

-U: Units in base 10
: If this option is disabled, sizes and throughputs will be reported in units based on powers of 2. Specifically, M (megabyte) corresponds to 2 to the 20th power and G (gigabyte) corresponds to 2 to the 30th. If this option is enabled, the units e6 (million bytes) and e9 (billion bytes) will be used instead. Note, either form is always acceptable when entering size values, regardless of this setting.

-v: Version and license
: Toggle the version and license screen.

-x num: Max no-match iterations
: Specify the number of iterations to remain running when there are no open files matching any of the other criteria. At least one match has to have been shown, and subsequently been closed, before the remaining iterations are counted. If during those iterations, another matching file is shown, the counter is reset. See also 'Iterations' above.

-y list: File system types
: Show all mounted filesystems of the specified types. Valid types are all, or one or more of the types supported by the kernel (refer to /proc/filesystems). The display is updated to reflect the mounting or unmounting of matching file systems.

-z list: File keywords & sizes
: Specify pre-determined final sizes to use for files opened for write access and for file systems (see 'Additional files/fs' above). The values in the list must be of the form keyword=size, where keyword is applied as in 'File keywords' (see above) and size is given in bytes, megabytes (or million bytes), or gigabytes (or billion bytes) with optional tenths value. See 'Units in base 10' above. The following is an example of a valid list: data_out.bin=1.5G,/tmp/=700e6,some_file.copy=120000

NOTES

The three characters displayed after a file's descriptor represent the type of file and the access mode. See 'File types' and 'Access modes' for details on each. In the case of a file system, FS- will be displayed. If a file is opened in append mode, an uppercase W will be displayed instead of a lowercase w.

The two characters following the access mode represent activity. If -- is displayed, there is no activity. If the position is advancing in a forward direction, then ->, >>, or >- will be displayed depending on how much progress is occurring. If the position is moving backward, then -<, <<, or <- will be displayed. If the position is moving in a somewhat random fashion, then <> will be displayed. Finally, any time a different file is open for the given descriptor, ** is displayed.

When monitoring additional files, only the current total size of the file can be obtained; no read or write position is available. Thus, for display purposes, the file is reported as being opened for write-only access, and the current file size is used as its position. If the ultimate size of the file is known, it can be supplied with 'File keywords & sizes' and that value will then be reported as the size.

For file systems, the amount of space currently consumed is used as the position. In both cases (additional files and file systems), the reported position value is still used in throughput calculations and remaining time estimates.

EXAMPLES

To see a real-time graphic representation of all mounted ext3 and nfs file systems:

ftop -QAy ext3,nfs

The following command provides very interesting feedback when working with large gzipped or bzip2'ed tar files. Note, the exact same command can be used to monitor both creating the archive file, and extracting its contents. The specified file system (/share/ in this example) should be where the file is being created, or where its contents are being placed (in which case multiple file systems may need to be given). Also, the delay time may need to be adjusted to achieve the desired effects.

ftop -d .1 -c 4 -p tar,gzip -t f,p -a /share/

If a file /tmp/output.bin is to be created by another process, and it is known that its resulting size will be approximately 6.5GB, then the following command will monitor the progress for at most 60 seconds, but will exit earlier if the process completes early or the file is otherwised closed for more than 1 second.

ftop -f mp/outp -z output.bin=6.5G -n 60 -x 1

If, in the example above, the file is being created by an NFS client, then the file will not be open locally. In this case, the command would be as follows:

ftop -Aa /tmp/output.bin -z output.bin=6.5G -n 60 -x 1

It can be interesting to see disk access patterns in different operating systems as they boot and perform their duties (or as a system is booting from a CD or DVD). With an emulator or virtualization environment, and provided the emulator doesn't do much caching of the virtualized disks, this behavior can be monitored for any number of disk image files with a command such as the following:

ftop -f cd.img,hdd.img -d 0.1 -QBED

To capture a log of progress's activity for one iteration (useful if sending a bug report):

ftop -On 1 -l all 2> log.txt