.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'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 >0, we'll generate index entries on stderr for
.\" 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Sys::Virt::StorageVol 3pm"
.TH Sys::Virt::StorageVol 3pm 2024-01-21 "perl v5.38.2" "User Contributed Perl Documentation"
.\" 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
Sys::Virt::StorageVol \- Represent & manage a libvirt storage volume
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \f(CW\*(C`Sys::Virt::StorageVol\*(C'\fR module represents a storage volume managed
by libvirt. A storage volume is always associated with a containing
storage pool (\f(CW\*(C`Sys::Virt::StoragePool\*(C'\fR).
.SH METHODS
.IX Header "METHODS"
.ie n .IP "my $name = $vol\->\fBget_name()\fR" 4
.el .IP "my \f(CW$name\fR = \f(CW$vol\fR\->\fBget_name()\fR" 4
.IX Item "my $name = $vol->get_name()"
Returns a string with a locally unique name of the storage vol
.ie n .IP "my $name = $vol\->\fBget_key()\fR" 4
.el .IP "my \f(CW$name\fR = \f(CW$vol\fR\->\fBget_key()\fR" 4
.IX Item "my $name = $vol->get_key()"
Returns a string with a globally unique key for the storage vol
.ie n .IP "my $name = $vol\->\fBget_path()\fR" 4
.el .IP "my \f(CW$name\fR = \f(CW$vol\fR\->\fBget_path()\fR" 4
.IX Item "my $name = $vol->get_path()"
Returns a string with a locally unique file path of the storage vol
.ie n .IP "my $xml = $vol\->\fBget_xml_description()\fR" 4
.el .IP "my \f(CW$xml\fR = \f(CW$vol\fR\->\fBget_xml_description()\fR" 4
.IX Item "my $xml = $vol->get_xml_description()"
Returns an XML document containing a complete description of
the storage vol's configuration
.ie n .IP $vol\->delete($flags) 4
.el .IP \f(CW$vol\fR\->delete($flags) 4
.IX Item "$vol->delete($flags)"
Immediately delete the storage volume freeing its storage resources.
The \f(CW\*(C`flags\*(C'\fR parameter indicates any special action to be taken when
deleting the volume.
.ie n .IP "$vol\->resize($newcapacity, $flags=0)" 4
.el .IP "\f(CW$vol\fR\->resize($newcapacity, \f(CW$flags\fR=0)" 4
.IX Item "$vol->resize($newcapacity, $flags=0)"
Adjust the size of the storage volume. The \f(CW$newcapacity\fR value
semantics depend on the \f(CW$flags\fR parameter. If \f(CW$flags\fR
specifies \f(CW\*(C`RESIZE_DELTA\*(C'\fR then the \f(CW$newcapacity\fR is relative
to the current size. If \f(CW$flags\fR specifies \f(CW\*(C`RESIZE_SHRINK\*(C'\fR
then the \f(CW$newcapacity\fR value is the amount of space to remove
.ie n .IP "$vol\->wipe($flags = 0)" 4
.el .IP "\f(CW$vol\fR\->wipe($flags = 0)" 4
.IX Item "$vol->wipe($flags = 0)"
Clear the data in the storage volume to avoid future information
leak. The \f(CW\*(C`flags\*(C'\fR parameter is currently unused and defaults
to zero.
.ie n .IP "$vol\->wipe_pattern($algorithm, $flags = 0)" 4
.el .IP "\f(CW$vol\fR\->wipe_pattern($algorithm, \f(CW$flags\fR = 0)" 4
.IX Item "$vol->wipe_pattern($algorithm, $flags = 0)"
Clear the data in the storage volume to avoid future information
leak. The \f(CW$algorithm\fR parameter specifies the data pattern used
to erase data, and should be one of the WIPE ALGORITHM CONSTANTS
listed later. The \f(CW\*(C`flags\*(C'\fR parameter is currently unused and defaults
to zero.
.ie n .IP "my $info = $vol\->get_info($flags = 0)" 4
.el .IP "my \f(CW$info\fR = \f(CW$vol\fR\->get_info($flags = 0)" 4
.IX Item "my $info = $vol->get_info($flags = 0)"
Retrieve live information about the storage volume. The returned
\&\f(CW$info\fR hash reference contains three keys. \f(CW\*(C`type\*(C'\fR indicates whether
the volume is a file or block device. \f(CW\*(C`capacity\*(C'\fR provides the maximum
logical size of the volume. \f(CW\*(C`allocation\*(C'\fR provides the current
physical usage of the volume. The allocation may be less than the
capacity for sparse, or grow-on-demand volumes. The allocation
may also be larger than the capacity, if there is a metadata overhead
for the volume format. \f(CW$flags\fR may take one of the values
.RS 4
.IP Sys::Virt::StorageVol::USE_ALLOCATION 4
.IX Item "Sys::Virt::StorageVol::USE_ALLOCATION"
Return the current allocation in allocation
.IP Sys::Virt::StorageVol::GET_PHYSICAL 4
.IX Item "Sys::Virt::StorageVol::GET_PHYSICAL"
Return the physical size in allocation
.RE
.RS 4
.RE
.ie n .IP "$vol\->download($st, $offset, $length, $flags=0);" 4
.el .IP "\f(CW$vol\fR\->download($st, \f(CW$offset\fR, \f(CW$length\fR, \f(CW$flags\fR=0);" 4
.IX Item "$vol->download($st, $offset, $length, $flags=0);"
Download data from \f(CW$vol\fR using the stream \f(CW$st\fR. If \f(CW$offset\fR
and \f(CW$length\fR are non-zero, then restrict data to the specified
volume byte range. The \f(CW$flags\fR accept the following values:
.RS 4
.IP Sys::Virt::StorageVol::VOL_DOWNLOAD_SPARSE_STREAM 4
.IX Item "Sys::Virt::StorageVol::VOL_DOWNLOAD_SPARSE_STREAM"
If this flag is is set in \f(CW@flags\fR effective transmission of holes
is enabled. This assumes using the stream \f(CW$st\fR with combination of
\&\f(CW\*(C`sparse_recv_all\*(C'\fR or \f(CW\*(C`recv($flags =
VIR_STREAM_RECV_STOP_AT_HOLE)\*(C'\fR for honouring holes sent by server.
.RE
.RS 4
.RE
.ie n .IP "$vol\->upload($st, $offset, $length, $flags=0);" 4
.el .IP "\f(CW$vol\fR\->upload($st, \f(CW$offset\fR, \f(CW$length\fR, \f(CW$flags\fR=0);" 4
.IX Item "$vol->upload($st, $offset, $length, $flags=0);"
Upload data to \f(CW$vol\fR using the stream \f(CW$st\fR. If \f(CW$offset\fR
and \f(CW$length\fR are non-zero, then restrict data to the specified
volume byte range. The \f(CW$flags\fR accept the following values:
.RS 4
.IP Sys::Virt::StorageVol::VOL_UPLOAD_SPARSE_STREAM 4
.IX Item "Sys::Virt::StorageVol::VOL_UPLOAD_SPARSE_STREAM"
If this is set in \f(CW$flags\fR effective transmission of holes is
enabled. This assumes using the stream \f(CW$st\fR with combination of
\&\f(CW\*(C`sparse_send_all\*(C'\fR or \f(CW\*(C`send_hole\*(C'\fR to preserve source file
sparseness.
.RE
.RS 4
.RE
.SH CONSTANTS
.IX Header "CONSTANTS"
The following sets of constants are useful when dealing with storage
volumes
.SS "VOLUME TYPES"
.IX Subsection "VOLUME TYPES"
The following constants are useful for interpreting the \f(CW\*(C`type\*(C'\fR
field in the hash returned by the \f(CW\*(C`get_info\*(C'\fR method
.IP Sys::Virt::StorageVol::TYPE_FILE 4
.IX Item "Sys::Virt::StorageVol::TYPE_FILE"
The volume is a plain file
.IP Sys::Virt::StorageVol::TYPE_BLOCK 4
.IX Item "Sys::Virt::StorageVol::TYPE_BLOCK"
The volume is a block device
.IP Sys::Virt::StorageVol::TYPE_DIR 4
.IX Item "Sys::Virt::StorageVol::TYPE_DIR"
The volume is a directory
.IP Sys::Virt::StorageVol::TYPE_NETWORK 4
.IX Item "Sys::Virt::StorageVol::TYPE_NETWORK"
The volume is a network source
.IP Sys::Virt::StorageVol::TYPE_NETDIR 4
.IX Item "Sys::Virt::StorageVol::TYPE_NETDIR"
The volume is a network directory
.IP Sys::Virt::StorageVol::TYPE_PLOOP 4
.IX Item "Sys::Virt::StorageVol::TYPE_PLOOP"
The volume is a ploop directory
.SS "CREATE MODES"
.IX Subsection "CREATE MODES"
The following constants are useful for the \f(CW\*(C`flags\*(C'\fR parameter of
the \f(CW\*(C`create\*(C'\fR method
.IP Sys::Virt::StorageVol::CREATE_PREALLOC_METADATA 4
.IX Item "Sys::Virt::StorageVol::CREATE_PREALLOC_METADATA"
Preallocate header metadata when creating the volume.
.IP Sys::Virt::StorageVol::CREATE_REFLINK 4
.IX Item "Sys::Virt::StorageVol::CREATE_REFLINK"
Perform lightweight reference copy
.IP Sys::Virt::StorageVol::CREATE_VALIDATE 4
.IX Item "Sys::Virt::StorageVol::CREATE_VALIDATE"
Validate the XML document against schema
.SS "DELETE MODES"
.IX Subsection "DELETE MODES"
The following constants are useful for the \f(CW\*(C`flags\*(C'\fR parameter of
the \f(CW\*(C`delete\*(C'\fR method
.IP Sys::Virt::StorageVol::DELETE_NORMAL 4
.IX Item "Sys::Virt::StorageVol::DELETE_NORMAL"
Do a plain delete without any attempt to scrub data.
.IP Sys::Virt::StorageVol::DELETE_ZEROED 4
.IX Item "Sys::Virt::StorageVol::DELETE_ZEROED"
Zero out current allocated blocks when deleting the volume
.IP Sys::Virt::StorageVol::DELETE_WITH_SNAPSHOTS 4
.IX Item "Sys::Virt::StorageVol::DELETE_WITH_SNAPSHOTS"
Delete snapshots associated with the volume
.SS "WIPE ALGORITHM CONSTANTS"
.IX Subsection "WIPE ALGORITHM CONSTANTS"
The following constants specify the algorithm for erasing
data
.IP Sys::Virt::StorageVol::WIPE_ALG_BSI 4
.IX Item "Sys::Virt::StorageVol::WIPE_ALG_BSI"
9\-pass method recommended by the German Center
of Security in Information Technologies
.IP Sys::Virt::StorageVol::WIPE_ALG_DOD 4
.IX Item "Sys::Virt::StorageVol::WIPE_ALG_DOD"
4\-pass Dod 5220.22\-M section, 8\-306 procedure
.IP Sys::Virt::StorageVol::WIPE_ALG_GUTMANN 4
.IX Item "Sys::Virt::StorageVol::WIPE_ALG_GUTMANN"
The canonical 35\-pass sequence
.IP Sys::Virt::StorageVol::WIPE_ALG_NNSA 4
.IX Item "Sys::Virt::StorageVol::WIPE_ALG_NNSA"
4\-pass NNSA Policy Letter NAP\-14.1\-C (XVI\-8)
.IP Sys::Virt::StorageVol::WIPE_ALG_PFITZNER7 4
.IX Item "Sys::Virt::StorageVol::WIPE_ALG_PFITZNER7"
7\-pass random
.IP Sys::Virt::StorageVol::WIPE_ALG_PFITZNER33 4
.IX Item "Sys::Virt::StorageVol::WIPE_ALG_PFITZNER33"
33\-pass random
.IP Sys::Virt::StorageVol::WIPE_ALG_RANDOM 4
.IX Item "Sys::Virt::StorageVol::WIPE_ALG_RANDOM"
1\-pass random
.IP Sys::Virt::StorageVol::WIPE_ALG_SCHNEIER 4
.IX Item "Sys::Virt::StorageVol::WIPE_ALG_SCHNEIER"
7\-pass method described by Bruce Schneier in "Applied
Cryptography" (1996)
.IP Sys::Virt::StorageVol::WIPE_ALG_ZERO 4
.IX Item "Sys::Virt::StorageVol::WIPE_ALG_ZERO"
1\-pass, all zeroes
.IP Sys::Virt::StorageVol::WIPE_ALG_TRIM 4
.IX Item "Sys::Virt::StorageVol::WIPE_ALG_TRIM"
1\-pass, trim all data on the volume by using TRIM or DISCARD
.SS "VOLUME RESIZE CONSTANTS"
.IX Subsection "VOLUME RESIZE CONSTANTS"
The following constants control how storage volumes can
be resized
.IP Sys::Virt::StorageVol::RESIZE_ALLOCATE 4
.IX Item "Sys::Virt::StorageVol::RESIZE_ALLOCATE"
Fully allocate the extra space required during resize
.IP Sys::Virt::StorageVol::RESIZE_DELTA 4
.IX Item "Sys::Virt::StorageVol::RESIZE_DELTA"
Treat the new capacity as a delta to the current capacity
.IP Sys::Virt::StorageVol::RESIZE_SHRINK 4
.IX Item "Sys::Virt::StorageVol::RESIZE_SHRINK"
Treat the new capacity as an amount to remove from the capacity
.SH AUTHORS
.IX Header "AUTHORS"
Daniel P. Berrange <berrange@redhat.com>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2006\-2009 Red Hat
Copyright (C) 2006\-2009 Daniel P. Berrange
.SH LICENSE
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or modify
it under the terms of either the GNU General Public License as published
by the Free Software Foundation (either version 2 of the License, or at
your option any later version), or, the Artistic License, as specified
in the Perl README file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Sys::Virt, Sys::Virt::Error, \f(CW\*(C`http://libvirt.org\*(C'\fR