APIs for management of domain snapshotsProvides APIs for the management of domain snapshotsDaniel Veillard <veillard@redhat.com> Copyright (C) 2006-2014 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/>. APIs for management of domainsProvides APIs for the management of domainsDaniel Veillard <veillard@redhat.com> Copyright (C) 2006-2015 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/>. APIs for management of eventsProvides APIs for the management of eventsDaniel Veillard <veillard@redhat.com> Copyright (C) 2006-2014 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/>. APIs for management of hostsProvides APIs for the management of hostsDaniel Veillard <veillard@redhat.com> Copyright (C) 2006-2014 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/>. APIs for management of interfacesProvides APIs for the management of interfacesDaniel Veillard <veillard@redhat.com> Copyright (C) 2006-2014 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/>. APIs for management of networksProvides APIs for the management of networksDaniel Veillard <veillard@redhat.com> Copyright (C) 2006-2014 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/>. APIs for management of nodedevsProvides APIs for the management of nodedevsDaniel Veillard <veillard@redhat.com> Copyright (C) 2006-2014 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/>. APIs for management of nwfiltersProvides APIs for the management of nwfiltersDaniel Veillard <veillard@redhat.com> Copyright (C) 2006-2014 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/>. APIs for management of secretsProvides APIs for the management of secretsDaniel Veillard <veillard@redhat.com> Copyright (C) 2006-2014, 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/>. APIs for management of storage pools and volumesProvides APIs for the management of storage pools and volumesDaniel 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/>. APIs for management of streamsProvides APIs for the management of streamsDaniel Veillard <veillard@redhat.com> Copyright (C) 2006-2014 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/>. error handling interfaces for the libvirt libraryProvides the interfaces of the libvirt library to handle errors raised while using the library. 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/>. Daniel Veillard <veillard@redhat.com> sub-element, such as "vda").]]>.* array could be sparse.
The actual size of the array corresponds to "vcpu.current".
The array size will never exceed "vcpu.maximum".
The typed parameter keys are in this format:
"vcpu.current" - current number of online virtual CPUs as unsigned int.
"vcpu.maximum" - maximum number of online virtual CPUs as unsigned int.
"vcpu..state" - state of the virtual CPU , as int
from virVcpuState enum.
"vcpu..time" - virtual cpu time spent by virtual CPU
as unsigned long long.
VIR_DOMAIN_STATS_INTERFACE: Return network interface statistics.
The typed parameter keys are in this format:
"net.count" - number of network interfaces on this domain
as unsigned int.
"net..name" - name of the interface as string.
"net..rx.bytes" - bytes received as unsigned long long.
"net..rx.pkts" - packets received as unsigned long long.
"net..rx.errs" - receive errors as unsigned long long.
"net..rx.drop" - receive packets dropped as unsigned long long.
"net..tx.bytes" - bytes transmitted as unsigned long long.
"net..tx.pkts" - packets transmitted as unsigned long long.
"net..tx.errs" - transmission errors as unsigned long long.
"net..tx.drop" - transmit packets dropped as unsigned long long.
VIR_DOMAIN_STATS_BLOCK: Return block devices statistics. By default,
this information is limited to the active layer of each of the
domain (where block.count is equal to the number of disks), but adding
VIR_CONNECT_GET_ALL_DOMAINS_STATS_BACKING to @flags will expand the
array to cover backing chains (block.count corresponds to the number
of host resources used together to provide the guest disks).
The typed parameter keys are in this format:
"block.count" - number of block devices in the subsequent list,
as unsigned int.
"block..name" - name of the block device as string.
matches the target name (vda/sda/hda) of the
block device. If the backing chain is listed,
this name is the same for all host resources tied
to the same guest device.
"block..backingIndex" - unsigned int giving the index,
only used when backing images are listed.
"block..path" - string describing the source of block device ,
if it is a file or block device (omitted for network
sources and drives with no media inserted).
"block..rd.reqs" - number of read requests as unsigned long long.
"block..rd.bytes" - number of read bytes as unsigned long long.
"block..rd.times" - total time (ns) spent on reads as
unsigned long long.
"block..wr.reqs" - number of write requests as unsigned long long.
"block..wr.bytes" - number of written bytes as unsigned long long.
"block..wr.times" - total time (ns) spent on writes as
unsigned long long.
"block..fl.reqs" - total flush requests as unsigned long long.
"block..fl.times" - total time (ns) spent on cache flushing as
unsigned long long.
"block..errors" - Xen only: the 'oo_req' value as
unsigned long long.
"block..allocation" - offset of the highest written sector
as unsigned long long.
"block..capacity" - logical size in bytes of the block device backing
image as unsigned long long.
"block..physical" - physical size in bytes of the container of the
backing image as unsigned long long.
VIR_DOMAIN_STATS_PERF: Return perf event statistics.
The typed parameter keys are in this format:
"perf.cmt" - the usage of l3 cache (bytes) by applications running on the
platform as unsigned long long. It is produced by cmt perf
event.
"perf.mbmt" - the total system bandwidth (bytes/s) from one level of cache
to another as unsigned long long. It is produced by mbmt perf
event.
"perf.mbml" - the amount of data (bytes/s) sent through the memory controller
on the socket as unsigned long long. It is produced by mbml
perf event.
Note that entire stats groups or individual stat fields may be missing from
the output in case they are not supported by the given hypervisor, are not
applicable for the current state of the guest domain, or their retrieval
was not successful.
Using 0 for @stats returns all stats groups supported by the given
hypervisor.
Specifying VIR_CONNECT_GET_ALL_DOMAINS_STATS_ENFORCE_STATS as @flags makes
the function return error in case some of the stat types in @stats were
not recognized by the daemon. However, even with this flag, a hypervisor
may omit individual fields within a known group if the information is not
available; as an extreme example, a supported group may produce zero
fields for offline domains if the statistics are meaningful only for a
running domain.
Similarly to virConnectListAllDomains, @flags can contain various flags to
filter the list of domains to provide stats for.
VIR_CONNECT_GET_ALL_DOMAINS_STATS_ACTIVE selects online domains while
VIR_CONNECT_GET_ALL_DOMAINS_STATS_INACTIVE selects offline ones.
VIR_CONNECT_GET_ALL_DOMAINS_STATS_PERSISTENT and
VIR_CONNECT_GET_ALL_DOMAINS_STATS_TRANSIENT allow to filter the list
according to their persistence.
To filter the list of VMs by domain state @flags can contain
VIR_CONNECT_GET_ALL_DOMAINS_STATS_RUNNING,
VIR_CONNECT_GET_ALL_DOMAINS_STATS_PAUSED,
VIR_CONNECT_GET_ALL_DOMAINS_STATS_SHUTOFF and/or
VIR_CONNECT_GET_ALL_DOMAINS_STATS_OTHER for all other states.]]> element of the XML. This API doesn't take emulator
limits into consideration, hence the returned value is not guaranteed to be
usable. It is recommended to use virConnectGetDomainCapabilities() and look
for "" in its output instead.]]> element of a domain XML. This information is generally
available only for hypervisors running with root privileges.]]> sub-element, such as
"/path/to/image"), or the device target shorthand (the
sub-element, such as "vda"). Valid names
can be found by calling virDomainGetXMLDesc() and inspecting
elements within //domain/devices/disk.
The @base and @top parameters can be either paths to files within the
backing chain, or the device target shorthand (the
sub-element, such as "vda") followed by an index to the backing chain
enclosed in square brackets. Backing chain indexes can be found by
inspecting //disk//backingStore/@index in the domain XML. Thus, for
example, "vda[3]" refers to the backing store with index equal to "3"
in the chain of disk "vda".
The maximum bandwidth that will be used to do the commit can be
specified with the @bandwidth parameter. If set to 0, there is no
limit. If @flags includes VIR_DOMAIN_BLOCK_COMMIT_BANDWIDTH_BYTES,
@bandwidth is in bytes/second; otherwise, it is in MiB/second.
Values larger than 2^52 bytes/sec may be rejected due to overflow
considerations based on the word size of both client and server,
and values larger than 2^31 bytes/sec may cause overflow problems
if later queried by virDomainGetBlockJobInfo() without scaling.
Hypervisors may further restrict the range of valid bandwidth
values. Some hypervisors do not support this feature and will
return an error if bandwidth is not 0; in this case, it might still
be possible for a later call to virDomainBlockJobSetSpeed() to
succeed. The actual speed can be determined with
virDomainGetBlockJobInfo().]]>, and
resembles what is used when hot-plugging a disk via virDomainAttachDevice(),
except that only sub-elements related to describing the new host resource
are necessary (sub-elements related to the guest view, such as ,
are ignored). It is strongly recommended to include a
format designation for the destination, to avoid the potential of any
security problem that might be caused by probing a file for its format.
This command starts a long-running copy. By default, the copy will pull
the entire source chain into the destination file, but if @flags also
contains VIR_DOMAIN_BLOCK_COPY_SHALLOW, then only the top of the source
chain will be copied (the source and destination have a common backing
file). The format of the destination file is controlled by the
sub-element of the XML. The destination will be created unless the
VIR_DOMAIN_BLOCK_COPY_REUSE_EXT flag is present stating that the file
was pre-created with the correct format and metadata and sufficient
size to hold the copy. In case the VIR_DOMAIN_BLOCK_COPY_SHALLOW flag
is used the pre-created file has to exhibit the same guest visible contents
as the backing file of the original image. This allows a management app to
pre-create files with relative backing file names, rather than the default
of absolute backing file names.
A copy job has two parts; in the first phase, the source is copied into
the destination, and the job can only be canceled by reverting to the
source file; progress in this phase can be tracked via the
virDomainBlockJobInfo() command, with a job type of
VIR_DOMAIN_BLOCK_JOB_TYPE_COPY. The job transitions to the second
phase when the job info states cur == end, and remains alive to mirror
all further changes to both source and destination. The user must
call virDomainBlockJobAbort() to end the mirroring while choosing
whether to revert to source or pivot to the destination. An event is
issued when the job ends, and depending on the hypervisor, an event may
also be issued when the job transitions from pulling to mirroring. If
the job is aborted, a new job will have to start over from the beginning
of the first phase.
Some hypervisors will restrict certain actions, such as virDomainSave()
or virDomainDetachDevice(), while a copy job is active; they may
also restrict a copy job to transient domains.
The @disk parameter is either an unambiguous source name of the
block device (the sub-element, such as
"/path/to/image"), or the device target shorthand (the
sub-element, such as "vda"). Valid names
can be found by calling virDomainGetXMLDesc() and inspecting
elements within //domain/devices/disk.
The @params and @nparams arguments can be used to set hypervisor-specific
tuning parameters, such as maximum bandwidth or granularity. For a
parameter that the hypervisor understands, explicitly specifying 0
behaves the same as omitting the parameter, to use the hypervisor
default; however, omitting a parameter is less likely to fail.
This command is a superset of the older virDomainBlockRebase() when used
with the VIR_DOMAIN_BLOCK_REBASE_COPY flag, and offers better control
over the destination format, the ability to copy to a destination that
is not a local file, and the possibility of additional tuning parameters.]]> sub-element, such as
"/path/to/image"), or (since 0.9.5) the device target shorthand
(the sub-element, such as "vda"). Valid names
can be found by calling virDomainGetXMLDesc() and inspecting
elements within //domain/devices/disk.
If the current block job for @disk is VIR_DOMAIN_BLOCK_JOB_TYPE_PULL, then
by default, this function performs a synchronous operation and the caller
may assume that the operation has completed when 0 is returned. However,
BlockJob operations may take a long time to cancel, and during this time
further domain interactions may be unresponsive. To avoid this problem,
pass VIR_DOMAIN_BLOCK_JOB_ABORT_ASYNC in the @flags argument to enable
asynchronous behavior, returning as soon as possible. When the job has
been canceled, a BlockJob event will be emitted, with status
VIR_DOMAIN_BLOCK_JOB_CANCELED (even if the ABORT_ASYNC flag was not
used); it is also possible to poll virDomainBlockJobInfo() to see if
the job cancellation is still pending. This type of job can be restarted
to pick up from where it left off.
If the current block job for @disk is VIR_DOMAIN_BLOCK_JOB_TYPE_COPY, then
the default is to abort the mirroring and revert to the source disk;
likewise, if the current job is VIR_DOMAIN_BLOCK_JOB_TYPE_ACTIVE_COMMIT,
the default is to abort without changing the active layer of @disk.
Adding @flags of VIR_DOMAIN_BLOCK_JOB_ABORT_PIVOT causes this call to
fail with VIR_ERR_BLOCK_COPY_ACTIVE if the copy or commit is not yet
ready; otherwise it will swap the disk over to the new active image
to end the mirroring or active commit. An event will be issued when the
job is ended, and it is possible to use VIR_DOMAIN_BLOCK_JOB_ABORT_ASYNC
to control whether this command waits for the completion of the job.
Restarting a copy or active commit job requires starting over from the
beginning of the first phase.]]> sub-element, such as
"/path/to/image"), or (since 0.9.5) the device target shorthand
(the sub-element, such as "vda"). Valid names
can be found by calling virDomainGetXMLDesc() and inspecting
elements within //domain/devices/disk.]]> sub-element, such as
"/path/to/image"), or (since 0.9.5) the device target shorthand
(the sub-element, such as "vda"). Valid names
can be found by calling virDomainGetXMLDesc() and inspecting
elements within //domain/devices/disk.
'offset' and 'size' represent an area which must lie entirely
within the device or file. 'size' may be 0 to test if the
call would succeed.
'buffer' is the return buffer and must be at least 'size' bytes.
NB. The remote driver imposes a 64K byte limit on 'size'.
For your program to be able to work reliably over a remote
connection you should split large requests to <= 65536 bytes.
However, with 0.9.13 this RPC limit has been raised to 1M byte.
Starting with version 1.0.6 the RPC limit has been raised again.
Now large requests up to 16M byte are supported.]]> sub-element, such as
"/path/to/image"), or (since 0.9.5) the device target shorthand
(the sub-element, such as "vda"). Valid names
can be found by calling virDomainGetXMLDesc() and inspecting
elements within //domain/devices/disk.
The maximum bandwidth that will be used to do the copy can be
specified with the @bandwidth parameter. If set to 0, there is no
limit. If @flags includes VIR_DOMAIN_BLOCK_PULL_BANDWIDTH_BYTES,
@bandwidth is in bytes/second; otherwise, it is in MiB/second.
Values larger than 2^52 bytes/sec may be rejected due to overflow
considerations based on the word size of both client and server,
and values larger than 2^31 bytes/sec may cause overflow problems
if later queried by virDomainGetBlockJobInfo() without scaling.
Hypervisors may further restrict the range of valid bandwidth
values. Some hypervisors do not support this feature and will
return an error if bandwidth is not 0; in this case, it might still
be possible for a later call to virDomainBlockJobSetSpeed() to
succeed. The actual speed can be determined with
virDomainGetBlockJobInfo().
This is shorthand for virDomainBlockRebase() with a NULL base.]]> sub-element, such as
"/path/to/image"), or the device target shorthand (the
sub-element, such as "vda"). Valid names
can be found by calling virDomainGetXMLDesc() and inspecting
elements within //domain/devices/disk.
The @base parameter can be either a path to a file within the backing
chain, or the device target shorthand (the
sub-element, such as "vda") followed by an index to the backing chain
enclosed in square brackets. Backing chain indexes can be found by
inspecting //disk//backingStore/@index in the domain XML. Thus, for
example, "vda[3]" refers to the backing store with index equal to "3"
in the chain of disk "vda".
The maximum bandwidth that will be used to do the copy can be
specified with the @bandwidth parameter. If set to 0, there is no
limit. If @flags includes VIR_DOMAIN_BLOCK_REBASE_BANDWIDTH_BYTES,
@bandwidth is in bytes/second; otherwise, it is in MiB/second.
Values larger than 2^52 bytes/sec may be rejected due to overflow
considerations based on the word size of both client and server,
and values larger than 2^31 bytes/sec may cause overflow problems
if later queried by virDomainGetBlockJobInfo() without scaling.
Hypervisors may further restrict the range of valid bandwidth
values. Some hypervisors do not support this feature and will
return an error if bandwidth is not 0; in this case, it might still
be possible for a later call to virDomainBlockJobSetSpeed() to
succeed. The actual speed can be determined with
virDomainGetBlockJobInfo().
When @base is NULL and @flags is 0, this is identical to
virDomainBlockPull(). When @flags contains VIR_DOMAIN_BLOCK_REBASE_COPY,
this command is shorthand for virDomainBlockCopy() where the destination
XML encodes @base as a , @bandwidth is properly scaled
and passed as a typed parameter, the shallow and reuse external flags
are preserved, and remaining flags control whether the XML encodes a
destination format of raw instead of leaving the destination identical
to the source format or probed from the reused file.]]> sub-element, such as
"/path/to/image"), or (since 0.9.5) the device target shorthand
(the sub-element, such as "vda"). Valid names
can be found by calling virDomainGetXMLDesc() and inspecting
elements within //domain/devices/disk.
Note that this call may fail if the underlying virtualization hypervisor
does not support it; this call requires privileged access to the
hypervisor.]]> sub-element, such as "vda"), or (since 0.9.8)
an unambiguous source name of the block device (the sub-element, such as "/path/to/image"). Valid names
can be found by calling virDomainGetXMLDesc() and inspecting
elements within //domain/devices/disk. Some drivers might also
accept the empty string for the @disk parameter, and then yield
summary stats for the entire domain.
Domains may have more than one block device. To get stats for
each you should make multiple calls to this function.
Individual fields within the stats structure may be returned
as -1, which indicates that the hypervisor does not support
that particular statistic.]]> sub-element, such as "vda"), or (since 0.9.8)
an unambiguous source name of the block device (the sub-element, such as "/path/to/image"). Valid names
can be found by calling virDomainGetXMLDesc() and inspecting
elements within //domain/devices/disk. Some drivers might also
accept the empty string for the @disk parameter, and then yield
summary stats for the entire domain.
Domains may have more than one block device. To get stats for
each you should make multiple calls to this function.
On input, @nparams gives the size of the @params array; on output,
@nparams gives how many slots were filled with parameter
information, which might be less but will not exceed the input
value.
As a special case, calling with @params as NULL and @nparams as 0 on
input will cause @nparams on output to contain the number of parameters
supported by the hypervisor. (Note that block devices of different types
might support different parameters, so it might be necessary to compute
@nparams for each block device). The caller should then allocate @params
array, i.e. (sizeof(@virTypedParameter) * @nparams) bytes and call the API
again. See virDomainGetMemoryParameters() for more details.]]> sub-element, such as
"/path/to/image"), or (since 0.9.5) the device target shorthand
(the sub-element, such as "vda"). Valid names
can be found by calling virDomainGetXMLDesc() and inspecting
elements within //domain/devices/disk.
For QEMU domains, the allocation and physical virDomainBlockInfo
values returned will generally be the same, except when using a
non raw, block backing device, such as qcow2 for an active domain.
When the persistent domain is not active, QEMU will return the
default which is the same value for allocation and physical.
Active QEMU domains can return an allocation value which is more
representative of the currently used blocks by the device compared
to the physical size of the device. Applications can use/monitor
the allocation value with the understanding that if the domain
becomes inactive during an attempt to get the value, the default
values will be returned. Thus, the application should check
after the call for the domain being inactive if the values are
the same. Optionally, the application could be watching for a
shutdown event and then ignore any values received afterwards.
This can be an issue when a domain is being migrated and the
exact timing of the domain being made inactive and check of
the allocation value results the default being returned. For
a transient domain in the similar situation, this call will return
-1 and an error message indicating the "domain is not running".
The following is some pseudo code illustrating the call sequence:
...
virDomainPtr dom;
virDomainBlockInfo info;
char *device;
...
// Either get a list of all domains or a specific domain
// via a virDomainLookupBy*() call.
//
// It's also required to fill in the device pointer, but that's
// specific to the implementation. For the purposes of this example
// a qcow2 backed device name string would need to be provided.
...
// If the following call is made on a persistent domain with a
// qcow2 block backed block device, then it's possible the returned
// allocation equals the physical value. In that case, the domain
// that may have been active prior to calling has become inactive,
// such as is the case during a domain migration. Thus once we
// get data returned, check for active domain when the values are
// the same.
if (virDomainGetBlockInfo(dom, device, &info, 0) < 0)
goto failure;
if (info.allocation == info.physical) {
// If the domain is no longer active,
// then the defaults are being returned.
if (!virDomainIsActive())
goto ignore_return;
}
// Do something with the allocation and physical values
...]]> sub-element, such as
"/path/to/image"), or the device target shorthand (the sub-element, such as "xvda"). Valid names can be found
by calling virDomainGetXMLDesc() and inspecting elements
within //domain/devices/disk. This parameter cannot be NULL
unless @nparams is 0 on input.]]> sub-element, such as
"/path/to/image"), or (since 0.9.5) the device target shorthand
(the sub-element, such as "vda"). Valid names
can be found by calling virDomainGetXMLDesc() and inspecting
elements within //domain/devices/disk.]]>name and @ifaces->hwaddr are never NULL.
The caller *must* free @ifaces when no longer needed. Usual use case
looks like this:
virDomainInterfacePtr *ifaces = NULL;
int ifaces_count = 0;
size_t i, j;
virDomainPtr dom = ... obtain a domain here ...;
if ((ifaces_count = virDomainInterfaceAddresses(dom, &ifaces,
VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_LEASE)) < 0)
goto cleanup;
... do something with returned values, for example:
for (i = 0; i < ifaces_count; i++) {
printf("name: %s", ifaces[i]->name);
if (ifaces[i]->hwaddr)
printf(" hwaddr: %s", ifaces[i]->hwaddr);
for (j = 0; j < ifaces[i]->naddrs; j++) {
virDomainIPAddressPtr ip_addr = ifaces[i]->addrs + j;
printf("[addr: %s prefix: %d type: %d]",
ip_addr->addr, ip_addr->prefix, ip_addr->type);
}
printf("\n");
}
cleanup:
if (ifaces && ifaces_count > 0)
for (i = 0; i < ifaces_count; i++)
virDomainInterfaceFree(ifaces[i]);
free(ifaces);]]> configured.
Due to implementation limitations in some drivers (the qemu driver,
for instance) it is not advised to migrate or save a guest that is
rebooting as a result of this API. Migrating such a guest can lead
to a plain shutdown on the destination.]]> when listed by virDomainSnapshotGetXMLDesc(),
such as those created prior to libvirt 0.9.5). 2) Any attempt to
revert a running domain to an active state that requires starting a
new hypervisor instance rather than reusing the existing hypervisor
(since this would terminate all connections to the domain, such as
such as VNC or Spice graphics) - this condition arises from active
snapshots that are provably ABI incompatible, as well as from
inactive snapshots with a @flags request to start the domain after
the revert.]]> sub-element, such as
"/path/to/image"), or the device target shorthand (the sub-element, such as "xvda"). Valid names can be found
by calling virDomainGetXMLDesc() and inspecting elements
within //domain/devices/disk.]]> configured.]]>