.\" ========================================================================
.\"
.IX Title "VIRT-TOP 1"
-.TH VIRT-TOP 1 "2007-08-30" "ocaml-libvirt-0.3.2.6" "Virtualization Support"
+.TH VIRT-TOP 1 "2007-10-19" "ocaml-libvirt-0.3.3.0" "Virtualization Support"
.SH "NAME"
virt\-top \- 'top'\-like utility for virtualization stats
.SH "SUMMARY"
Not every version of virt-top supports \s-1CSV\s0 output \- it depends how the
program was compiled (see \fI\s-1README\s0\fR file in the source distribution
for details).
+.Sp
+To save space you can compress your \s-1CSV\s0 files (if your shell supports
+this feature, eg. \fIbash\fR):
+.Sp
+.Vb 1
+\& 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
+the \s-1CSV\s0 file is split every 1000 lines into files called
+\&\fIoutput.csv.00\fR, \fIoutput.csv.01\fR etc.
+.Sp
+.Vb 1
+\& virt-top --csv >(split -d -l 1000 - output.csv.)
+.Ve
+.IP "\fB\-\-no\-csv\-cpu\fR" 4
+.IX Item "--no-csv-cpu"
+Disable domain \s-1CPU\s0 stats in \s-1CSV\s0 output.
+.IP "\fB\-\-no\-csv\-block\fR" 4
+.IX Item "--no-csv-block"
+Disable domain block device stats in \s-1CSV\s0 output.
+.IP "\fB\-\-no\-csv\-net\fR" 4
+.IX Item "--no-csv-net"
+Disable domain network interface stats in \s-1CSV\s0 output.
.IP "\fB\-\-debug filename\fR" 4
.IX Item "--debug filename"
Send debug and error messages to \fIfilename\fR.
.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.
+.IP "\fB\-\-no\-init\-file\fR" 4
+.IX Item "--no-init-file"
+Do not read any init file.
+.IP "\fB\-\-script\fR" 4
+.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\-\-end\-time time\fR" 4
+.IX Item "--end-time time"
+The program will exit at the \fItime\fR given.
+.Sp
+The time may be given in one of the following formats:
+.RS 4
+.IP "\fIYYYY-MM-DD \s-1HH:MM:SS\s0\fR" 4
+.IX Item "YYYY-MM-DD HH:MM:SS"
+End time is the date and time given.
+.IP "\fI\s-1HH:MM:SS\s0\fR" 4
+.IX Item "HH:MM:SS"
+End time is the time given, today.
+.IP "\fI+HH:MM:SS\fR" 4
+.IX Item "+HH:MM:SS"
+End time is \s-1HH\s0 hours, \s-1MM\s0 minutes, \s-1SS\s0 seconds in the future (counted
+from the moment that program starts).
+.IP "\fI+secs\fR" 4
+.IX Item "+secs"
+End time is \fIsecs\fR seconds in the future.
+.RE
+.RS 4
+.Sp
+For example to run the program for 3 minutes you could do:
+.Sp
+.Vb 1
+\& virt-top --end-time +00:03:00
+.Ve
+.Sp
+or:
+.Sp
+.Vb 1
+\& virt-top --end-time +180
+.Ve
+.Sp
+Not every version of virt-top supports this option \- it depends how the
+program was compiled (see \fI\s-1README\s0\fR file in the source distribution
+for details).
+.RE
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
Display usage summary.
.IX Item "F"
Select the sort field interactively (there are other
sort fields you can choose using this key).
+.IP "\fIW\fR" 4
+.IX Item "W"
+This creates or overwrites the init file with the current settings.
+.Sp
+This key is disabled if \fI\-\-no\-init\-file\fR was specified on the
+command line or if \fIoverwrite-init-file false\fR is given in
+the init file.
+.SH "INIT FILE"
+.IX Header "INIT FILE"
+When virt-top starts up, it reads initial settings from the
+file \fI.virt\-toprc\fR in the user's home directory.
+.PP
+The name of this file may be overridden using the \fI\-\-init\-file
+filename\fR command line option or may be disabled entirely using
+\&\fI\-\-no\-init\-file\fR.
+.PP
+The init file has a simple format. Blank lines and comments
+beginning with \fI#\fR are ignored. Everything else is a set of
+\&\fIkey value\fR pairs, described below.
+.IP "\fBdisplay\fR \fItask|pcpu|block|net\fR" 4
+.IX Item "display task|pcpu|block|net"
+Sets the major display mode to one of \fItask\fR (tasks, the
+default), \fIpcpu\fR (physical CPUs), \fIblock\fR (block devices),
+or \fInet\fR (network interfaces).
+.IP "\fBdelay\fR \fIsecs\fR" 4
+.IX Item "delay secs"
+Sets the delay between display updates in seconds.
+.IP "\fBhist-cpu\fR \fIsecs\fR" 4
+.IX Item "hist-cpu secs"
+Sets the historical \s-1CPU\s0 delay in seconds.
+.IP "\fBiterations\fR \fIn\fR" 4
+.IX Item "iterations n"
+Sets the number of iterations to run before we exit. Setting
+this to \fI\-1\fR means to run continuously.
+.IP "\fBsort\fR \fIcpu|mem|time|id|name|...\fR" 4
+.IX Item "sort cpu|mem|time|id|name|..."
+Sets the sort order. The option names are the same as for
+the command line \fI\-o\fR option.
+.IP "\fBconnect\fR \fIuri\fR" 4
+.IX Item "connect uri"
+Sets the default connection \s-1URI\s0.
+.IP "\fBdebug\fR \fIfilename\fR" 4
+.IX Item "debug filename"
+Sets the default filename to use for debug and error messages.
+.IP "\fBcsv\fR \fIfilename\fR" 4
+.IX Item "csv filename"
+Enables \s-1CSV\s0 output to the named file.
+.IP "\fBcsv-cpu\fR \fItrue|false\fR" 4
+.IX Item "csv-cpu true|false"
+Enable or disable domain \s-1CPU\s0 stats in \s-1CSV\s0 output.
+.IP "\fBcsv-block\fR \fItrue|false\fR" 4
+.IX Item "csv-block true|false"
+Enable or disable domain block device stats in \s-1CSV\s0 output.
+.IP "\fBcsv-net\fR \fItrue|false\fR" 4
+.IX Item "csv-net true|false"
+Enable or disable domain network interface stats in \s-1CSV\s0 output.
+.IP "\fBbatch\fR \fItrue|false\fR" 4
+.IX Item "batch true|false"
+Sets batch mode.
+.IP "\fBsecure\fR \fItrue|false\fR" 4
+.IX Item "secure true|false"
+Sets secure mode.
+.IP "\fBscript\fR \fItrue|false\fR" 4
+.IX Item "script true|false"
+Sets script mode.
+.IP "\fBend-time\fR \fItime\fR" 4
+.IX Item "end-time time"
+Set the time at which the program exits. See above for the
+time formats supported.
+.IP "\fBoverwrite-init-file\fR \fIfalse\fR" 4
+.IX Item "overwrite-init-file false"
+If set to \fIfalse\fR then the \fIW\fR key will not overwrite the
+init file.
+.PP
+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 "SEE ALSO"
.IX Header "SEE ALSO"
\&\fItop\fR\|(1),
.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
+http://libvirt.org/
+.PP
+This program is free software; you can redistribute it and/or modify
+it under the terms of the \s-1GNU\s0 General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+.PP
+This program is distributed in the hope that it will be useful,
+but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
+\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. See the
+\&\s-1GNU\s0 General Public License for more details.
+.PP
+You should have received a copy of the \s-1GNU\s0 General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, \s-1MA\s0 02139, \s-1USA\s0.
.SH "REPORTING BUGS"
.IX Header "REPORTING BUGS"
Bugs can be viewed on the Red Hat Bugzilla page:
git.annexia.org / virt-top.git / blobdiff