---
name: "Sys::Virt::StorageVol"
section: "3pm"
platform: "linux"
package: "perl-sys-virt"
version: "12.7.0-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Sys::Virt::StorageVol"
---

# Sys::Virt::StorageVol(3pm)

Represent & manage a libvirt storage volume

## NAME

Sys::Virt::StorageVol - Represent & manage a libvirt storage volume

## DESCRIPTION

The `"Sys::Virt::StorageVol"` module represents a storage volume managed by libvirt. A storage volume is always associated with a containing storage pool (`"Sys::Virt::StoragePool"`).

## METHODS

- my $name = $vol-\>**get\_name()**

  Returns a string with a locally unique name of the storage vol

- my $name = $vol-\>**get\_key()**

  Returns a string with a globally unique key for the storage vol

- my $name = $vol-\>**get\_path()**

  Returns a string with a locally unique file path of the storage vol

- my $xml = $vol-\>**get\_xml\_description()**

  Returns an XML document containing a complete description of the storage vol's configuration

- $vol-\>delete($flags)

  Immediately delete the storage volume freeing its storage resources. The `"flags"` parameter indicates any special action to be taken when deleting the volume.

- $vol-\>resize($newcapacity, $flags=0)

  Adjust the size of the storage volume. The `$newcapacity` value semantics depend on the `$flags` parameter. If `$flags` specifies `"RESIZE_DELTA"` then the `$newcapacity` is relative to the current size. If `$flags` specifies `"RESIZE_SHRINK"` then the `$newcapacity` value is the amount of space to remove

- $vol-\>wipe($flags = 0)

  Clear the data in the storage volume to avoid future information leak. The `"flags"` parameter is currently unused and defaults to zero.

- $vol-\>wipe\_pattern($algorithm, $flags = 0)

  Clear the data in the storage volume to avoid future information leak. The `$algorithm` parameter specifies the data pattern used to erase data, and should be one of the WIPE ALGORITHM CONSTANTS listed later. The `"flags"` parameter is currently unused and defaults to zero.

- my $info = $vol-\>get\_info($flags = 0)

  Retrieve live information about the storage volume. The returned `$info` hash reference contains three keys. `"type"` indicates whether the volume is a file or block device. `"capacity"` provides the maximum logical size of the volume. `"allocation"` 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. `$flags` may take one of the values

  - Sys::Virt::StorageVol::USE\_ALLOCATION

    Return the current allocation in allocation

  - Sys::Virt::StorageVol::GET\_PHYSICAL

    Return the physical size in allocation

- $vol-\>download($st, $offset, $length, $flags=0);

  Download data from `$vol` using the stream `$st`. If `$offset` and `$length` are non-zero, then restrict data to the specified volume byte range. The `$flags` accept the following values:

  - Sys::Virt::StorageVol::VOL\_DOWNLOAD\_SPARSE\_STREAM

    If this flag is is set in `@flags` effective transmission of holes is enabled. This assumes using the stream `$st` with combination of `"sparse_recv_all"` or `"recv($flags =` `VIR_STREAM_RECV_STOP_AT_HOLE)"` for honouring holes sent by server.

- $vol-\>upload($st, $offset, $length, $flags=0);

  Upload data to `$vol` using the stream `$st`. If `$offset` and `$length` are non-zero, then restrict data to the specified volume byte range. The `$flags` accept the following values:

  - Sys::Virt::StorageVol::VOL\_UPLOAD\_SPARSE\_STREAM

    If this is set in `$flags` effective transmission of holes is enabled. This assumes using the stream `$st` with combination of `"sparse_send_all"` or `"send_hole"` to preserve source file sparseness.

## CONSTANTS

The following sets of constants are useful when dealing with storage volumes

### VOLUME TYPES

The following constants are useful for interpreting the `"type"` field in the hash returned by the `"get_info"` method

- Sys::Virt::StorageVol::TYPE\_FILE

  The volume is a plain file

- Sys::Virt::StorageVol::TYPE\_BLOCK

  The volume is a block device

- Sys::Virt::StorageVol::TYPE\_DIR

  The volume is a directory

- Sys::Virt::StorageVol::TYPE\_NETWORK

  The volume is a network source

- Sys::Virt::StorageVol::TYPE\_NETDIR

  The volume is a network directory

- Sys::Virt::StorageVol::TYPE\_PLOOP

  The volume is a ploop directory

### CREATE MODES

The following constants are useful for the `"flags"` parameter of the `"create"` method

- Sys::Virt::StorageVol::CREATE\_PREALLOC\_METADATA

  Preallocate header metadata when creating the volume.

- Sys::Virt::StorageVol::CREATE\_REFLINK

  Perform lightweight reference copy

- Sys::Virt::StorageVol::CREATE\_VALIDATE

  Validate the XML document against schema

### DELETE MODES

The following constants are useful for the `"flags"` parameter of the `"delete"` method

- Sys::Virt::StorageVol::DELETE\_NORMAL

  Do a plain delete without any attempt to scrub data.

- Sys::Virt::StorageVol::DELETE\_ZEROED

  Zero out current allocated blocks when deleting the volume

- Sys::Virt::StorageVol::DELETE\_WITH\_SNAPSHOTS

  Delete snapshots associated with the volume

### WIPE ALGORITHM CONSTANTS

The following constants specify the algorithm for erasing data

- Sys::Virt::StorageVol::WIPE\_ALG\_BSI

  9-pass method recommended by the German Center of Security in Information Technologies

- Sys::Virt::StorageVol::WIPE\_ALG\_DOD

  4-pass Dod 5220.22-M section, 8-306 procedure

- Sys::Virt::StorageVol::WIPE\_ALG\_GUTMANN

  The canonical 35-pass sequence

- Sys::Virt::StorageVol::WIPE\_ALG\_NNSA

  4-pass NNSA Policy Letter NAP-14.1-C (XVI-8)

- Sys::Virt::StorageVol::WIPE\_ALG\_PFITZNER7

  7-pass random

- Sys::Virt::StorageVol::WIPE\_ALG\_PFITZNER33

  33-pass random

- Sys::Virt::StorageVol::WIPE\_ALG\_RANDOM

  1-pass random

- Sys::Virt::StorageVol::WIPE\_ALG\_SCHNEIER

  7-pass method described by Bruce Schneier in "Applied Cryptography" (1996)

- Sys::Virt::StorageVol::WIPE\_ALG\_ZERO

  1-pass, all zeroes

- Sys::Virt::StorageVol::WIPE\_ALG\_TRIM

  1-pass, trim all data on the volume by using TRIM or DISCARD

### VOLUME RESIZE CONSTANTS

The following constants control how storage volumes can be resized

- Sys::Virt::StorageVol::RESIZE\_ALLOCATE

  Fully allocate the extra space required during resize

- Sys::Virt::StorageVol::RESIZE\_DELTA

  Treat the new capacity as a delta to the current capacity

- Sys::Virt::StorageVol::RESIZE\_SHRINK

  Treat the new capacity as an amount to remove from the capacity

## AUTHORS

Daniel P. Berrange \<berrange@redhat.com\>

## COPYRIGHT

Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 Daniel P. Berrange

## 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.

## SEE ALSO

Sys::Virt, Sys::Virt::Error, `"http://libvirt.org"`