1FTOP(1) General Commands Manual FTOP(1)
2
6 ftop - show progress of open files and file systems
7
9 ftop [options]
10
12 ftop is Copyright (C) 2009 Jason Todd. Send bug reports and sugges‐
13 tions/patches/etc. to jtodd1@earthlink.net.
14
16 The ftop program displays progress information for the open files and
17 file systems in a Linux system. As processes read and write files,
18 ftop displays data rates and time estimates. Its feature-rich inter‐
19 face is similar to top, and includes extensive run-time configuration
20 options.
21 While this manual page contains the full documentation for ftop, the
23 built-in online help is the best source for the most up to date docu‐
24 mentation. To access the online help, run ftop with the -h command
25 line option, or simply press 'h' while ftop is running.
26
28 Every option listed below is supported as a command-line argument (for
29 example, -f) and as a run-time keyboard command (f). Thus, any option
30 can be set when ftop is started, and can be changed later while it is
31 running. Options with uppercase characters are boolean values (enabled
32 or disabled), and lowercase option characters require other types of
33 values.
34 Boolean options are disabled by default. When supplied as a command-
36 line argument, the option is enabled. If the corresponding key is
37 pressed while ftop is running, the option's value is toggled.
38 Non-boolean options accept values of the type shown next to their
40 option characters. List values accept one or more values, separated by
41 comma characters (with no spaces). Values of type num are numeric, and
42 values of type user can be specified as either a valid login or numeric
43 UID.
44 Please refer to the additional details following the list of options.
46 -a list Additional files/fs
48 Manually specify files or file systems to monitor. These are
49 in addition to all currently open files. If any directories
50 are specified, their file system usage is displayed. This
51 option is useful for monitoring files written by NFS clients,
52 or for observing the addition of a large number of files to a
53 file system (for example, while extracting a large archive or
54 restoring from a backup).
55 -A Addl. files/fs only
57 Only show the files and file systems specified in 'Additional
58 files/fs' (see above) and 'File system types' (see below).
59 -B Expand at-beginning
61 Show the progress bar for files that are still at the begin‐
62 ning. When this option is disabled, a file's progress bar
63 doesn't appear until there has been some activity. Often,
64 there are processes that hold log files open for append, but
65 haven't yet written anything new. Leaving this disabled
66 reduces the clutter in the presence of those (and similar)
67 situations.
68 -c num Closed files count
70 Additionally show the specified number of most recently closed
71 files for each displayed process.
72 -d num Delay
74 Change the time between updates. The value is specified in
75 seconds, with optional tenths or hundredths (for example: 1 or
76 0.5 or 1.25 are all valid).
77 -D Hide path directories
79 Hide all leading directory components of each file path. If
80 the file path refers to an unnamed pipe or socket, or other‐
81 wise is not valid, then the full path will still be displayed.
82 -E Expand at-end
84 Show the progress bar for files that are at the end. When
85 this option is disabled, a file's progress bar disappears once
86 the process reaches the end of the file. Whenever a process
87 writes to a file, the resulting position is at the end. Pro‐
88 cesses that write to log files tend to have several files open
89 in this state. Leaving this disabled "reduces the clutter in
90 the presence of those (and similar) situations. See also
91 'File keywords & sizes' below.
92 -f list File keywords
94 Only show files whose path contains, anywhere within, one of
95 the specified keywords. For instance, if a file /tmp/live-
96 cd.iso is open, and the keyword list contains cd.i, then that
97 file will be shown.
98 -F Show un-expanded files
100 Show all files that are open within the displayed processes.
101 See also
102 -h Help
104 Toggle the help screen.
105 -l list Log types
107 Specify the type(s) of messages to log. Valid types are none,
108 all, or one or more of the following: err, warn, info, debug.
109 The value none disables logging. If logging is enabled, and
110 'Limited output mode' (see below) is enabled, the log is out‐
111 put on stderr. See also 'View log' below.
112 -L View log
114 Toggle the log screen, if logging is enabled.
115 -m list Access modes
117 Specify the access mode(s) of files to show. Valid modes are
118 one or more of the following: r, w, rw. If r is specified,
119 files open for read-only access will be shown. If w is speci‐
120 fied, files open for write-only access will be shown. If rw
121 is specified, then files open for read and write will be
122 shown. Note, rw does not include read-only or write-only
123 files.
124 -n num Iterations
126 Specify the total number of update iterations to run, after
127 which ftop will exit.
128 -N Show all FDs numeric
130 Display all file descriptors as their numeric values. When
131 this option is disabled, file descriptors 0, 1, and 2 are
132 given the symbolic names in, out, and err, respectively, to
133 reflect stdin, stdout, and stderr.
134 -o View options
136 Toggle the options summary screen.
137 -O Limited output mode
139 Toggle between full output mode and limited output mode. By
140 default, full mode is selected if the ncurses library is
141 available and stdout is a terminal (e.g. not redirected or
142 piped). If neither of the above is true, then only limited
143 mode will be available. If this option is specified on the
144 command line, limited mode will be used initially. In limited
145 mode, all control keys can still be used, but scrolling is not
146 available.
147 -p list Process keywords/PIDs
149 Show only processes whose command line contains, anywhere
150 within, one the specified keywords, or whose PID equals a
151 specified value. For instance, the list 1,bash,X will show
152 the init process, all instances of bash, and any running X
153 servers (if X is within their command line). Note, processes
154 with no open files that match any of the other criteria will
155 still not be shown. See also 'Show un-expanded procs' below.
156 -P Show un-expanded procs
158 Show all processes. See also 'Show un-expanded files' and
159 'Process keywords/PIDs' above.
160 -q Quit
162 Exit from ftop.
163 -Q Hide tput & est. time
165 Do not show any throughput or estimated time remaining calcu‐
166 lations. This is useful when simply monitoring how far into
167 files the processes are, especially if used with a very small
168 delay (see 'Delay' above).
169 -r Refresh display
171 Force a refresh of the display.
172 -t list File types
174 Specify the type(s) of files to show. Valid types are all, or
175 one or more of the following: f, d, c, b, p, s, x. Also
176 allowed is r, an alias for f. The meaning of each is: f (reg‐
177 ular file), d (directory), c (character device), b (block
178 device), p (pipe/FIFO), s (socket), and x (miscellaneous -
179 unknown or unclassifiable).
180 -u user User name/UID
182 Only show processes with the given real user id. The user can
183 be specified either as a name or as a UID.
184 -U Units in base 10
186 If this option is disabled, sizes and throughputs will be
187 reported in units based on powers of 2. Specifically, M
188 (megabyte) corresponds to 2 to the 20th power and G (gigabyte)
189 corresponds to 2 to the 30th. If this option is enabled, the
190 units e6 (million bytes) and e9 (billion bytes) will be used
191 instead. Note, either form is always acceptable when entering
192 size values, regardless of this setting.
193 -v Version and license
195 Toggle the version and license screen.
196 -x num Max no-match iterations
198 Specify the number of iterations to remain running when there
199 are no open files matching any of the other criteria. At
200 least one match has to have been shown, and subsequently been
201 closed, before the remaining iterations are counted. If dur‐
202 ing those iterations, another matching file is shown, the
203 counter is reset. See also 'Iterations' above.
204 -y list File system types
206 Show all mounted filesystems of the specified types. Valid
207 types are all, or one or more of the types supported by the
208 kernel (refer to /proc/filesystems). The display is updated
209 to reflect the mounting or unmounting of matching file sys‐
210 tems.
211 -z list File keywords & sizes
213 Specify pre-determined final sizes to use for files opened for
214 write access and for file systems (see 'Additional files/fs'
215 above). The values in the list must be of the form key‐
216 word=size, where keyword is applied as in 'File keywords' (see
217 above) and size is given in bytes, megabytes (or million
218 bytes), or gigabytes (or billion bytes) with optional tenths
219 value. See 'Units in base 10' above. The following is an
220 example of a valid list:
221 data_out.bin=1.5G,/tmp/=700e6,some_file.copy=120000
222
224 The three characters displayed after a file's descriptor represent the
225 type of file and the access mode. See 'File types' and 'Access modes'
226 for details on each. In the case of a file system, FS- will be dis‐
227 played. If a file is opened in append mode, an uppercase W will be
228 displayed instead of a lowercase w.
229 The two characters following the access mode represent activity. If --
231 is displayed, there is no activity. If the position is advancing in a
232 forward direction, then ->, >>, or >- will be displayed depending on
233 how much progress is occurring. If the position is moving backward,
234 then -<, <<, or <- will be displayed. If the position is moving in a
235 somewhat random fashion, then <> will be displayed. Finally, any time
236 a different file is open for the given descriptor, ** is displayed.
237 When monitoring additional files, only the current total size of the
239 file can be obtained; no read or write position is available. Thus,
240 for display purposes, the file is reported as being opened for write-
241 only access, and the current file size is used as its position. If the
242 ultimate size of the file is known, it can be supplied with 'File key‐
243 words & sizes' and that value will then be reported as the size.
244 For file systems, the amount of space currently consumed is used as the
246 position. In both cases (additional files and file systems), the
247 reported position value is still used in throughput calculations and
248 remaining time estimates.
249
251 To see a real-time graphic representation of all mounted ext3 and nfs
252 file systems:
253 ftop -QAy ext3,nfs
255 The following command provides very interesting feedback when working
257 with large gzipped or bzip2'ed tar files. Note, the exact same command
258 can be used to monitor both creating the archive file, and extracting
259 its contents. The specified file system (/share/ in this example)
260 should be where the file is being created, or where its contents are
261 being placed (in which case multiple file systems may need to be
262 given). Also, the delay time may need to be adjusted to achieve the
263 desired effects.
264 ftop -d .1 -c 4 -p tar,gzip -t f,p -a /share/
266 If a file /tmp/output.bin is to be created by another process, and it
268 is known that its resulting size will be approximately 6.5GB, then the
269 following command will monitor the progress for at most 60 seconds, but
270 will exit earlier if the process completes early or the file is other‐
271 wised closed for more than 1 second.
272 ftop -f mp/outp -z output.bin=6.5G -n 60 -x 1
274 If, in the example above, the file is being created by an NFS client,
276 then the file will not be open locally. In this case, the command
277 would be as follows:
278 ftop -Aa /tmp/output.bin -z output.bin=6.5G -n 60 -x 1
280 It can be interesting to see disk access patterns in different operat‐
282 ing systems as they boot and perform their duties (or as a system is
283 booting from a CD or DVD). With an emulator or virtualization environ‐
284 ment, and provided the emulator doesn't do much caching of the virtual‐
285 ized disks, this behavior can be monitored for any number of disk image
286 files with a command such as the following:
287 ftop -f cd.img,hdd.img -d 0.1 -QBED
289 To capture a log of progress's activity for one iteration (useful if
291 sending a bug report):
292 ftop -On 1 -l all 2> log.txt
294
296 top(1)
297ftop 1.0 2009-02-16 FTOP(1)