common macros and enums for the libvirt and libvirt-admin library Provides common macros and enums needed by both libvirt and libvirt-admin libraries Erik Skultety <eskultet@redhat.com> Copyright (C) 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 domain snapshots Provides APIs for the management of domain snapshots Daniel 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 domains Provides APIs for the management of domains Daniel 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 events Provides APIs for the management of events Daniel 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 hosts Provides APIs for the management of hosts Daniel 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 interfaces Provides APIs for the management of interfaces Daniel 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 networks Provides APIs for the management of networks Daniel 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 nodedevs Provides APIs for the management of nodedevs Daniel 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 nwfilters Provides APIs for the management of nwfilters Daniel 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 secrets Provides APIs for the management of secrets Daniel 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 volumes Provides APIs for the management of storage pools and volumes 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/>. APIs for management of streams Provides APIs for the management of streams Daniel 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 library Provides 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. "perf.cache_misses" - the count of cache misses as unsigned long long. It is produced by cache_misses perf event. "perf.cache_references" - the count of cache hits as unsigned long long. It is produced by cache_references perf event. "perf.instructions" - The count of instructions as unsigned long long. It is produced by instructions perf event. "perf.cpu_cycles" - The count of cpu cycles (total/elapsed) as an unsigned long long. It is produced by cpu_cycles 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. As a corner case underlying hypervisor may report cur == 0 and end == 0 when the block job hasn't been started yet. In this case libvirt reports cur = 0 and end = 1. However, hypervisor may return cur == 0 and end == 0 if the block job has finished and was no-op. In this case libvirt reports cur = 1 and end = 1. Since 2.3.0.]]> 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.]]>