-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote. | will give a
-.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
-.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
-.\" expand to `' in nroff, nothing in troff, for use with C<>.
-.tr \(*W-|\(bv\*(Tr
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds R" ''
'br\}
.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
-.if \nF \{\
+.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
-.\"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
+.el \{\
+. de IX
+..
+.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
.\" ========================================================================
.\"
.IX Title "VIRT-TOP 1"
-.TH VIRT-TOP 1 "2007-11-19" "ocaml-libvirt-0.3.3.3" "Virtualization Support"
+.TH VIRT-TOP 1 "2011-02-02" "virt-top-1.0.5" "Virtualization Support"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
.SH "NAME"
virt\-top \- 'top'\-like utility for virtualization stats
.SH "SUMMARY"
.IX Item "-o sort"
Set the sort order to one of:
\&\fBcpu\fR (sort by \f(CW%CPU\fR used),
-\&\fBmem\fR (sort by memory used),
+\&\fBmem\fR (sort by total memory),
\&\fBtime\fR (sort by total time),
\&\fBid\fR (sort by domain \s-1ID\s0),
\&\fBname\fR (sort by domain name),
this feature, eg. \fIbash\fR):
.Sp
.Vb 1
-\& virt-top --csv >(gzip -9 > output.csv.gz)
+\& virt\-top \-\-csv >(gzip \-9 > output.csv.gz)
.Ve
.Sp
You can use a similar trick to split the \s-1CSV\s0 file up. In this example
\&\fIoutput.csv.00\fR, \fIoutput.csv.01\fR etc.
.Sp
.Vb 1
-\& virt-top --csv >(split -d -l 1000 - output.csv.)
+\& virt\-top \-\-csv >(split \-d \-l 1000 \- output.csv.)
.Ve
.IP "\fB\-\-no\-csv\-cpu\fR" 4
.IX Item "--no-csv-cpu"
To send error messages to syslog you can do:
.Sp
.Vb 1
-\& virt-top --debug >(logger -t virt-top)
+\& virt\-top \-\-debug >(logger \-t virt\-top)
.Ve
.Sp
See also \s-1REPORTING\s0 \s-1BUGS\s0 below.
.IP "\fB\-\-init\-file filename\fR" 4
.IX Item "--init-file filename"
Read \fIfilename\fR as the init file instead of the default which is
-\&\fI$HOME/.virt\-toprc\fR. See also \s-1INIT\s0 \s-1FILE\s0 below.
+\&\fI\f(CI$HOME\fI/.virt\-toprc\fR. See also \s-1INIT\s0 \s-1FILE\s0 below.
.IP "\fB\-\-no\-init\-file\fR" 4
.IX Item "--no-init-file"
Do not read any init file.
.IX Item "--script"
Script mode. There will be no user interface. This is most useful
when used together with the \fI\-\-csv\fR and \fI\-n\fR options.
+.IP "\fB\-\-stream\fR" 4
+.IX Item "--stream"
+Stream mode. All output is sent to stdout. This can be used from
+shell scripts etc. There is no user interface.
+.IP "\fB\-\-block\-in\-bytes\fR" 4
+.IX Item "--block-in-bytes"
+Show I/O statistics in Bytes. Default is shown in the number of Requests.
.IP "\fB\-\-end\-time time\fR" 4
.IX Item "--end-time time"
The program will exit at the \fItime\fR given.
For example to run the program for 3 minutes you could do:
.Sp
.Vb 1
-\& virt-top --end-time +00:03:00
+\& virt\-top \-\-end\-time +00:03:00
.Ve
.Sp
or:
.Sp
.Vb 1
-\& virt-top --end-time +180
+\& virt\-top \-\-end\-time +180
.Ve
.Sp
Not every version of virt-top supports this option \- it depends how the
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
Display usage summary.
+.IP "\fB\-\-version\fR" 4
+.IX Item "--version"
+Display version number and exit.
.SH "KEYS"
.IX Header "KEYS"
Note that keys are case sensitive. For example use upper-case \fIP\fR
.IP "\fIs\fR or \fId\fR" 4
.IX Item "s or d"
Change the delay between screen updates.
+.IP "\fIB\fR" 4
+.IX Item "B"
+Toggle Block I/O statistics so they are shown in either bytes or requests.
.IP "\fI0\fR (number 0)" 4
.IX Item "0 (number 0)"
Show the normal list of domains display.
Sort by \f(CW%CPU\fR.
.IP "\fIM\fR" 4
.IX Item "M"
-Sort by memory.
+Sort by total memory. Note that this shows the total memory
+allocated to the guest, not the memory being used.
.IP "\fIT\fR" 4
.IX Item "T"
Sort by total time.
.IP "\fBscript\fR \fItrue|false\fR" 4
.IX Item "script true|false"
Sets script mode.
+.IP "\fBstream\fR \fItrue|false\fR" 4
+.IX Item "stream true|false"
+Sets stream mode.
+.IP "\fBblock-in-bytes\fR \fItrue|false\fR" 4
+.IX Item "block-in-bytes true|false"
+Show block device statistics in bytes.
.IP "\fBend-time\fR \fItime\fR" 4
.IX Item "end-time time"
Set the time at which the program exits. See above for the
Note that in the current implementation, options specified in
the init file override options specified on the command line.
This is a bug and this behaviour may change in the future.
+.SH "NOTES"
+.IX Header "NOTES"
+.SS "Block I/O statistics"
+.IX Subsection "Block I/O statistics"
+This I/O value is the amount of I/O since the previous iteration
+of virt-top. To calculate speed of I/O, you should divide
+the number by delay secs.
+.SS "\s-1NETWORK\s0 \s-1RX\s0 \s-1BYTES\s0 \s-1AND\s0 \s-1PACKETS\s0"
+.IX Subsection "NETWORK RX BYTES AND PACKETS"
+Libvirt/virt\-top has no way to know that a packet transmitted to a
+guest was received (eg. if the guest is not listening). In the
+network \s-1RX\s0 stats, virt-top reports the packets transmitted to the
+guest, on the basis that the guest might receive them.
+.PP
+In particular this includes broadcast packets. Because of the way
+that Linux bridges work, if the guest is connected to a bridge, it
+will probably see a steady \*(L"background noise\*(R" of \s-1RX\s0 packets even when
+the network interface is idle or down. These are caused by \s-1STP\s0
+packets generated by the bridge.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fItop\fR\|(1),
\&\fIvirsh\fR\|(1),
-\&\fIxm\fR\|(1),
-\&\fIxentop\fR\|(1),
+<http://www.libvirt.org/ocaml/>,
<http://www.libvirt.org/>,
-<http://et.redhat.com/~rjones/>,
+<http://people.redhat.com/~rjones/>,
<http://caml.inria.fr/>
.SH "AUTHORS"
.IX Header "AUTHORS"
Richard W.M. Jones <rjones @ redhat . com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
-(C) Copyright 2007 Red Hat Inc., Richard W.M. Jones
+(C) Copyright 2007\-2011 Red Hat Inc., Richard W.M. Jones
http://libvirt.org/
.PP
This program is free software; you can redistribute it and/or modify
Bugs can be viewed on the Red Hat Bugzilla page:
<https://bugzilla.redhat.com/>.
.PP
-If you find a bug in virt\-top, please follow these steps to report it:
+If you find a bug in virt-top, please follow these steps to report it:
.IP "1. Check for existing bug reports" 4
.IX Item "1. Check for existing bug reports"
Go to <https://bugzilla.redhat.com/> and search for similar bugs.
Run
.Sp
.Vb 1
-\& virt-top --debug virt-top.log
+\& virt\-top \-\-debug virt\-top.log
.Ve
.Sp
and keep \fIvirt\-top.log\fR. It contains error messages which you
should submit with your bug report.
.IP "3. Get version of virt-top and version of libvirt." 4
.IX Item "3. Get version of virt-top and version of libvirt."
-In virt\-top, press the \fIh\fR (help) key, and write down the version of
-virt-top and the version of libvirt. They are shown in the first
-line.
+Use:
+.Sp
+.Vb 1
+\& virt\-top \-\-version
+.Ve
+.Sp
+If you can get the precise version of libvirt you are using
+then that too is helpful.
.IP "4. Submit a bug report." 4
.IX Item "4. Submit a bug report."
Go to <https://bugzilla.redhat.com/> and enter a new bug.