1FTOP(1)                     General Commands Manual                    FTOP(1)
2
3
4

NAME

6       ftop - show progress of open files and file systems
7

SYNOPSIS

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

DESCRIPTION

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
22       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

OPTIONS

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
35       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
39       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
45       Please refer to the additional details following the list of options.
46
47       -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
56       -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
60       -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
69       -c num   Closed files count
70                Additionally show the specified number of most recently closed
71                files for each displayed process.
72
73       -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
78       -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
83       -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
93       -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
99       -F       Show un-expanded files
100                Show all files that are open within the  displayed  processes.
101                See also
102
103       -h       Help
104                Toggle the help screen.
105
106       -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
113       -L       View log
114                Toggle the log screen, if logging is enabled.
115
116       -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
125       -n num   Iterations
126                Specify  the  total  number of update iterations to run, after
127                which ftop will exit.
128
129       -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
135       -o       View options
136                Toggle the options summary screen.
137
138       -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
148       -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
157       -P       Show un-expanded procs
158                Show all processes.  See also  'Show  un-expanded  files'  and
159                'Process keywords/PIDs' above.
160
161       -q       Quit
162                Exit from ftop.
163
164       -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
170       -r       Refresh display
171                Force a refresh of the display.
172
173       -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
181       -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
185       -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
194       -v       Version and license
195                Toggle the version and license screen.
196
197       -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
205       -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
212       -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

NOTES

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
230       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
238       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
245       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

EXAMPLES

251       To see a real-time graphic representation of all mounted ext3  and  nfs
252       file systems:
253
254           ftop -QAy ext3,nfs
255
256       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
265           ftop -d .1 -c 4 -p tar,gzip -t f,p -a /share/
266
267       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
273           ftop -f mp/outp -z output.bin=6.5G -n 60 -x 1
274
275       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
279           ftop -Aa /tmp/output.bin -z output.bin=6.5G -n 60 -x 1
280
281       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
288           ftop -f cd.img,hdd.img -d 0.1 -QBED
289
290       To  capture  a  log of progress's activity for one iteration (useful if
291       sending a bug report):
292
293           ftop -On 1 -l all 2> log.txt
294

SEE ALSO

296       top(1)
297
298
299
300ftop 1.0                          2009-02-16                           FTOP(1)
Impressum