![]() |
![]() |
![]() |
![]() |
libvirt Reference Manual |
---|
libvirt-storage - APIs for management of storage pools and volumes
Provides APIs for the management of storage pools and volumes
Author(s): Daniel Veillard <veillard@redhat.com> Copyright (C) 2006-2016 Red Hat, Inc. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library. If not, see <http://www.gnu.org/licenses/>.
#define VIR_STORAGE_POOL_EVENT_CALLBACK; typedef enum virConnectListAllStoragePoolsFlags; typedef struct _virStoragePool virStoragePool; typedef enum virStoragePoolBuildFlags; typedef enum virStoragePoolCreateFlags; 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 struct _virStorageVolInfo virStorageVolInfo; typedef enum virStorageVolInfoFlags; typedef virStorageVolInfo * virStorageVolInfoPtr; typedef virStorageVol * virStorageVolPtr; typedef enum virStorageVolResizeFlags; typedef enum virStorageVolType; typedef enum virStorageVolWipeAlgorithm; typedef enum virStorageXMLFlags; char * virConnectFindStoragePoolSources (virConnectPtr conn,
const char * type,
const char * srcSpec,
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 void virConnectStoragePoolEventGenericCallback (virConnectPtr conn,
virStoragePoolPtr pool,
void * opaque); typedef 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 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);
#define VIR_STORAGE_POOL_EVENT_CALLBACK;
Used to cast the event specific callback into the generic one for use for virConnectStoragePoolEventRegisterAny()
enum virConnectListAllStoragePoolsFlags { VIR_CONNECT_LIST_STORAGE_POOLS_INACTIVE = 1 VIR_CONNECT_LIST_STORAGE_POOLS_ACTIVE = 2 VIR_CONNECT_LIST_STORAGE_POOLS_PERSISTENT = 4 VIR_CONNECT_LIST_STORAGE_POOLS_TRANSIENT = 8 VIR_CONNECT_LIST_STORAGE_POOLS_AUTOSTART = 16 VIR_CONNECT_LIST_STORAGE_POOLS_NO_AUTOSTART = 32 /* List pools by type */ VIR_CONNECT_LIST_STORAGE_POOLS_DIR = 64 VIR_CONNECT_LIST_STORAGE_POOLS_FS = 128 VIR_CONNECT_LIST_STORAGE_POOLS_NETFS = 256 VIR_CONNECT_LIST_STORAGE_POOLS_LOGICAL = 512 VIR_CONNECT_LIST_STORAGE_POOLS_DISK = 1024 VIR_CONNECT_LIST_STORAGE_POOLS_ISCSI = 2048 VIR_CONNECT_LIST_STORAGE_POOLS_SCSI = 4096 VIR_CONNECT_LIST_STORAGE_POOLS_MPATH = 8192 VIR_CONNECT_LIST_STORAGE_POOLS_RBD = 16384 VIR_CONNECT_LIST_STORAGE_POOLS_SHEEPDOG = 32768 VIR_CONNECT_LIST_STORAGE_POOLS_GLUSTER = 65536 VIR_CONNECT_LIST_STORAGE_POOLS_ZFS = 131072 };
struct _virStoragePool { The content of this structure is not made public by the API. } virStoragePool;
enum virStoragePoolBuildFlags { VIR_STORAGE_POOL_BUILD_NEW = 0 /* Regular build from scratch */ VIR_STORAGE_POOL_BUILD_REPAIR = 1 /* Repair / reinitialize */ VIR_STORAGE_POOL_BUILD_RESIZE = 2 /* Extend existing pool */ VIR_STORAGE_POOL_BUILD_NO_OVERWRITE = 4 /* Do not overwrite existing pool */ VIR_STORAGE_POOL_BUILD_OVERWRITE = 8 /* Overwrite data */ };
enum virStoragePoolCreateFlags { VIR_STORAGE_POOL_CREATE_NORMAL = 0 /* Create the pool and perform pool build without any flags */ VIR_STORAGE_POOL_CREATE_WITH_BUILD = 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_OVERWRITE = 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 */ VIR_STORAGE_POOL_CREATE_WITH_BUILD_NO_OVERWRITE = 4 };
enum virStoragePoolDeleteFlags { VIR_STORAGE_POOL_DELETE_NORMAL = 0 /* Delete metadata only (fast) */ VIR_STORAGE_POOL_DELETE_ZEROED = 1 /* Clear all data to zeros (slow) */ };
enum virStoragePoolEventID { VIR_STORAGE_POOL_EVENT_ID_LIFECYCLE = 0 /* virConnectStoragePoolEventLifecycleCallback */ VIR_STORAGE_POOL_EVENT_ID_REFRESH = 1 /* virConnectStoragePoolEventGenericCallback */ VIR_STORAGE_POOL_EVENT_ID_LAST = 2 /* 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. */ };
enum virStoragePoolEventLifecycleType { VIR_STORAGE_POOL_EVENT_DEFINED = 0 VIR_STORAGE_POOL_EVENT_UNDEFINED = 1 VIR_STORAGE_POOL_EVENT_STARTED = 2 VIR_STORAGE_POOL_EVENT_STOPPED = 3 VIR_STORAGE_POOL_EVENT_LAST = 4 };
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 } virStoragePoolInfo;
virStoragePoolInfo * virStoragePoolInfoPtr;
virStoragePool * virStoragePoolPtr;
a virStoragePoolPtr is pointer to a virStoragePool private structure, this is the type used to reference a storage pool in the API.
enum virStoragePoolState { VIR_STORAGE_POOL_INACTIVE = 0 /* Not running */ VIR_STORAGE_POOL_BUILDING = 1 /* Initializing pool, not available */ VIR_STORAGE_POOL_RUNNING = 2 /* Running normally */ VIR_STORAGE_POOL_DEGRADED = 3 /* Running degraded */ VIR_STORAGE_POOL_INACCESSIBLE = 4 /* Running, but not accessible */ VIR_STORAGE_POOL_STATE_LAST = 5 };
struct _virStorageVol { The content of this structure is not made public by the API. } virStorageVol;
enum virStorageVolCreateFlags { VIR_STORAGE_VOL_CREATE_PREALLOC_METADATA = 1 VIR_STORAGE_VOL_CREATE_REFLINK = 2 /* perform a btrfs lightweight copy */ };
enum virStorageVolDeleteFlags { VIR_STORAGE_VOL_DELETE_NORMAL = 0 /* Delete metadata only (fast) */ VIR_STORAGE_VOL_DELETE_ZEROED = 1 /* Clear all data to zeros (slow) */ VIR_STORAGE_VOL_DELETE_WITH_SNAPSHOTS = 2 /* Force removal of volume, even if in use */ };
struct _virStorageVolInfo { int type : virStorageVolType flags unsigned long long capacity : Logical size bytes unsigned long long allocation : Current allocation bytes } virStorageVolInfo;
enum virStorageVolInfoFlags { VIR_STORAGE_VOL_USE_ALLOCATION = 0 /* Return the physical size in allocation */ VIR_STORAGE_VOL_GET_PHYSICAL = 1 };
virStorageVolInfo * virStorageVolInfoPtr;
virStorageVol * virStorageVolPtr;
a virStorageVolPtr is pointer to a virStorageVol private structure, this is the type used to reference a storage volume in the API.
enum virStorageVolResizeFlags { VIR_STORAGE_VOL_RESIZE_ALLOCATE = 1 /* force allocation of new size */ VIR_STORAGE_VOL_RESIZE_DELTA = 2 /* size is relative to current */ VIR_STORAGE_VOL_RESIZE_SHRINK = 4 /* allow decrease in capacity */ };
enum virStorageVolType { VIR_STORAGE_VOL_FILE = 0 /* Regular file based volumes */ VIR_STORAGE_VOL_BLOCK = 1 /* Block based volumes */ VIR_STORAGE_VOL_DIR = 2 /* Directory-passthrough based volume */ VIR_STORAGE_VOL_NETWORK = 3 /* Network volumes like RBD (RADOS Block Device) */ VIR_STORAGE_VOL_NETDIR = 4 /* Network accessible directory that can contain other network volumes */ VIR_STORAGE_VOL_PLOOP = 5 /* Ploop based volumes */ VIR_STORAGE_VOL_LAST = 6 };
enum virStorageVolWipeAlgorithm { VIR_STORAGE_VOL_WIPE_ALG_ZERO = 0 /* 1-pass, all zeroes */ VIR_STORAGE_VOL_WIPE_ALG_NNSA = 1 /* 4-pass NNSA Policy Letter NAP-14.1-C (XVI-8) */ VIR_STORAGE_VOL_WIPE_ALG_DOD = 2 /* 4-pass DoD 5220.22-M section 8-306 procedure */ VIR_STORAGE_VOL_WIPE_ALG_BSI = 3 /* 9-pass method recommended by the German Center of Security in Information Technologies */ VIR_STORAGE_VOL_WIPE_ALG_GUTMANN = 4 /* The canonical 35-pass sequence */ VIR_STORAGE_VOL_WIPE_ALG_SCHNEIER = 5 /* 7-pass method described by Bruce Schneier in "Applied Cryptography" (1996) */ VIR_STORAGE_VOL_WIPE_ALG_PFITZNER7 = 6 /* 7-pass random */ VIR_STORAGE_VOL_WIPE_ALG_PFITZNER33 = 7 /* 33-pass random */ VIR_STORAGE_VOL_WIPE_ALG_RANDOM = 8 /* 1-pass random */ VIR_STORAGE_VOL_WIPE_ALG_TRIM = 9 /* 1-pass, trim all data on the volume by using TRIM or DISCARD */ VIR_STORAGE_VOL_WIPE_ALG_LAST = 10 /* 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. */ };
enum virStorageXMLFlags { VIR_STORAGE_XML_INACTIVE = 1 /* dump inactive pool/volume information */ };
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 |
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. |
opaque: | application specified data |
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. |
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
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. |
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. For more control over the results, see 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. |
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. For more control over the results, see 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. |
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 |
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 |
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 |
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. |
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 |
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 |
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 |
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: | extra flags; not used yet, so callers should always pass 0 |
Returns: | a virStoragePoolPtr object, or NULL if creation failed |
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 |
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 |
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. |
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 |
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. WARNING: When writing libvirt bindings in other languages, do not use this function. Instead, store the connection and the pool object together.
pool: | pointer to a pool |
Returns: | the virConnectPtr or NULL in case of failure. |
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. |
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 |
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; |
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; |
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 |
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 |
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 |
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. |
int virStoragePoolListVolumes (virStoragePoolPtr pool,
char ** const names,
int maxnames)
Fetch list of storage volume names, limiting to at most maxnames. To list the volume objects directly, see 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 |
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 |
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 |
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 |
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 |
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 |
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. |
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 |
int virStoragePoolSetAutostart (virStoragePoolPtr pool,
int autostart)
Sets the autostart flag
pool: | pointer to storage pool |
autostart: | new flag setting |
Returns: | 0 on success, -1 on failure |
int virStoragePoolUndefine (virStoragePoolPtr pool)
Undefine an inactive storage pool
pool: | pointer to storage pool |
Returns: | 0 on success, -1 on failure |
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 |
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 |
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 |
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. 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: | extra flags; not used yet, so callers should always pass 0 |
Returns: | 0, or -1 upon error. |
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 |
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. WARNING: When writing libvirt bindings in other languages, do not use this function. Instead, store the connection and the volume object together.
vol: | pointer to a pool |
Returns: | the virConnectPtr or NULL in case of failure. |
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 |
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 |
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 |
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 |
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. |
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 |
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 |
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 |
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 |
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. |
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. |
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. 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 the target storage pool will be refreshed 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: | extra flags; not used yet, so callers should always pass 0 |
Returns: | 0, or -1 upon error. |
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 |
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. |