Sys::V...rageVol(3pm)

📦
version 12.4.0 · 12 versions
, in epel 10

✨ NAME ✨

okay bestie, welcome to Sys::Virt::StorageVol 💖 this page lives in the User Contributed Perl Documentation manual, and the title you'd see up top is Sys::V...rageVol(3pm).

Sys::Virt::StorageVol — represent & manage a libvirt storage volume. periodt.

🦋 DESCRIPTION 🦋

okay so Sys::Virt::StorageVol is the module that represents a storage volume managed by libvirt. A storage volume is always associated with a containing storage pool, aka Sys::Virt::StoragePool — no floating volumes here, bestie 🫶

✨ METHODS ✨

  • my $name = $vol->get_name() — returns a string with the locally unique name of the storage vol.
  • my $name = $vol->get_key() — returns a string with the globally unique key for the storage vol.
  • my $name = $vol->get_path() — returns a string with the 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 deletes the storage volume and frees its storage resources 😭 the flags parameter says any special action to take when deleting the volume.
  • $vol->resize($newcapacity, $flags=0) — adjusts the size of the storage volume. The $newcapacity value semantics depend on the $flags parameter: if $flags specifies RESIZE_DELTA, then $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) — clears the data in the storage volume so you avoid future information leaks 🔥 the flags parameter is currently unused and defaults to zero.
  • $vol->wipe_pattern($algorithm, $flags = 0) — clears the data in the storage volume so you avoid future information leaks. 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) — retrieves 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 these 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); — downloads 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 set in @flags, effective transmission of holes is enabled. This assumes using the stream $st with a combination of sparse_recv_all or recv($flags = VIR_STREAM_RECV_STOP_AT_HOLE) for honouring holes sent by the server.
  • $vol->upload($st, $offset, $length, $flags=0); — uploads 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 a combination of sparse_send_all or send_hole to preserve source file sparseness.

💅 CONSTANTS 💅

okay constant stans, these sets 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 (C) 2006-2009 Red Hat
  • Copyright (C) 2006-2009 Daniel P. Berrange

⭐ LICENSE ⭐

the legal tea, bestie ☕: 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 🍓

go peek at Sys::Virt, Sys::Virt::Error, and "http://libvirt.org" 🦋

okay that’s the whole page 💅 source/version is perl v5.40.2, dated 2026-06-08 — go manage those volumes, bestie 🫶✨

📦 where this page comes from