libvirt: Module libvirt-storage from libvirt
Description: libvirt, virtualization, virtualization API

# Module libvirt-storage from libvirt

Provides APIs for the management of storage pools and volumes

## Table of Contents

### Macros

    #define VIR_STORAGE_POOL_EVENT_CALLBACK

### Types

    typedef enum virConnectListAllStoragePoolsFlags
    typedef struct _virStoragePool virStoragePool
    typedef enum virStoragePoolBuildFlags
    typedef enum virStoragePoolCreateFlags
    typedef enum virStoragePoolDefineFlags
    typedef enum virStoragePoolDeleteFlags
    typedef enum virStoragePoolEventID
    typedef enum virStoragePoolEventLifecycleType
    typedef struct _virStoragePoolInfo virStoragePoolInfo
    typedef virStoragePoolInfo * virStoragePoolInfoPtr
    typedef virStoragePool * virStoragePoolPtr
    typedef enum virStoragePoolState
    typedef struct _virStorageVol virStorageVol
    typedef enum virStorageVolCreateFlags
    typedef enum virStorageVolDeleteFlags
    typedef enum virStorageVolDownloadFlags
    typedef struct _virStorageVolInfo virStorageVolInfo
    typedef enum virStorageVolInfoFlags
    typedef virStorageVolInfo * virStorageVolInfoPtr
    typedef virStorageVol * virStorageVolPtr
    typedef enum virStorageVolResizeFlags
    typedef enum virStorageVolType
    typedef enum virStorageVolUploadFlags
    typedef enum virStorageVolWipeAlgorithm
    typedef enum virStorageXMLFlags

### Functions

    char *	virConnectFindStoragePoolSources	(virConnectPtr conn,
    						 const char * type,
    						 const char * srcSpec,
    						 unsigned int flags)
    char *	virConnectGetStoragePoolCapabilities	(virConnectPtr conn,
    						 unsigned int flags)
    int	virConnectListAllStoragePools	(virConnectPtr conn,
    					 virStoragePoolPtr ** pools,
    					 unsigned int flags)
    int	virConnectListDefinedStoragePools	(virConnectPtr conn,
    						 char ** const names,
    						 int maxnames)
    int	virConnectListStoragePools	(virConnectPtr conn,
    					 char ** const names,
    					 int maxnames)
    int	virConnectNumOfDefinedStoragePools	(virConnectPtr conn)
    int	virConnectNumOfStoragePools	(virConnectPtr conn)
    int	virConnectStoragePoolEventDeregisterAny	(virConnectPtr conn,
    						 int callbackID)
    typedef virConnectStoragePoolEventGenericCallback
    void	virConnectStoragePoolEventGenericCallback	(virConnectPtr conn,
    							 virStoragePoolPtr pool,
    							 void * opaque)

    typedef virConnectStoragePoolEventLifecycleCallback
    void	virConnectStoragePoolEventLifecycleCallback	(virConnectPtr conn,
    							 virStoragePoolPtr pool,
    							 int event,
    							 int detail,
    							 void * opaque)

    int	virConnectStoragePoolEventRegisterAny	(virConnectPtr conn,
    						 virStoragePoolPtr pool,
    						 int eventID,
    						 virConnectStoragePoolEventGenericCallback cb,
    						 void * opaque,
    						 virFreeCallback freecb)
    int	virStoragePoolBuild		(virStoragePoolPtr pool,
    					 unsigned int flags)
    int	virStoragePoolCreate		(virStoragePoolPtr pool,
    					 unsigned int flags)
    virStoragePoolPtr	virStoragePoolCreateXML	(virConnectPtr conn,
    						 const char * xmlDesc,
    						 unsigned int flags)
    virStoragePoolPtr	virStoragePoolDefineXML	(virConnectPtr conn,
    						 const char * xml,
    						 unsigned int flags)
    int	virStoragePoolDelete		(virStoragePoolPtr pool,
    					 unsigned int flags)
    int	virStoragePoolDestroy		(virStoragePoolPtr pool)
    int	virStoragePoolFree		(virStoragePoolPtr pool)
    int	virStoragePoolGetAutostart	(virStoragePoolPtr pool,
    					 int * autostart)
    virConnectPtr	virStoragePoolGetConnect	(virStoragePoolPtr pool)
    int	virStoragePoolGetInfo		(virStoragePoolPtr pool,
    					 virStoragePoolInfoPtr info)
    const char *	virStoragePoolGetName	(virStoragePoolPtr pool)
    int	virStoragePoolGetUUID		(virStoragePoolPtr pool,
    					 unsigned char * uuid)
    int	virStoragePoolGetUUIDString	(virStoragePoolPtr pool,
    					 char * buf)
    char *	virStoragePoolGetXMLDesc	(virStoragePoolPtr pool,
    					 unsigned int flags)
    int	virStoragePoolIsActive		(virStoragePoolPtr pool)
    int	virStoragePoolIsPersistent	(virStoragePoolPtr pool)
    int	virStoragePoolListAllVolumes	(virStoragePoolPtr pool,
    					 virStorageVolPtr ** vols,
    					 unsigned int flags)
    int	virStoragePoolListVolumes	(virStoragePoolPtr pool,
    					 char ** const names,
    					 int maxnames)
    virStoragePoolPtr	virStoragePoolLookupByName	(virConnectPtr conn,
    							 const char * name)
    virStoragePoolPtr	virStoragePoolLookupByTargetPath	(virConnectPtr conn,
    							 const char * path)
    virStoragePoolPtr	virStoragePoolLookupByUUID	(virConnectPtr conn,
    							 const unsigned char * uuid)
    virStoragePoolPtr	virStoragePoolLookupByUUIDString	(virConnectPtr conn,
    							 const char * uuidstr)
    virStoragePoolPtr	virStoragePoolLookupByVolume	(virStorageVolPtr vol)
    int	virStoragePoolNumOfVolumes	(virStoragePoolPtr pool)
    int	virStoragePoolRef		(virStoragePoolPtr pool)
    int	virStoragePoolRefresh		(virStoragePoolPtr pool,
    					 unsigned int flags)
    int	virStoragePoolSetAutostart	(virStoragePoolPtr pool,
    					 int autostart)
    int	virStoragePoolUndefine		(virStoragePoolPtr pool)
    virStorageVolPtr	virStorageVolCreateXML	(virStoragePoolPtr pool,
    						 const char * xmlDesc,
    						 unsigned int flags)
    virStorageVolPtr	virStorageVolCreateXMLFrom	(virStoragePoolPtr pool,
    							 const char * xmlDesc,
    							 virStorageVolPtr clonevol,
    							 unsigned int flags)
    int	virStorageVolDelete		(virStorageVolPtr vol,
    					 unsigned int flags)
    int	virStorageVolDownload		(virStorageVolPtr vol,
    					 virStreamPtr stream,
    					 unsigned long long offset,
    					 unsigned long long length,
    					 unsigned int flags)
    int	virStorageVolFree		(virStorageVolPtr vol)
    virConnectPtr	virStorageVolGetConnect	(virStorageVolPtr vol)
    int	virStorageVolGetInfo		(virStorageVolPtr vol,
    					 virStorageVolInfoPtr info)
    int	virStorageVolGetInfoFlags	(virStorageVolPtr vol,
    					 virStorageVolInfoPtr info,
    					 unsigned int flags)
    const char *	virStorageVolGetKey	(virStorageVolPtr vol)
    const char *	virStorageVolGetName	(virStorageVolPtr vol)
    char *	virStorageVolGetPath		(virStorageVolPtr vol)
    char *	virStorageVolGetXMLDesc		(virStorageVolPtr vol,
    					 unsigned int flags)
    virStorageVolPtr	virStorageVolLookupByKey	(virConnectPtr conn,
    							 const char * key)
    virStorageVolPtr	virStorageVolLookupByName	(virStoragePoolPtr pool,
    							 const char * name)
    virStorageVolPtr	virStorageVolLookupByPath	(virConnectPtr conn,
    							 const char * path)
    int	virStorageVolRef		(virStorageVolPtr vol)
    int	virStorageVolResize		(virStorageVolPtr vol,
    					 unsigned long long capacity,
    					 unsigned int flags)
    int	virStorageVolUpload		(virStorageVolPtr vol,
    					 virStreamPtr stream,
    					 unsigned long long offset,
    					 unsigned long long length,
    					 unsigned int flags)
    int	virStorageVolWipe		(virStorageVolPtr vol,
    					 unsigned int flags)
    int	virStorageVolWipePattern	(virStorageVolPtr vol,
    					 unsigned int algorithm,
    					 unsigned int flags)

## Description

### Macros

### `VIR_STORAGE_POOL_EVENT_CALLBACK`

    #define VIR_STORAGE_POOL_EVENT_CALLBACK

Used to cast the event specific callback into the generic one for use for virConnectStoragePoolEventRegisterAny()

### Types

### `virConnectListAllStoragePoolsFlags`

Flags used to tune pools returned by virConnectListAllStoragePools(). Note that these flags come in groups; if all bits from a group are 0, then that group is not used to filter results.

    enum virConnectListAllStoragePoolsFlags {

VIR_CONNECT_LIST_STORAGE_POOLS_INACTIVE | = | 1 (0x1; 1 << 0) |
VIR_CONNECT_LIST_STORAGE_POOLS_ACTIVE | = | 2 (0x2; 1 << 1) |
VIR_CONNECT_LIST_STORAGE_POOLS_PERSISTENT | = | 4 (0x4; 1 << 2) |
VIR_CONNECT_LIST_STORAGE_POOLS_TRANSIENT | = | 8 (0x8; 1 << 3) |
VIR_CONNECT_LIST_STORAGE_POOLS_AUTOSTART | = | 16 (0x10; 1 << 4) |
VIR_CONNECT_LIST_STORAGE_POOLS_NO_AUTOSTART | = | 32 (0x20; 1 << 5) |
VIR_CONNECT_LIST_STORAGE_POOLS_DIR | = | 64 (0x40; 1 << 6) |
VIR_CONNECT_LIST_STORAGE_POOLS_FS | = | 128 (0x80; 1 << 7) |
VIR_CONNECT_LIST_STORAGE_POOLS_NETFS | = | 256 (0x100; 1 << 8) |
VIR_CONNECT_LIST_STORAGE_POOLS_LOGICAL | = | 512 (0x200; 1 << 9) |
VIR_CONNECT_LIST_STORAGE_POOLS_DISK | = | 1024 (0x400; 1 << 10) |
VIR_CONNECT_LIST_STORAGE_POOLS_ISCSI | = | 2048 (0x800; 1 << 11) |
VIR_CONNECT_LIST_STORAGE_POOLS_SCSI | = | 4096 (0x1000; 1 << 12) |
VIR_CONNECT_LIST_STORAGE_POOLS_MPATH | = | 8192 (0x2000; 1 << 13) |
VIR_CONNECT_LIST_STORAGE_POOLS_RBD | = | 16384 (0x4000; 1 << 14) |
VIR_CONNECT_LIST_STORAGE_POOLS_SHEEPDOG | = | 32768 (0x8000; 1 << 15) |
VIR_CONNECT_LIST_STORAGE_POOLS_GLUSTER | = | 65536 (0x10000; 1 << 16) |
VIR_CONNECT_LIST_STORAGE_POOLS_ZFS | = | 131072 (0x20000; 1 << 17) |
VIR_CONNECT_LIST_STORAGE_POOLS_VSTORAGE | = | 262144 (0x40000; 1 << 18) |
VIR_CONNECT_LIST_STORAGE_POOLS_ISCSI_DIRECT | = | 524288 (0x80000; 1 << 19) |

    }

### `virStoragePool`

    struct virStoragePool {

The content of this structure is not made public by the API

    }

### `virStoragePoolBuildFlags`

    enum virStoragePoolBuildFlags {

VIR_STORAGE_POOL_BUILD_NEW | = | 0 (0x0) | Regular build from scratch
VIR_STORAGE_POOL_BUILD_REPAIR | = | 1 (0x1; 1 << 0) | Repair / reinitialize
VIR_STORAGE_POOL_BUILD_RESIZE | = | 2 (0x2; 1 << 1) | Extend existing pool
VIR_STORAGE_POOL_BUILD_NO_OVERWRITE | = | 4 (0x4; 1 << 2) | Do not overwrite existing pool
VIR_STORAGE_POOL_BUILD_OVERWRITE | = | 8 (0x8; 1 << 3) | Overwrite data

    }

### `virStoragePoolCreateFlags`

    enum virStoragePoolCreateFlags {

VIR_STORAGE_POOL_CREATE_NORMAL | = | 0 (0x0) | Create the pool but do not perform pool build
VIR_STORAGE_POOL_CREATE_WITH_BUILD | = | 1 (0x1; 1 << 0) | Create the pool and perform pool build without any flags
VIR_STORAGE_POOL_CREATE_WITH_BUILD_OVERWRITE | = | 2 (0x2; 1 << 1) | Create the pool and perform pool build using the VIR_STORAGE_POOL_BUILD_OVERWRITE flag. This is mutually exclusive to VIR_STORAGE_POOL_CREATE_WITH_BUILD_NO_OVERWRITE
VIR_STORAGE_POOL_CREATE_WITH_BUILD_NO_OVERWRITE | = | 4 (0x4; 1 << 2) | Create the pool and perform pool build using the VIR_STORAGE_POOL_BUILD_NO_OVERWRITE flag. This is mutually exclusive to VIR_STORAGE_POOL_CREATE_WITH_BUILD_OVERWRITE

    }

### `virStoragePoolDefineFlags`

    enum virStoragePoolDefineFlags {

VIR_STORAGE_POOL_DEFINE_VALIDATE | = | 1 (0x1; 1 << 0) | Validate the XML document against schema

    }

### `virStoragePoolDeleteFlags`

    enum virStoragePoolDeleteFlags {

VIR_STORAGE_POOL_DELETE_NORMAL | = | 0 (0x0) | Delete metadata only (fast)
VIR_STORAGE_POOL_DELETE_ZEROED | = | 1 (0x1; 1 << 0) | Clear all data to zeros (slow)

    }

### `virStoragePoolEventID`

An enumeration of supported eventId parameters for virConnectStoragePoolEventRegisterAny(). Each event id determines which signature of callback function will be used.

    enum virStoragePoolEventID {

VIR_STORAGE_POOL_EVENT_ID_LIFECYCLE | = | 0 (0x0) | virConnectStoragePoolEventLifecycleCallback
VIR_STORAGE_POOL_EVENT_ID_REFRESH | = | 1 (0x1) | virConnectStoragePoolEventGenericCallback
VIR_STORAGE_POOL_EVENT_ID_LAST | = | 2 (0x2) | NB: this enum value will increase over time as new events are added to the libvirt API. It reflects the last event ID supported by this version of the libvirt API.

    }

### `virStoragePoolEventLifecycleType`

a virStoragePoolEventLifecycleType is emitted during storage pool lifecycle events

    enum virStoragePoolEventLifecycleType {

VIR_STORAGE_POOL_EVENT_DEFINED | = | 0 (0x0) |
VIR_STORAGE_POOL_EVENT_UNDEFINED | = | 1 (0x1) |
VIR_STORAGE_POOL_EVENT_STARTED | = | 2 (0x2) |
VIR_STORAGE_POOL_EVENT_STOPPED | = | 3 (0x3) |
VIR_STORAGE_POOL_EVENT_CREATED | = | 4 (0x4) |
VIR_STORAGE_POOL_EVENT_DELETED | = | 5 (0x5) |
VIR_STORAGE_POOL_EVENT_LAST | = | 6 (0x6) |

    }

### `virStoragePoolInfo`

    struct virStoragePoolInfo {

int | state | virStoragePoolState flags
unsigned long long | capacity | Logical size bytes
unsigned long long | allocation | Current allocation bytes
unsigned long long | available | Remaining free space bytes

    }

### `virStoragePoolInfoPtr`

    typedef virStoragePoolInfo * virStoragePoolInfoPtr;

### `virStoragePoolPtr`

    typedef virStoragePool * virStoragePoolPtr;

a virStoragePoolPtr is pointer to a virStoragePool private structure, this is the type used to reference a storage pool in the API.

### `virStoragePoolState`

    enum virStoragePoolState {

VIR_STORAGE_POOL_INACTIVE | = | 0 (0x0) | Not running
VIR_STORAGE_POOL_BUILDING | = | 1 (0x1) | Initializing pool, not available
VIR_STORAGE_POOL_RUNNING | = | 2 (0x2) | Running normally
VIR_STORAGE_POOL_DEGRADED | = | 3 (0x3) | Running degraded
VIR_STORAGE_POOL_INACCESSIBLE | = | 4 (0x4) | Running, but not accessible
VIR_STORAGE_POOL_STATE_LAST | = | 5 (0x5) |

    }

### `virStorageVol`

    struct virStorageVol {

The content of this structure is not made public by the API

    }

### `virStorageVolCreateFlags`

    enum virStorageVolCreateFlags {

VIR_STORAGE_VOL_CREATE_PREALLOC_METADATA | = | 1 (0x1; 1 << 0) |
VIR_STORAGE_VOL_CREATE_REFLINK | = | 2 (0x2; 1 << 1) | perform a btrfs lightweight copy
VIR_STORAGE_VOL_CREATE_VALIDATE | = | 4 (0x4; 1 << 2) | Validate the XML document against schema

    }

### `virStorageVolDeleteFlags`

    enum virStorageVolDeleteFlags {

VIR_STORAGE_VOL_DELETE_NORMAL | = | 0 (0x0) | Delete metadata only (fast)
VIR_STORAGE_VOL_DELETE_ZEROED | = | 1 (0x1; 1 << 0) | Clear all data to zeros (slow)
VIR_STORAGE_VOL_DELETE_WITH_SNAPSHOTS | = | 2 (0x2; 1 << 1) | Force removal of volume, even if in use

    }

### `virStorageVolDownloadFlags`

    enum virStorageVolDownloadFlags {

VIR_STORAGE_VOL_DOWNLOAD_SPARSE_STREAM | = | 1 (0x1; 1 << 0) | Use sparse stream

    }

### `virStorageVolInfo`

    struct virStorageVolInfo {

int | type | virStorageVolType flags
unsigned long long | capacity | Logical size bytes
unsigned long long | allocation | Current allocation bytes

    }

### `virStorageVolInfoFlags`

    enum virStorageVolInfoFlags {

VIR_STORAGE_VOL_USE_ALLOCATION | = | 0 (0x0) |
VIR_STORAGE_VOL_GET_PHYSICAL | = | 1 (0x1; 1 << 0) | Return the physical size in allocation

    }

### `virStorageVolInfoPtr`

    typedef virStorageVolInfo * virStorageVolInfoPtr;

### `virStorageVolPtr`

    typedef virStorageVol * virStorageVolPtr;

a virStorageVolPtr is pointer to a virStorageVol private structure, this is the type used to reference a storage volume in the API.

### `virStorageVolResizeFlags`

    enum virStorageVolResizeFlags {

VIR_STORAGE_VOL_RESIZE_ALLOCATE | = | 1 (0x1; 1 << 0) | force allocation of new size
VIR_STORAGE_VOL_RESIZE_DELTA | = | 2 (0x2; 1 << 1) | size is relative to current
VIR_STORAGE_VOL_RESIZE_SHRINK | = | 4 (0x4; 1 << 2) | allow decrease in capacity

    }

### `virStorageVolType`

    enum virStorageVolType {

VIR_STORAGE_VOL_FILE | = | 0 (0x0) | Regular file based volumes
VIR_STORAGE_VOL_BLOCK | = | 1 (0x1) | Block based volumes
VIR_STORAGE_VOL_DIR | = | 2 (0x2) | Directory-passthrough based volume
VIR_STORAGE_VOL_NETWORK | = | 3 (0x3) | Network volumes like RBD (RADOS Block Device)
VIR_STORAGE_VOL_NETDIR | = | 4 (0x4) | Network accessible directory that can contain other network volumes
VIR_STORAGE_VOL_PLOOP | = | 5 (0x5) | Ploop based volumes
VIR_STORAGE_VOL_LAST | = | 6 (0x6) |

    }

### `virStorageVolUploadFlags`

    enum virStorageVolUploadFlags {

VIR_STORAGE_VOL_UPLOAD_SPARSE_STREAM | = | 1 (0x1; 1 << 0) | Use sparse stream

    }

### `virStorageVolWipeAlgorithm`

    enum virStorageVolWipeAlgorithm {

VIR_STORAGE_VOL_WIPE_ALG_ZERO | = | 0 (0x0) | 1-pass, all zeroes
VIR_STORAGE_VOL_WIPE_ALG_NNSA | = | 1 (0x1) | 4-pass NNSA Policy Letter NAP-14.1-C (XVI-8)
VIR_STORAGE_VOL_WIPE_ALG_DOD | = | 2 (0x2) | 4-pass DoD 5220.22-M section 8-306 procedure
VIR_STORAGE_VOL_WIPE_ALG_BSI | = | 3 (0x3) | 9-pass method recommended by the German Center of Security in Information Technologies
VIR_STORAGE_VOL_WIPE_ALG_GUTMANN | = | 4 (0x4) | The canonical 35-pass sequence
VIR_STORAGE_VOL_WIPE_ALG_SCHNEIER | = | 5 (0x5) | 7-pass method described by Bruce Schneier in "Applied Cryptography" (1996)
VIR_STORAGE_VOL_WIPE_ALG_PFITZNER7 | = | 6 (0x6) | 7-pass random data
VIR_STORAGE_VOL_WIPE_ALG_PFITZNER33 | = | 7 (0x7) | 33-pass random data
VIR_STORAGE_VOL_WIPE_ALG_RANDOM | = | 8 (0x8) | 1-pass random data
VIR_STORAGE_VOL_WIPE_ALG_TRIM | = | 9 (0x9) | 1-pass, trim all data on the volume by using TRIM or DISCARD
VIR_STORAGE_VOL_WIPE_ALG_LAST | = | 10 (0xa) | NB: this enum value will increase over time as new algorithms are added to the libvirt API. It reflects the last algorithm supported by this version of the libvirt API.

    }

### `virStorageXMLFlags`

    enum virStorageXMLFlags {

VIR_STORAGE_XML_INACTIVE | = | 1 (0x1; 1 << 0) | dump inactive pool/volume information

    }

### Functions

### `virConnectFindStoragePoolSources`

    char *	virConnectFindStoragePoolSources	(virConnectPtr conn,
    						 const char * type,
    						 const char * srcSpec,
    						 unsigned int flags)

Talks to a storage backend and attempts to auto-discover the set of available storage pool sources. e.g. For iSCSI this would be a set of iSCSI targets. For NFS this would be a list of exported paths. The srcSpec (optional for some storage pool types, e.g. local ones) is an instance of the storage pool's source element specifying where to look for the pools.

srcSpec is not required for some types (e.g., those querying local storage resources only)

conn
  pointer to hypervisor connection
type
  type of storage pool sources to discover
srcSpec
  XML document specifying discovery source
flags
  extra flags; not used yet, so callers should always pass 0
Returns
  an xml document consisting of a SourceList element containing a source document appropriate to the given pool type for each discovered source.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
connect | detect-storage-pools | -

### `virConnectGetStoragePoolCapabilities`

    char *	virConnectGetStoragePoolCapabilities	(virConnectPtr conn,
    						 unsigned int flags)

Prior creating a storage pool (for instance via virStoragePoolCreateXML or virStoragePoolDefineXML) it may be suitable to know what pool types are supported along with the file/disk formats for each pool.

conn
  pointer to the hypervisor connection
flags
  extra flags; not used yet, so callers should always pass 0
Returns
  NULL in case of error or an XML string defining the capabilities.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
connect | read | -

### `virConnectListAllStoragePools`

    int	virConnectListAllStoragePools	(virConnectPtr conn,
    					 virStoragePoolPtr ** pools,
    					 unsigned int flags)

Collect the list of storage pools, and allocate an array to store those objects. This API solves the race inherent between virConnectListStoragePools and virConnectListDefinedStoragePools.

Normally, all storage pools are returned; however, `flags` can be used to filter the results for a smaller list of targeted pools. The valid flags are divided into groups, where each group contains bits that describe mutually exclusive attributes of a pool, and where all bits within a group describe all possible pools.

The first group of `flags` is VIR_CONNECT_LIST_STORAGE_POOLS_ACTIVE (online) and VIR_CONNECT_LIST_STORAGE_POOLS_INACTIVE (offline) to filter the pools by state.

The second group of `flags` is VIR_CONNECT_LIST_STORAGE_POOLS_PERSITENT (defined) and VIR_CONNECT_LIST_STORAGE_POOLS_TRANSIENT (running but not defined), to filter the pools by whether they have persistent config or not.

The third group of `flags` is VIR_CONNECT_LIST_STORAGE_POOLS_AUTOSTART and VIR_CONNECT_LIST_STORAGE_POOLS_NO_AUTOSTART, to filter the pools by whether they are marked as autostart or not.

The last group of `flags` is provided to filter the pools by the types, the flags include: VIR_CONNECT_LIST_STORAGE_POOLS_DIR VIR_CONNECT_LIST_STORAGE_POOLS_FS VIR_CONNECT_LIST_STORAGE_POOLS_NETFS VIR_CONNECT_LIST_STORAGE_POOLS_LOGICAL VIR_CONNECT_LIST_STORAGE_POOLS_DISK VIR_CONNECT_LIST_STORAGE_POOLS_ISCSI VIR_CONNECT_LIST_STORAGE_POOLS_SCSI VIR_CONNECT_LIST_STORAGE_POOLS_MPATH VIR_CONNECT_LIST_STORAGE_POOLS_RBD VIR_CONNECT_LIST_STORAGE_POOLS_SHEEPDOG VIR_CONNECT_LIST_STORAGE_POOLS_GLUSTER VIR_CONNECT_LIST_STORAGE_POOLS_ZFS VIR_CONNECT_LIST_STORAGE_POOLS_VSTORAGE VIR_CONNECT_LIST_STORAGE_POOLS_ISCSI_DIRECT

conn
  Pointer to the hypervisor connection.
pools
  Pointer to a variable to store the array containing storage pool objects or NULL if the list is not required (just returns number of pools).
flags
  bitwise-OR of virConnectListAllStoragePoolsFlags.
Returns
  the number of storage pools found or -1 and sets `pools` to NULL in case of error. On success, the array stored into `pools` is guaranteed to have an extra allocated element set to NULL but not included in the return count, to make iteration easier. The caller is responsible for calling virStoragePoolFree() on each array element, then calling free() on `pools`.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
connect | search-storage-pools | -

##### Access control return value filters

Object | Permission
--- | ---
storage-pool | getattr

### `virConnectListDefinedStoragePools`

    int	virConnectListDefinedStoragePools	(virConnectPtr conn,
    						 char ** const names,
    						 int maxnames)

Provides the list of names of inactive storage pools up to maxnames. If there are more than maxnames, the remaining names will be silently ignored.

The use of this function is discouraged. Instead, use virConnectListAllStoragePools().

conn
  pointer to hypervisor connection
names
  array of char * to fill with pool names (allocated by caller)
maxnames
  size of the names array
Returns
  the number of names provided in the array or -1 in case of error. Note that this command is inherently racy; a pool can be defined between a call to virConnectNumOfDefinedStoragePools() and this call; you are only guaranteed that all currently defined pools were listed if the return is less than `maxnames`. The client must call free() on each returned name.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
connect | search-storage-pools | -

##### Access control return value filters

Object | Permission
--- | ---
storage-pool | getattr

### `virConnectListStoragePools`

    int	virConnectListStoragePools	(virConnectPtr conn,
    					 char ** const names,
    					 int maxnames)

Provides the list of names of active storage pools up to maxnames. If there are more than maxnames, the remaining names will be silently ignored.

The use of this function is discouraged. Instead, use virConnectListAllStoragePools().

conn
  pointer to hypervisor connection
names
  array of char * to fill with pool names (allocated by caller)
maxnames
  size of the names array
Returns
  the number of pools found or -1 in case of error. Note that this command is inherently racy; a pool can be started between a call to virConnectNumOfStoragePools() and this call; you are only guaranteed that all currently active pools were listed if the return is less than `maxnames`. The client must call free() on each returned name.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
connect | search-storage-pools | -

##### Access control return value filters

Object | Permission
--- | ---
storage-pool | getattr

### `virConnectNumOfDefinedStoragePools`

    int	virConnectNumOfDefinedStoragePools	(virConnectPtr conn)

Provides the number of inactive storage pools

conn
  pointer to hypervisor connection
Returns
  the number of pools found, or -1 on error

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
connect | search-storage-pools | -

##### Access control return value filters

Object | Permission
--- | ---
storage-pool | getattr

### `virConnectNumOfStoragePools`

    int	virConnectNumOfStoragePools	(virConnectPtr conn)

Provides the number of active storage pools

conn
  pointer to hypervisor connection
Returns
  the number of pools found, or -1 on error

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
connect | search-storage-pools | -

##### Access control return value filters

Object | Permission
--- | ---
storage-pool | getattr

### `virConnectStoragePoolEventDeregisterAny`

    int	virConnectStoragePoolEventDeregisterAny	(virConnectPtr conn,
    						 int callbackID)

Removes an event callback. The callbackID parameter should be the value obtained from a previous virConnectStoragePoolEventRegisterAny() method.

conn
  pointer to the connection
callbackID
  the callback identifier
Returns
  0 on success, -1 on failure

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
connect | read | -

### `virConnectStoragePoolEventGenericCallback`

    typedef void	(*virConnectStoragePoolEventGenericCallback)	(virConnectPtr conn,
    							 virStoragePoolPtr pool,
    							 void * opaque)

A generic storage pool event callback handler, for use with virConnectStoragePoolEventRegisterAny(). Specific events usually have a customization with extra parameters, often with `opaque` being passed in a different parameter position; use VIR_STORAGE_POOL_EVENT_CALLBACK() when registering an appropriate handler.

conn
  the connection pointer
pool
  the pool pointer
opaque
  application specified data

### `virConnectStoragePoolEventLifecycleCallback`

    typedef void	(*virConnectStoragePoolEventLifecycleCallback)	(virConnectPtr conn,
    							 virStoragePoolPtr pool,
    							 int event,
    							 int detail,
    							 void * opaque)

This callback is called when a pool lifecycle action is performed, like start or stop.

The callback signature to use when registering for an event of type VIR_STORAGE_POOL_EVENT_ID_LIFECYCLE with virConnectStoragePoolEventRegisterAny()

conn
  connection object
pool
  pool on which the event occurred
event
  The specific virStoragePoolEventLifecycleType which occurred
detail
  contains some details on the reason of the event (currently unused)
opaque
  application specified data

### `virConnectStoragePoolEventRegisterAny`

    int	virConnectStoragePoolEventRegisterAny	(virConnectPtr conn,
    						 virStoragePoolPtr pool,
    						 int eventID,
    						 virConnectStoragePoolEventGenericCallback cb,
    						 void * opaque,
    						 virFreeCallback freecb)

Adds a callback to receive notifications of arbitrary storage pool events occurring on a storage pool. This function requires that an event loop has been previously registered with virEventRegisterImpl() or virEventRegisterDefaultImpl().

If `pool` is NULL, then events will be monitored for any storage pool. If `pool` is non-NULL, then only the specific storage pool will be monitored.

Most types of events have a callback providing a custom set of parameters for the event. When registering an event, it is thus necessary to use the VIR_STORAGE_POOL_EVENT_CALLBACK() macro to cast the supplied function pointer to match the signature of this method.

The virStoragePoolPtr object handle passed into the callback upon delivery of an event is only valid for the duration of execution of the callback. If the callback wishes to keep the storage pool object after the callback returns, it shall take a reference to it, by calling virStoragePoolRef(). The reference can be released once the object is no longer required by calling virStoragePoolFree().

The return value from this method is a positive integer identifier for the callback. To unregister a callback, this callback ID should be passed to the virConnectStoragePoolEventDeregisterAny() method.

conn
  pointer to the connection
pool
  pointer to the storage pool
eventID
  the event type to receive
cb
  callback to the function handling network events
opaque
  opaque data to pass on to the callback
freecb
  optional function to deallocate opaque when not used anymore
Returns
  a callback identifier on success, -1 on failure.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
connect | search-storage-pools | -

##### Access control return value filters

Object | Permission
--- | ---
storage-pool | getattr

### `virStoragePoolBuild`

    int	virStoragePoolBuild		(virStoragePoolPtr pool,
    					 unsigned int flags)

Currently only filesystem pool accepts flags VIR_STORAGE_POOL_BUILD_OVERWRITE and VIR_STORAGE_POOL_BUILD_NO_OVERWRITE.

Build the underlying storage pool

pool
  pointer to storage pool
flags
  bitwise-OR of virStoragePoolBuildFlags
Returns
  0 on success, or -1 upon failure

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | format | -

### `virStoragePoolCreate`

    int	virStoragePoolCreate		(virStoragePoolPtr pool,
    					 unsigned int flags)

Starts an inactive storage pool

pool
  pointer to storage pool
flags
  bitwise-OR of virStoragePoolCreateFlags
Returns
  0 on success, or -1 if it could not be started

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | start | -

### `virStoragePoolCreateXML`

    virStoragePoolPtr	virStoragePoolCreateXML	(virConnectPtr conn,
    						 const char * xmlDesc,
    						 unsigned int flags)

Create a new storage based on its XML description. The pool is not persistent, so its definition will disappear when it is destroyed, or if the host is restarted

virStoragePoolFree should be used to free the resources after the storage pool object is no longer needed.

conn
  pointer to hypervisor connection
xmlDesc
  XML description for new pool
flags
  bitwise-OR of virStoragePoolCreateFlags
Returns
  a virStoragePoolPtr object, or NULL if creation failed

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | start | -
storage-pool | write | -

### `virStoragePoolDefineXML`

    virStoragePoolPtr	virStoragePoolDefineXML	(virConnectPtr conn,
    						 const char * xml,
    						 unsigned int flags)

Define an inactive persistent storage pool or modify an existing persistent one from the XML description.

virStoragePoolFree should be used to free the resources after the storage pool object is no longer needed.

conn
  pointer to hypervisor connection
xml
  XML description for new pool
flags
  bitwise-OR of virStoragePoolDefineFlags
Returns
  a virStoragePoolPtr object, or NULL if creation failed

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | write | -
storage-pool | save | -

### `virStoragePoolDelete`

    int	virStoragePoolDelete		(virStoragePoolPtr pool,
    					 unsigned int flags)

Delete the underlying pool resources. This is a non-recoverable operation. The virStoragePoolPtr object itself is not free'd.

pool
  pointer to storage pool
flags
  bitwise-OR of virStoragePoolDeleteFlags
Returns
  0 on success, or -1 if it could not be obliterate

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | format | -

### `virStoragePoolDestroy`

    int	virStoragePoolDestroy		(virStoragePoolPtr pool)

Destroy an active storage pool. This will deactivate the pool on the host, but keep any persistent config associated with it. If it has a persistent config it can later be restarted with virStoragePoolCreate(). This does not free the associated virStoragePoolPtr object.

pool
  pointer to storage pool
Returns
  0 on success, or -1 if it could not be destroyed

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | stop | -

### `virStoragePoolFree`

    int	virStoragePoolFree		(virStoragePoolPtr pool)

Free a storage pool object, releasing all memory associated with it. Does not change the state of the pool on the host.

pool
  pointer to storage pool
Returns
  0 on success, or -1 if it could not be free'd.

### `virStoragePoolGetAutostart`

    int	virStoragePoolGetAutostart	(virStoragePoolPtr pool,
    					 int * autostart)

Fetches the value of the autostart flag, which determines whether the pool is automatically started at boot time

pool
  pointer to storage pool
autostart
  location in which to store autostart flag
Returns
  0 on success, -1 on failure

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | read | -

### `virStoragePoolGetConnect`

    virConnectPtr	virStoragePoolGetConnect	(virStoragePoolPtr pool)

Provides the connection pointer associated with a storage pool. The reference counter on the connection is not increased by this call.

pool
  pointer to a pool
Returns
  the virConnectPtr or NULL in case of failure.

### `virStoragePoolGetInfo`

    int	virStoragePoolGetInfo		(virStoragePoolPtr pool,
    					 virStoragePoolInfoPtr info)

Get volatile information about the storage pool such as free space / usage summary

pool
  pointer to storage pool
info
  pointer at which to store info
Returns
  0 on success, or -1 on failure.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | read | -

### `virStoragePoolGetName`

    const char *	virStoragePoolGetName	(virStoragePoolPtr pool)

Fetch the locally unique name of the storage pool

pool
  pointer to storage pool
Returns
  the name of the pool, or NULL on error

### `virStoragePoolGetUUID`

    int	virStoragePoolGetUUID		(virStoragePoolPtr pool,
    					 unsigned char * uuid)

Fetch the globally unique ID of the storage pool

pool
  pointer to storage pool
uuid
  buffer of VIR_UUID_BUFLEN bytes in size
Returns
  0 on success, or -1 on error;

### `virStoragePoolGetUUIDString`

    int	virStoragePoolGetUUIDString	(virStoragePoolPtr pool,
    					 char * buf)

Fetch the globally unique ID of the storage pool as a string

pool
  pointer to storage pool
buf
  buffer of VIR_UUID_STRING_BUFLEN bytes in size
Returns
  0 on success, or -1 on error;

### `virStoragePoolGetXMLDesc`

    char *	virStoragePoolGetXMLDesc	(virStoragePoolPtr pool,
    					 unsigned int flags)

Fetch an XML document describing all aspects of the storage pool. This is suitable for later feeding back into the virStoragePoolCreateXML method.

pool
  pointer to storage pool
flags
  bitwise-OR of virStorageXMLFlags
Returns
  a XML document (caller frees), or NULL on error

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | read | -

### `virStoragePoolIsActive`

    int	virStoragePoolIsActive		(virStoragePoolPtr pool)

Determine if the storage pool is currently running

pool
  pointer to the storage pool object
Returns
  1 if running, 0 if inactive, -1 on error

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | read | -

### `virStoragePoolIsPersistent`

    int	virStoragePoolIsPersistent	(virStoragePoolPtr pool)

Determine if the storage pool has a persistent configuration which means it will still exist after shutting down

pool
  pointer to the storage pool object
Returns
  1 if persistent, 0 if transient, -1 on error

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | read | -

### `virStoragePoolListAllVolumes`

    int	virStoragePoolListAllVolumes	(virStoragePoolPtr pool,
    					 virStorageVolPtr ** vols,
    					 unsigned int flags)

Collect the list of storage volumes, and allocate an array to store those objects.

pool
  Pointer to storage pool
vols
  Pointer to a variable to store the array containing storage volume objects or NULL if the list is not required (just returns number of volumes).
flags
  extra flags; not used yet, so callers should always pass 0
Returns
  the number of storage volumes found or -1 and sets `vols` to NULL in case of error. On success, the array stored into `vols` is guaranteed to have an extra allocated element set to NULL but not included in the return count, to make iteration easier. The caller is responsible for calling virStorageVolFree() on each array element, then calling free() on `vols`.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | search-storage-vols | -

##### Access control return value filters

Object | Permission
--- | ---
storage-vol | getattr

### `virStoragePoolListVolumes`

    int	virStoragePoolListVolumes	(virStoragePoolPtr pool,
    					 char ** const names,
    					 int maxnames)

Fetch list of storage volume names, limiting to at most maxnames.

The use of this function is discouraged. Instead, use virStoragePoolListAllVolumes().

pool
  pointer to storage pool
names
  array in which to storage volume names
maxnames
  size of names array
Returns
  the number of names fetched, or -1 on error

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | search-storage-vols | -

##### Access control return value filters

Object | Permission
--- | ---
storage-vol | getattr

### `virStoragePoolLookupByName`

    virStoragePoolPtr	virStoragePoolLookupByName	(virConnectPtr conn,
    							 const char * name)

Fetch a storage pool based on its unique name

virStoragePoolFree should be used to free the resources after the storage pool object is no longer needed.

conn
  pointer to hypervisor connection
name
  name of pool to fetch
Returns
  a virStoragePoolPtr object, or NULL if no matching pool is found

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | getattr | -

### `virStoragePoolLookupByTargetPath`

    virStoragePoolPtr	virStoragePoolLookupByTargetPath	(virConnectPtr conn,
    							 const char * path)

Fetch a storage pool which maps to a particular target directory. If more than one pool maps to the path, it is undefined which will be returned first.

virStoragePoolFree should be used to free the resources after the storage pool object is no longer needed.

conn
  pointer to hypervisor connection
path
  path at which the pool is exposed
Returns
  a virStoragePoolPtr object, or NULL if no matching pool is found

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | getattr | -

### `virStoragePoolLookupByUUID`

    virStoragePoolPtr	virStoragePoolLookupByUUID	(virConnectPtr conn,
    							 const unsigned char * uuid)

Fetch a storage pool based on its globally unique id

virStoragePoolFree should be used to free the resources after the storage pool object is no longer needed.

conn
  pointer to hypervisor connection
uuid
  globally unique id of pool to fetch
Returns
  a virStoragePoolPtr object, or NULL if no matching pool is found

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | getattr | -

### `virStoragePoolLookupByUUIDString`

    virStoragePoolPtr	virStoragePoolLookupByUUIDString	(virConnectPtr conn,
    							 const char * uuidstr)

Fetch a storage pool based on its globally unique id

virStoragePoolFree should be used to free the resources after the storage pool object is no longer needed.

conn
  pointer to hypervisor connection
uuidstr
  globally unique id of pool to fetch
Returns
  a virStoragePoolPtr object, or NULL if no matching pool is found

### `virStoragePoolLookupByVolume`

    virStoragePoolPtr	virStoragePoolLookupByVolume	(virStorageVolPtr vol)

Fetch a storage pool which contains a particular volume

virStoragePoolFree should be used to free the resources after the storage pool object is no longer needed.

vol
  pointer to storage volume
Returns
  a virStoragePoolPtr object, or NULL if no matching pool is found

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | getattr | -

### `virStoragePoolNumOfVolumes`

    int	virStoragePoolNumOfVolumes	(virStoragePoolPtr pool)

Fetch the number of storage volumes within a pool

pool
  pointer to storage pool
Returns
  the number of storage pools, or -1 on failure

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | search-storage-vols | -

##### Access control return value filters

Object | Permission
--- | ---
storage-vol | getattr

### `virStoragePoolRef`

    int	virStoragePoolRef		(virStoragePoolPtr pool)

Increment the reference count on the pool. For each additional call to this method, there shall be a corresponding call to virStoragePoolFree to release the reference count, once the caller no longer needs the reference to this object.

This method is typically useful for applications where multiple threads are using a connection, and it is required that the connection remain open until all threads have finished using it. ie, each new thread using a pool would increment the reference count.

pool
  the pool to hold a reference on
Returns
  0 in case of success, -1 in case of failure.

### `virStoragePoolRefresh`

    int	virStoragePoolRefresh		(virStoragePoolPtr pool,
    					 unsigned int flags)

Request that the pool refresh its list of volumes. This may involve communicating with a remote server, and/or initializing new devices at the OS layer

pool
  pointer to storage pool
flags
  extra flags; not used yet, so callers should always pass 0
Returns
  0 if the volume list was refreshed, -1 on failure

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | refresh | -

### `virStoragePoolSetAutostart`

    int	virStoragePoolSetAutostart	(virStoragePoolPtr pool,
    					 int autostart)

Configure the storage pool to be automatically started when the host machine boots.

pool
  pointer to storage pool
autostart
  whether the storage pool should be automatically started 0 or 1
Returns
  0 on success, -1 on failure

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | write | -

### `virStoragePoolUndefine`

    int	virStoragePoolUndefine		(virStoragePoolPtr pool)

Undefine an inactive storage pool

pool
  pointer to storage pool
Returns
  0 on success, -1 on failure

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-pool | delete | -

### `virStorageVolCreateXML`

    virStorageVolPtr	virStorageVolCreateXML	(virStoragePoolPtr pool,
    						 const char * xmlDesc,
    						 unsigned int flags)

Create a storage volume within a pool based on an XML description. Not all pools support creation of volumes.

Since 1.0.1 VIR_STORAGE_VOL_CREATE_PREALLOC_METADATA in flags can be used to get higher performance with qcow2 image files which don't support full preallocation, by creating a sparse image file with metadata.

virStorageVolFree should be used to free the resources after the storage volume object is no longer needed.

pool
  pointer to storage pool
xmlDesc
  description of volume to create
flags
  bitwise-OR of virStorageVolCreateFlags
Returns
  the storage volume, or NULL on error

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-vol | create | -

### `virStorageVolCreateXMLFrom`

    virStorageVolPtr	virStorageVolCreateXMLFrom	(virStoragePoolPtr pool,
    							 const char * xmlDesc,
    							 virStorageVolPtr clonevol,
    							 unsigned int flags)

Create a storage volume in the parent pool, using the 'clonevol' volume as input. Information for the new volume (name, perms) are passed via a typical volume XML description.

Since 1.0.1 VIR_STORAGE_VOL_CREATE_PREALLOC_METADATA in flags can be used to get higher performance with qcow2 image files which don't support full preallocation, by creating a sparse image file with metadata.

virStorageVolFree should be used to free the resources after the storage volume object is no longer needed.

pool
  pointer to parent pool for the new volume
xmlDesc
  description of volume to create
clonevol
  storage volume to use as input
flags
  bitwise-OR of virStorageVolCreateFlags
Returns
  the storage volume, or NULL on error

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-vol | create | -

### `virStorageVolDelete`

    int	virStorageVolDelete		(virStorageVolPtr vol,
    					 unsigned int flags)

Delete the storage volume from the pool

vol
  pointer to storage volume
flags
  bitwise-OR of virStorageVolDeleteFlags
Returns
  0 on success, or -1 on error

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-vol | delete | -

### `virStorageVolDownload`

    int	virStorageVolDownload		(virStorageVolPtr vol,
    					 virStreamPtr stream,
    					 unsigned long long offset,
    					 unsigned long long length,
    					 unsigned int flags)

Download the content of the volume as a stream. If `length` is zero, then the remaining contents of the volume after `offset` will be downloaded. Please note that the stream transports the volume itself as is, so the downloaded data may not correspond to guest OS visible state in cases when a complex storage format such as qcow2 or vmdk is used.

If VIR_STORAGE_VOL_DOWNLOAD_SPARSE_STREAM is set in `flags` effective transmission of holes is enabled. This assumes using the `stream` with combination of virStreamSparseRecvAll() or virStreamRecvFlags(stream, ..., flags = VIR_STREAM_RECV_STOP_AT_HOLE) for honouring holes sent by server.

This call sets up an asynchronous stream; subsequent use of stream APIs is necessary to transfer the actual data, determine how much data is successfully transferred, and detect any errors. The results will be unpredictable if another active stream is writing to the storage volume.

vol
  pointer to volume to download from
stream
  stream to use as output
offset
  position in `vol` to start reading from
length
  limit on amount of data to download
flags
  bitwise-OR of virStorageVolDownloadFlags
Returns
  0, or -1 upon error.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-vol | data-read | -

### `virStorageVolFree`

    int	virStorageVolFree		(virStorageVolPtr vol)

Release the storage volume handle. The underlying storage volume continues to exist.

vol
  pointer to storage volume
Returns
  0 on success, or -1 on error

### `virStorageVolGetConnect`

    virConnectPtr	virStorageVolGetConnect	(virStorageVolPtr vol)

Provides the connection pointer associated with a storage volume. The reference counter on the connection is not increased by this call.

vol
  pointer to a pool
Returns
  the virConnectPtr or NULL in case of failure.

### `virStorageVolGetInfo`

    int	virStorageVolGetInfo		(virStorageVolPtr vol,
    					 virStorageVolInfoPtr info)

Fetches volatile information about the storage volume such as its current allocation

vol
  pointer to storage volume
info
  pointer at which to store info
Returns
  0 on success, or -1 on failure

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-vol | read | -

### `virStorageVolGetInfoFlags`

    int	virStorageVolGetInfoFlags	(virStorageVolPtr vol,
    					 virStorageVolInfoPtr info,
    					 unsigned int flags)

Fetches volatile information about the storage volume such as its current allocation.

If the `flags` argument is VIR_STORAGE_VOL_GET_PHYSICAL, then the physical bytes used for the volume will be returned in the `info` allocation field. This is useful for sparse files and certain volume file types where the physical on disk usage can be different than the calculated allocation value as is the case with qcow2 files.

vol
  pointer to storage volume
info
  pointer at which to store info
flags
  bitwise-OR of virStorageVolInfoFlags
Returns
  0 on success, or -1 on failure

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-vol | read | -

### `virStorageVolGetKey`

    const char *	virStorageVolGetKey	(virStorageVolPtr vol)

Fetch the storage volume key. This is globally unique, so the same volume will have the same key no matter what host it is accessed from

vol
  pointer to storage volume
Returns
  the volume key, or NULL on error

### `virStorageVolGetName`

    const char *	virStorageVolGetName	(virStorageVolPtr vol)

Fetch the storage volume name. This is unique within the scope of a pool

vol
  pointer to storage volume
Returns
  the volume name, or NULL on error

### `virStorageVolGetPath`

    char *	virStorageVolGetPath		(virStorageVolPtr vol)

Fetch the storage volume path. Depending on the pool configuration this is either persistent across hosts, or dynamically assigned at pool startup. Consult pool documentation for information on getting the persistent naming

vol
  pointer to storage volume
Returns
  the storage volume path, or NULL on error. The caller must free() the returned path after use.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-vol | read | -

### `virStorageVolGetXMLDesc`

    char *	virStorageVolGetXMLDesc		(virStorageVolPtr vol,
    					 unsigned int flags)

Fetch an XML document describing all aspects of the storage volume

vol
  pointer to storage volume
flags
  extra flags; not used yet, so callers should always pass 0
Returns
  the XML document, or NULL on error

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-vol | read | -

### `virStorageVolLookupByKey`

    virStorageVolPtr	virStorageVolLookupByKey	(virConnectPtr conn,
    							 const char * key)

Fetch a pointer to a storage volume based on its globally unique key

virStorageVolFree should be used to free the resources after the storage volume object is no longer needed.

conn
  pointer to hypervisor connection
key
  globally unique key
Returns
  a storage volume, or NULL if not found / error

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-vol | getattr | -

### `virStorageVolLookupByName`

    virStorageVolPtr	virStorageVolLookupByName	(virStoragePoolPtr pool,
    							 const char * name)

Fetch a pointer to a storage volume based on its name within a pool

virStorageVolFree should be used to free the resources after the storage volume object is no longer needed.

pool
  pointer to storage pool
name
  name of storage volume
Returns
  a storage volume, or NULL if not found / error

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-vol | getattr | -

### `virStorageVolLookupByPath`

    virStorageVolPtr	virStorageVolLookupByPath	(virConnectPtr conn,
    							 const char * path)

Fetch a pointer to a storage volume based on its locally (host) unique path

virStorageVolFree should be used to free the resources after the storage volume object is no longer needed.

conn
  pointer to hypervisor connection
path
  locally unique path
Returns
  a storage volume, or NULL if not found / error

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-vol | getattr | -

### `virStorageVolRef`

    int	virStorageVolRef		(virStorageVolPtr vol)

Increment the reference count on the vol. For each additional call to this method, there shall be a corresponding call to virStorageVolFree to release the reference count, once the caller no longer needs the reference to this object.

This method is typically useful for applications where multiple threads are using a connection, and it is required that the connection remain open until all threads have finished using it. ie, each new thread using a vol would increment the reference count.

vol
  the vol to hold a reference on
Returns
  0 in case of success, -1 in case of failure.

### `virStorageVolResize`

    int	virStorageVolResize		(virStorageVolPtr vol,
    					 unsigned long long capacity,
    					 unsigned int flags)

Changes the capacity of the storage volume `vol` to `capacity`. The operation will fail if the new capacity requires allocation that would exceed the remaining free space in the parent pool. The contents of the new capacity will appear as all zero bytes. The capacity value will be rounded to the granularity supported by the hypervisor.

Normally, the operation will attempt to affect capacity with a minimum impact on allocation (that is, the default operation favors a sparse resize). If `flags` contains VIR_STORAGE_VOL_RESIZE_ALLOCATE, then the operation will ensure that allocation is sufficient for the new capacity; this may make the operation take noticeably longer.

Normally, the operation treats `capacity` as the new size in bytes; but if `flags` contains VIR_STORAGE_VOL_RESIZE_DELTA, then `capacity` represents the size difference to add to the current size. It is up to the storage pool implementation whether unaligned requests are rounded up to the next valid boundary, or rejected.

Normally, this operation should only be used to enlarge capacity; but if `flags` contains VIR_STORAGE_VOL_RESIZE_SHRINK, it is possible to attempt a reduction in capacity even though it might cause data loss. If VIR_STORAGE_VOL_RESIZE_DELTA is also present, then `capacity` is subtracted from the current size; without it, `capacity` represents the absolute new size regardless of whether it is larger or smaller than the current size.

vol
  pointer to storage volume
capacity
  new capacity, in bytes
flags
  bitwise-OR of virStorageVolResizeFlags
Returns
  0 on success, or -1 on error.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-vol | resize | -

### `virStorageVolUpload`

    int	virStorageVolUpload		(virStorageVolPtr vol,
    					 virStreamPtr stream,
    					 unsigned long long offset,
    					 unsigned long long length,
    					 unsigned int flags)

Upload new content to the volume from a stream. This call will fail if `offset` + `length` exceeds the size of the volume. Otherwise, if `length` is non-zero, an error will be raised if an attempt is made to upload greater than `length` bytes of data. Please note that the stream transports the volume itself as is, so the downloaded data may not correspond to guest OS visible state in cases when a complex storage format such as qcow2 or vmdk is used.

If VIR_STORAGE_VOL_UPLOAD_SPARSE_STREAM is set in `flags` effective transmission of holes is enabled. This assumes using the `stream` with combination of virStreamSparseSendAll() or virStreamSendHole() to preserve source file sparseness.

This call sets up an asynchronous stream; subsequent use of stream APIs is necessary to transfer the actual data, determine how much data is successfully transferred, and detect any errors. The results will be unpredictable if another active stream is writing to the storage volume.

When the data stream is closed whether the upload is successful or not an attempt will be made to refresh the target storage pool if an asynchronous build is not running in order to reflect pool and volume changes as a result of the upload. Depending on the target volume storage backend and the source stream type for a successful upload, the target volume may take on the characteristics from the source stream such as format type, capacity, and allocation.

vol
  pointer to volume to upload
stream
  stream to use as input
offset
  position to start writing to
length
  limit on amount of data to upload
flags
  bitwise-OR of virStorageVolUploadFlags
Returns
  0, or -1 upon error.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-vol | data-write | -

### `virStorageVolWipe`

    int	virStorageVolWipe		(virStorageVolPtr vol,
    					 unsigned int flags)

Ensure data previously on a volume is not accessible to future reads.

The data to be wiped may include the format and possibly size information, so non-raw images might become raw with a different size. It is storage backend dependent whether the format and size information is regenerated once the initial volume wipe is completed.

Depending on the actual volume representation, this call may not overwrite the physical location of the volume. For instance, files stored journaled, log structured, copy-on-write, versioned, and network file systems are known to be problematic.

vol
  pointer to storage volume
flags
  extra flags; not used yet, so callers should always pass 0
Returns
  0 on success, or -1 on error

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-vol | format | -

### `virStorageVolWipePattern`

    int	virStorageVolWipePattern	(virStorageVolPtr vol,
    					 unsigned int algorithm,
    					 unsigned int flags)

Similar to virStorageVolWipe, but one can choose between different wiping algorithms. Also note, that depending on the actual volume representation, this call may not really overwrite the physical location of the volume. For instance, files stored journaled, log structured, copy-on-write, versioned, and network file systems are known to be problematic.

vol
  pointer to storage volume
algorithm
  one of virStorageVolWipeAlgorithm
flags
  future flags, use 0 for now
Returns
  0 on success, or -1 on error.

##### Access control parameter checks

Object | Permission | Condition
--- | --- | ---
storage-vol | format | -