2 * libvirt-domain.c: entry points for virDomainPtr APIs
4 * Copyright (C) 2006-2015 Red Hat, Inc.
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library. If not, see
18 * <http://www.gnu.org/licenses/>.
24 #include "datatypes.h"
28 #include "virtypedparam.h"
31 VIR_LOG_INIT("libvirt.domain");
33 #define VIR_FROM_THIS VIR_FROM_DOMAIN
37 * virConnectListDomains:
38 * @conn: pointer to the hypervisor connection
39 * @ids: array to collect the list of IDs of active domains
40 * @maxids: size of @ids
42 * Collect the list of active domains, and store their IDs in array @ids
44 * The use of this function is discouraged. Instead, use
45 * virConnectListAllDomains().
47 * Returns the number of domains found or -1 in case of error. Note that
48 * this command is inherently racy; a domain can be started between a
49 * call to virConnectNumOfDomains() and this call; you are only guaranteed
50 * that all currently active domains were listed if the return is less
56 virConnectListDomains(virConnectPtr conn
, int *ids
, int maxids
)
58 VIR_DEBUG("conn=%p, ids=%p, maxids=%d", conn
, ids
, maxids
);
62 virCheckConnectReturn(conn
, -1);
63 virCheckNonNullArrayArgGoto(ids
, maxids
, error
);
64 virCheckNonNegativeArgGoto(maxids
, error
);
66 if (conn
->driver
->connectListDomains
) {
67 int ret
= conn
->driver
->connectListDomains(conn
, ids
, maxids
);
73 virReportUnsupportedError();
75 virDispatchError(conn
);
81 * virConnectNumOfDomains:
82 * @conn: pointer to the hypervisor connection
84 * Provides the number of active domains.
86 * Returns the number of domain found or -1 in case of error
91 virConnectNumOfDomains(virConnectPtr conn
)
93 VIR_DEBUG("conn=%p", conn
);
97 virCheckConnectReturn(conn
, -1);
99 if (conn
->driver
->connectNumOfDomains
) {
100 int ret
= conn
->driver
->connectNumOfDomains(conn
);
106 virReportUnsupportedError();
108 virDispatchError(conn
);
114 * virDomainGetConnect:
115 * @dom: pointer to a domain
117 * Provides the connection pointer associated with a domain. The
118 * reference counter on the connection is not increased by this
121 * Returns the virConnectPtr or NULL in case of failure.
126 virDomainGetConnect(virDomainPtr dom
)
128 VIR_DOMAIN_DEBUG(dom
);
132 virCheckDomainReturn(dom
, NULL
);
139 * virDomainCreateXML:
140 * @conn: pointer to the hypervisor connection
141 * @xmlDesc: string containing an XML description of the domain
142 * @flags: bitwise-OR of supported virDomainCreateFlags
144 * Launch a new guest domain, based on an XML description similar
145 * to the one returned by virDomainGetXMLDesc()
146 * This function may require privileged access to the hypervisor.
147 * The domain is not persistent, so its definition will disappear when it
148 * is destroyed, or if the host is restarted (see virDomainDefineXML() to
149 * define persistent domains).
151 * If the VIR_DOMAIN_START_PAUSED flag is set, the guest domain
152 * will be started, but its CPUs will remain paused. The CPUs
153 * can later be manually started using virDomainResume.
155 * If the VIR_DOMAIN_START_AUTODESTROY flag is set, the guest
156 * domain will be automatically destroyed when the virConnectPtr
157 * object is finally released. This will also happen if the
158 * client application crashes / loses its connection to the
159 * libvirtd daemon. Any domains marked for auto destroy will
160 * block attempts at migration. Hypervisors may also block save-to-file,
163 * If @flags includes VIR_DOMAIN_START_RESET_NVRAM, then libvirt will
164 * discard any existing NVRAM file and re-initialize NVRAM from the
167 * virDomainFree should be used to free the resources after the
168 * domain object is no longer needed.
170 * Returns a new domain object or NULL in case of failure
175 virDomainCreateXML(virConnectPtr conn
, const char *xmlDesc
,
178 VIR_DEBUG("conn=%p, xmlDesc=%s, flags=0x%x", conn
, NULLSTR(xmlDesc
), flags
);
182 virCheckConnectReturn(conn
, NULL
);
183 virCheckNonNullArgGoto(xmlDesc
, error
);
184 virCheckReadOnlyGoto(conn
->flags
, error
);
186 if (conn
->driver
->domainCreateXML
) {
188 ret
= conn
->driver
->domainCreateXML(conn
, xmlDesc
, flags
);
194 virReportUnsupportedError();
196 virDispatchError(conn
);
202 * virDomainCreateXMLWithFiles:
203 * @conn: pointer to the hypervisor connection
204 * @xmlDesc: string containing an XML description of the domain
205 * @nfiles: number of file descriptors passed
206 * @files: list of file descriptors passed
207 * @flags: bitwise-OR of supported virDomainCreateFlags
209 * Launch a new guest domain, based on an XML description similar
210 * to the one returned by virDomainGetXMLDesc()
211 * This function may require privileged access to the hypervisor.
212 * The domain is not persistent, so its definition will disappear when it
213 * is destroyed, or if the host is restarted (see virDomainDefineXML() to
214 * define persistent domains).
216 * @files provides an array of file descriptors which will be
217 * made available to the 'init' process of the guest. The file
218 * handles exposed to the guest will be renumbered to start
219 * from 3 (ie immediately following stderr). This is only
220 * supported for guests which use container based virtualization
223 * If the VIR_DOMAIN_START_PAUSED flag is set, the guest domain
224 * will be started, but its CPUs will remain paused. The CPUs
225 * can later be manually started using virDomainResume.
227 * If the VIR_DOMAIN_START_AUTODESTROY flag is set, the guest
228 * domain will be automatically destroyed when the virConnectPtr
229 * object is finally released. This will also happen if the
230 * client application crashes / loses its connection to the
231 * libvirtd daemon. Any domains marked for auto destroy will
232 * block attempts at migration. Hypervisors may also block
233 * save-to-file, or snapshots.
235 * virDomainFree should be used to free the resources after the
236 * domain object is no longer needed.
238 * Returns a new domain object or NULL in case of failure
243 virDomainCreateXMLWithFiles(virConnectPtr conn
, const char *xmlDesc
,
248 VIR_DEBUG("conn=%p, xmlDesc=%s, nfiles=%u, files=%p, flags=0x%x",
249 conn
, NULLSTR(xmlDesc
), nfiles
, files
, flags
);
253 virCheckConnectReturn(conn
, NULL
);
254 virCheckNonNullArgGoto(xmlDesc
, error
);
255 virCheckReadOnlyGoto(conn
->flags
, error
);
260 if ((rc
= VIR_DRV_SUPPORTS_FEATURE(conn
->driver
, conn
,
261 VIR_DRV_FEATURE_FD_PASSING
)) <= 0) {
263 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
264 _("fd passing is not supported by this connection"));
269 if (conn
->driver
->domainCreateXMLWithFiles
) {
271 ret
= conn
->driver
->domainCreateXMLWithFiles(conn
, xmlDesc
,
279 virReportUnsupportedError();
281 virDispatchError(conn
);
287 * virDomainCreateLinux:
288 * @conn: pointer to the hypervisor connection
289 * @xmlDesc: string containing an XML description of the domain
290 * @flags: extra flags; not used yet, so callers should always pass 0
292 * Deprecated after 0.4.6.
293 * Renamed to virDomainCreateXML() providing identical functionality.
294 * This existing name will be left indefinitely for API compatibility.
296 * Returns a new domain object or NULL in case of failure
301 virDomainCreateLinux(virConnectPtr conn
, const char *xmlDesc
,
304 return virDomainCreateXML(conn
, xmlDesc
, flags
);
309 * virDomainLookupByID:
310 * @conn: pointer to the hypervisor connection
311 * @id: the domain ID number
313 * Try to find a domain based on the hypervisor ID number
314 * Note that this won't work for inactive domains which have an ID of -1,
315 * in that case a lookup based on the Name or UUID need to be done instead.
317 * virDomainFree should be used to free the resources after the
318 * domain object is no longer needed.
320 * Returns a new domain object or NULL in case of failure. If the
321 * domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
326 virDomainLookupByID(virConnectPtr conn
, int id
)
328 VIR_DEBUG("conn=%p, id=%d", conn
, id
);
332 virCheckConnectReturn(conn
, NULL
);
333 virCheckNonNegativeArgGoto(id
, error
);
335 if (conn
->driver
->domainLookupByID
) {
337 ret
= conn
->driver
->domainLookupByID(conn
, id
);
343 virReportUnsupportedError();
346 virDispatchError(conn
);
352 * virDomainLookupByUUID:
353 * @conn: pointer to the hypervisor connection
354 * @uuid: the raw UUID for the domain
356 * Try to lookup a domain on the given hypervisor based on its UUID.
358 * virDomainFree should be used to free the resources after the
359 * domain object is no longer needed.
361 * Returns a new domain object or NULL in case of failure. If the
362 * domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
367 virDomainLookupByUUID(virConnectPtr conn
, const unsigned char *uuid
)
369 VIR_UUID_DEBUG(conn
, uuid
);
373 virCheckConnectReturn(conn
, NULL
);
374 virCheckNonNullArgGoto(uuid
, error
);
376 if (conn
->driver
->domainLookupByUUID
) {
378 ret
= conn
->driver
->domainLookupByUUID(conn
, uuid
);
384 virReportUnsupportedError();
387 virDispatchError(conn
);
393 * virDomainLookupByUUIDString:
394 * @conn: pointer to the hypervisor connection
395 * @uuidstr: the string UUID for the domain
397 * Try to lookup a domain on the given hypervisor based on its UUID.
399 * virDomainFree should be used to free the resources after the
400 * domain object is no longer needed.
402 * Returns a new domain object or NULL in case of failure. If the
403 * domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
408 virDomainLookupByUUIDString(virConnectPtr conn
, const char *uuidstr
)
410 unsigned char uuid
[VIR_UUID_BUFLEN
];
411 VIR_DEBUG("conn=%p, uuidstr=%s", conn
, NULLSTR(uuidstr
));
415 virCheckConnectReturn(conn
, NULL
);
416 virCheckNonNullArgGoto(uuidstr
, error
);
418 if (virUUIDParse(uuidstr
, uuid
) < 0) {
419 virReportInvalidArg(uuidstr
, "%s", _("Invalid UUID"));
423 return virDomainLookupByUUID(conn
, &uuid
[0]);
426 virDispatchError(conn
);
432 * virDomainLookupByName:
433 * @conn: pointer to the hypervisor connection
434 * @name: name for the domain
436 * Try to lookup a domain on the given hypervisor based on its name.
438 * virDomainFree should be used to free the resources after the
439 * domain object is no longer needed.
441 * Returns a new domain object or NULL in case of failure. If the
442 * domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
447 virDomainLookupByName(virConnectPtr conn
, const char *name
)
449 VIR_DEBUG("conn=%p, name=%s", conn
, NULLSTR(name
));
453 virCheckConnectReturn(conn
, NULL
);
454 virCheckNonNullArgGoto(name
, error
);
456 if (conn
->driver
->domainLookupByName
) {
458 dom
= conn
->driver
->domainLookupByName(conn
, name
);
464 virReportUnsupportedError();
467 virDispatchError(conn
);
474 * @domain: a domain object
476 * Destroy the domain object. The running instance is shutdown if not down
477 * already and all resources used by it are given back to the hypervisor. This
478 * does not free the associated virDomainPtr object.
479 * This function may require privileged access.
481 * virDomainDestroy first requests that a guest terminate
482 * (e.g. SIGTERM), then waits for it to comply. After a reasonable
483 * timeout, if the guest still exists, virDomainDestroy will
484 * forcefully terminate the guest (e.g. SIGKILL) if necessary (which
485 * may produce undesirable results, for example unflushed disk cache
486 * in the guest). To avoid this possibility, it's recommended to
487 * instead call virDomainDestroyFlags, sending the
488 * VIR_DOMAIN_DESTROY_GRACEFUL flag.
490 * If the domain is transient and has any snapshot metadata (see
491 * virDomainSnapshotNum()), then that metadata will automatically
492 * be deleted when the domain quits.
494 * Returns 0 in case of success and -1 in case of failure.
499 virDomainDestroy(virDomainPtr domain
)
503 VIR_DOMAIN_DEBUG(domain
);
507 virCheckDomainReturn(domain
, -1);
510 virCheckReadOnlyGoto(conn
->flags
, error
);
512 if (conn
->driver
->domainDestroy
) {
514 ret
= conn
->driver
->domainDestroy(domain
);
520 virReportUnsupportedError();
523 virDispatchError(conn
);
529 * virDomainDestroyFlags:
530 * @domain: a domain object
531 * @flags: bitwise-OR of virDomainDestroyFlagsValues
533 * Destroy the domain object. The running instance is shutdown if not down
534 * already and all resources used by it are given back to the hypervisor.
535 * This does not free the associated virDomainPtr object.
536 * This function may require privileged access.
538 * Calling this function with no @flags set (equal to zero) is
539 * equivalent to calling virDomainDestroy, and after a reasonable
540 * timeout will forcefully terminate the guest (e.g. SIGKILL) if
541 * necessary (which may produce undesirable results, for example
542 * unflushed disk cache in the guest). Including
543 * VIR_DOMAIN_DESTROY_GRACEFUL in the flags will prevent the forceful
544 * termination of the guest, and virDomainDestroyFlags will instead
545 * return an error if the guest doesn't terminate by the end of the
546 * timeout; at that time, the management application can decide if
547 * calling again without VIR_DOMAIN_DESTROY_GRACEFUL is appropriate.
549 * If VIR_DOMAIN_DESTROY_REMOVE_LOGS flag is set then domain specific
550 * logs will be deleted as well if there are any. Note that not all
551 * deployments are be supported. For example in case of QEMU driver
552 * this flags is noop if virtlogd is not used for handling QEMU
555 * Another alternative which may produce cleaner results for the
556 * guest's disks is to use virDomainShutdown() instead, but that
557 * depends on guest support (some hypervisor/guest combinations may
558 * ignore the shutdown request).
561 * Returns 0 in case of success and -1 in case of failure.
566 virDomainDestroyFlags(virDomainPtr domain
,
571 VIR_DOMAIN_DEBUG(domain
, "flags=0x%x", flags
);
575 virCheckDomainReturn(domain
, -1);
578 virCheckReadOnlyGoto(conn
->flags
, error
);
580 if (conn
->driver
->domainDestroyFlags
) {
582 ret
= conn
->driver
->domainDestroyFlags(domain
, flags
);
588 virReportUnsupportedError();
591 virDispatchError(conn
);
598 * @domain: a domain object
600 * Free the domain object. The running instance is kept alive.
601 * The data structure is freed and should not be used thereafter.
603 * Returns 0 in case of success and -1 in case of failure.
608 virDomainFree(virDomainPtr domain
)
610 VIR_DOMAIN_DEBUG(domain
);
614 virCheckDomainReturn(domain
, -1);
616 virObjectUnref(domain
);
623 * @domain: the domain to hold a reference on
625 * Increment the reference count on the domain. For each
626 * additional call to this method, there shall be a corresponding
627 * call to virDomainFree to release the reference count, once
628 * the caller no longer needs the reference to this object.
630 * This method is typically useful for applications where multiple
631 * threads are using a connection, and it is required that the
632 * connection remain open until all threads have finished using
633 * it. ie, each new thread using a domain would increment
634 * the reference count.
636 * Returns 0 in case of success and -1 in case of failure.
641 virDomainRef(virDomainPtr domain
)
643 VIR_DOMAIN_DEBUG(domain
);
647 virCheckDomainReturn(domain
, -1);
649 virObjectRef(domain
);
656 * @domain: a domain object
658 * Suspends an active domain, the process is frozen without further access
659 * to CPU resources and I/O but the memory used by the domain at the
660 * hypervisor level will stay allocated. Use virDomainResume() to reactivate
662 * This function may require privileged access.
663 * Moreover, suspend may not be supported if domain is in some
664 * special state like VIR_DOMAIN_PMSUSPENDED.
666 * Returns 0 in case of success and -1 in case of failure.
671 virDomainSuspend(virDomainPtr domain
)
675 VIR_DOMAIN_DEBUG(domain
);
679 virCheckDomainReturn(domain
, -1);
682 virCheckReadOnlyGoto(conn
->flags
, error
);
684 if (conn
->driver
->domainSuspend
) {
686 ret
= conn
->driver
->domainSuspend(domain
);
692 virReportUnsupportedError();
695 virDispatchError(domain
->conn
);
702 * @domain: a domain object
704 * Resume a suspended domain, the process is restarted from the state where
705 * it was frozen by calling virDomainSuspend().
706 * This function may require privileged access
707 * Moreover, resume may not be supported if domain is in some
708 * special state like VIR_DOMAIN_PMSUSPENDED.
710 * Returns 0 in case of success and -1 in case of failure.
715 virDomainResume(virDomainPtr domain
)
719 VIR_DOMAIN_DEBUG(domain
);
723 virCheckDomainReturn(domain
, -1);
726 virCheckReadOnlyGoto(conn
->flags
, error
);
728 if (conn
->driver
->domainResume
) {
730 ret
= conn
->driver
->domainResume(domain
);
736 virReportUnsupportedError();
739 virDispatchError(domain
->conn
);
745 * virDomainPMSuspendForDuration:
746 * @dom: a domain object
747 * @target: a value from virNodeSuspendTarget
748 * @duration: duration in seconds to suspend, or 0 for indefinite
749 * @flags: extra flags; not used yet, so callers should always pass 0
751 * Attempt to have the guest enter the given @target power management
752 * suspension level. If @duration is non-zero, also schedule the guest to
753 * resume normal operation after that many seconds, if nothing else has
754 * resumed it earlier. Some hypervisors require that @duration be 0, for
755 * an indefinite suspension.
757 * Dependent on hypervisor used, this may require a
758 * guest agent to be available, e.g. QEMU.
760 * Beware that at least for QEMU, the domain's process will be terminated
761 * when VIR_NODE_SUSPEND_TARGET_DISK is used and a new process will be
762 * launched when libvirt is asked to wake up the domain. As a result of
763 * this, any runtime changes, such as device hotplug or memory settings,
764 * are lost unless such changes were made with VIR_DOMAIN_AFFECT_CONFIG
767 * Returns: 0 on success,
773 virDomainPMSuspendForDuration(virDomainPtr dom
,
775 unsigned long long duration
,
780 VIR_DOMAIN_DEBUG(dom
, "target=%u duration=%llu flags=0x%x",
781 target
, duration
, flags
);
785 virCheckDomainReturn(dom
, -1);
788 virCheckReadOnlyGoto(conn
->flags
, error
);
790 if (conn
->driver
->domainPMSuspendForDuration
) {
792 ret
= conn
->driver
->domainPMSuspendForDuration(dom
, target
,
799 virReportUnsupportedError();
802 virDispatchError(conn
);
809 * @dom: a domain object
810 * @flags: extra flags; not used yet, so callers should always pass 0
812 * Inject a wakeup into the guest that previously used
813 * virDomainPMSuspendForDuration, rather than waiting for the
814 * previously requested duration (if any) to elapse.
816 * Returns: 0 on success,
822 virDomainPMWakeup(virDomainPtr dom
,
827 VIR_DOMAIN_DEBUG(dom
, "flags=0x%x", flags
);
831 virCheckDomainReturn(dom
, -1);
834 virCheckReadOnlyGoto(conn
->flags
, error
);
836 if (conn
->driver
->domainPMWakeup
) {
838 ret
= conn
->driver
->domainPMWakeup(dom
, flags
);
844 virReportUnsupportedError();
847 virDispatchError(conn
);
854 * @domain: a domain object
855 * @to: path for the output save file / directory
857 * This method will suspend a domain and save its memory contents to a file or
858 * direcotry (based on the vmm) on disk. After the call, if successful,the domain
859 * is not listed as running anymore (this ends the life of a transient domain).
860 * Use virDomainRestore() to restore a domain after saving.
862 * See virDomainSaveFlags() and virDomainSaveParams() for more control.
863 * Also, a save file can be inspected or modified slightly with
864 * virDomainSaveImageGetXMLDesc() and virDomainSaveImageDefineXML().
866 * Returns 0 in case of success and -1 in case of failure.
871 virDomainSave(virDomainPtr domain
, const char *to
)
875 VIR_DOMAIN_DEBUG(domain
, "to=%s", to
);
879 virCheckDomainReturn(domain
, -1);
882 virCheckReadOnlyGoto(conn
->flags
, error
);
883 virCheckNonNullArgGoto(to
, error
);
885 if (conn
->driver
->domainSave
) {
889 /* We must absolutize the file path as the save is done out of process */
890 if (!(absolute_to
= g_canonicalize_filename(to
, NULL
))) {
891 virReportError(VIR_ERR_INTERNAL_ERROR
, "%s",
892 _("could not build absolute output file path"));
896 ret
= conn
->driver
->domainSave(domain
, absolute_to
);
898 VIR_FREE(absolute_to
);
905 virReportUnsupportedError();
908 virDispatchError(domain
->conn
);
914 * virDomainSaveFlags:
915 * @domain: a domain object
916 * @to: path for the output file
917 * @dxml: (optional) XML config for adjusting guest xml used on restore
918 * @flags: bitwise-OR of virDomainSaveRestoreFlags
920 * This method will suspend a domain and save its memory contents to
921 * a file on disk. After the call, if successful, the domain is not
922 * listed as running anymore (this ends the life of a transient domain).
923 * Use virDomainRestore() to restore a domain after saving.
925 * If the hypervisor supports it, @dxml can be used to alter
926 * host-specific portions of the domain XML that will be used when
927 * restoring an image. For example, it is possible to alter the
928 * backing filename that is associated with a disk device, in order to
929 * prepare for file renaming done as part of backing up the disk
930 * device while the domain is stopped.
932 * If @flags includes VIR_DOMAIN_SAVE_BYPASS_CACHE, then libvirt will
933 * attempt to bypass the file system cache while creating the file, or
934 * fail if it cannot do so for the given system; this can allow less
935 * pressure on file system cache, but also risks slowing saves to NFS.
937 * Normally, the saved state file will remember whether the domain was
938 * running or paused, and restore defaults to the same state.
939 * Specifying VIR_DOMAIN_SAVE_RUNNING or VIR_DOMAIN_SAVE_PAUSED in
940 * @flags will override what state gets saved into the file. These
941 * two flags are mutually exclusive.
943 * A save file can be inspected or modified slightly with
944 * virDomainSaveImageGetXMLDesc() and virDomainSaveImageDefineXML().
946 * Some hypervisors may prevent this operation if there is a current
947 * block job running; in that case, use virDomainBlockJobAbort()
948 * to stop the block job first.
950 * Returns 0 in case of success and -1 in case of failure.
955 virDomainSaveFlags(virDomainPtr domain
, const char *to
,
956 const char *dxml
, unsigned int flags
)
960 VIR_DOMAIN_DEBUG(domain
, "to=%s, dxml=%s, flags=0x%x",
961 to
, NULLSTR(dxml
), flags
);
965 virCheckDomainReturn(domain
, -1);
968 virCheckReadOnlyGoto(conn
->flags
, error
);
969 virCheckNonNullArgGoto(to
, error
);
971 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_SAVE_RUNNING
,
972 VIR_DOMAIN_SAVE_PAUSED
,
975 if (conn
->driver
->domainSaveFlags
) {
979 /* We must absolutize the file path as the save is done out of process */
980 if (!(absolute_to
= g_canonicalize_filename(to
, NULL
))) {
981 virReportError(VIR_ERR_INTERNAL_ERROR
, "%s",
982 _("could not build absolute output file path"));
986 ret
= conn
->driver
->domainSaveFlags(domain
, absolute_to
, dxml
, flags
);
988 VIR_FREE(absolute_to
);
995 virReportUnsupportedError();
998 virDispatchError(domain
->conn
);
1003 * virDomainSaveParams:
1004 * @domain: a domain object
1005 * @params: save parameters
1006 * @nparams: number of save parameters
1007 * @flags: bitwise-OR of virDomainSaveRestoreFlags
1009 * This method extends virDomainSaveFlags by adding parameters.
1010 * If VIR_DOMAIN_SAVE_PARAM_FILE is not provided then a managed save is
1011 * performed (see virDomainManagedSave).
1013 * Returns 0 in case of success and -1 in case of failure.
1018 virDomainSaveParams(virDomainPtr domain
,
1019 virTypedParameterPtr params
, int nparams
,
1024 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%d, flags=0x%x",
1025 params
, nparams
, flags
);
1026 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
1028 virResetLastError();
1030 virCheckDomainReturn(domain
, -1);
1031 conn
= domain
->conn
;
1033 virCheckReadOnlyGoto(conn
->flags
, error
);
1035 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_SAVE_RUNNING
,
1036 VIR_DOMAIN_SAVE_PAUSED
,
1039 if (conn
->driver
->domainSaveParams
) {
1040 if (conn
->driver
->domainSaveParams(domain
, params
, nparams
, flags
) < 0)
1045 virReportUnsupportedError();
1048 virDispatchError(domain
->conn
);
1055 * @conn: pointer to the hypervisor connection
1056 * @from: path to the input save file / directory
1058 * This method will restore a domain saved to disk by virDomainSave().
1060 * See virDomainRestoreFlags() for more control.
1062 * Returns 0 in case of success and -1 in case of failure.
1067 virDomainRestore(virConnectPtr conn
, const char *from
)
1069 VIR_DEBUG("conn=%p, from=%s", conn
, NULLSTR(from
));
1071 virResetLastError();
1073 virCheckConnectReturn(conn
, -1);
1074 virCheckReadOnlyGoto(conn
->flags
, error
);
1075 virCheckNonNullArgGoto(from
, error
);
1077 if (conn
->driver
->domainRestore
) {
1079 char *absolute_from
;
1081 /* We must absolutize the file path as the restore is done out of process */
1082 if (!(absolute_from
= g_canonicalize_filename(from
, NULL
))) {
1083 virReportError(VIR_ERR_INTERNAL_ERROR
, "%s",
1084 _("could not build absolute input file path"));
1088 ret
= conn
->driver
->domainRestore(conn
, absolute_from
);
1090 VIR_FREE(absolute_from
);
1097 virReportUnsupportedError();
1100 virDispatchError(conn
);
1106 * virDomainRestoreFlags:
1107 * @conn: pointer to the hypervisor connection
1108 * @from: path to the input file
1109 * @dxml: (optional) XML config for adjusting guest xml used on restore
1110 * @flags: bitwise-OR of virDomainSaveRestoreFlags
1112 * This method will restore a domain saved to disk by virDomainSave().
1114 * If the hypervisor supports it, @dxml can be used to alter
1115 * host-specific portions of the domain XML that will be used when
1116 * restoring an image. For example, it is possible to alter the
1117 * backing filename that is associated with a disk device, in order to
1118 * prepare for file renaming done as part of backing up the disk
1119 * device while the domain is stopped.
1121 * If @flags includes VIR_DOMAIN_SAVE_BYPASS_CACHE, then libvirt will
1122 * attempt to bypass the file system cache while restoring the file, or
1123 * fail if it cannot do so for the given system; this can allow less
1124 * pressure on file system cache, but also risks slowing restores from NFS.
1126 * Normally, the saved state file will remember whether the domain was
1127 * running or paused, and restore defaults to the same state.
1128 * Specifying VIR_DOMAIN_SAVE_RUNNING or VIR_DOMAIN_SAVE_PAUSED in
1129 * @flags will override the default read from the file. These two
1130 * flags are mutually exclusive.
1132 * If @flags includes VIR_DOMAIN_SAVE_RESET_NVRAM, then libvirt will
1133 * discard any existing NVRAM file and re-initialize NVRAM from the
1134 * pristine template.
1136 * Returns 0 in case of success and -1 in case of failure.
1141 virDomainRestoreFlags(virConnectPtr conn
, const char *from
, const char *dxml
,
1144 VIR_DEBUG("conn=%p, from=%s, dxml=%s, flags=0x%x",
1145 conn
, NULLSTR(from
), NULLSTR(dxml
), flags
);
1147 virResetLastError();
1149 virCheckConnectReturn(conn
, -1);
1150 virCheckReadOnlyGoto(conn
->flags
, error
);
1151 virCheckNonNullArgGoto(from
, error
);
1153 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_SAVE_RUNNING
,
1154 VIR_DOMAIN_SAVE_PAUSED
,
1157 if (conn
->driver
->domainRestoreFlags
) {
1159 char *absolute_from
;
1161 /* We must absolutize the file path as the restore is done out of process */
1162 if (!(absolute_from
= g_canonicalize_filename(from
, NULL
))) {
1163 virReportError(VIR_ERR_INTERNAL_ERROR
, "%s",
1164 _("could not build absolute input file path"));
1168 ret
= conn
->driver
->domainRestoreFlags(conn
, absolute_from
, dxml
,
1171 VIR_FREE(absolute_from
);
1178 virReportUnsupportedError();
1181 virDispatchError(conn
);
1187 * virDomainRestoreParams:
1188 * @conn: pointer to the hypervisor connection
1189 * @params: restore parameters
1190 * @nparams: number of restore parameters
1191 * @flags: bitwise-OR of virDomainSaveRestoreFlags
1193 * This method extends virDomainRestoreFlags by adding parameters. For
1194 * now, VIR_DOMAIN_SAVE_PARAM_FILE is required but this requirement may
1195 * be lifted in the future.
1197 * Returns 0 in case of success and -1 in case of failure.
1202 virDomainRestoreParams(virConnectPtr conn
,
1203 virTypedParameterPtr params
, int nparams
,
1206 VIR_DEBUG("conn=%p, params=%p, nparams=%d, flags=0x%x",
1207 conn
, params
, nparams
, flags
);
1208 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
1210 virResetLastError();
1212 virCheckConnectReturn(conn
, -1);
1213 virCheckReadOnlyGoto(conn
->flags
, error
);
1215 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_SAVE_RUNNING
,
1216 VIR_DOMAIN_SAVE_PAUSED
,
1219 if (conn
->driver
->domainRestoreParams
) {
1220 if (conn
->driver
->domainRestoreParams(conn
, params
, nparams
, flags
) < 0)
1225 virReportUnsupportedError();
1228 virDispatchError(conn
);
1234 * virDomainSaveImageGetXMLDesc:
1235 * @conn: pointer to the hypervisor connection
1236 * @file: path to saved state file
1237 * @flags: bitwise-OR of supported virDomainSaveImageXMLFlags
1239 * This method will extract the XML describing the domain at the time
1240 * a saved state file was created. @file must be a file created
1241 * previously by virDomainSave() or virDomainSaveFlags().
1243 * No security-sensitive data will be included unless @flags contains
1244 * VIR_DOMAIN_SAVE_IMAGE_XML_SECURE.
1246 * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of
1247 * error. The caller must free() the returned value.
1252 virDomainSaveImageGetXMLDesc(virConnectPtr conn
, const char *file
,
1255 VIR_DEBUG("conn=%p, file=%s, flags=0x%x",
1256 conn
, NULLSTR(file
), flags
);
1258 virResetLastError();
1260 virCheckConnectReturn(conn
, NULL
);
1261 virCheckNonNullArgGoto(file
, error
);
1262 virCheckReadOnlyGoto(conn
->flags
, error
);
1264 if (conn
->driver
->domainSaveImageGetXMLDesc
) {
1266 char *absolute_file
;
1268 /* We must absolutize the file path as the read is done out of process */
1269 if (!(absolute_file
= g_canonicalize_filename(file
, NULL
))) {
1270 virReportError(VIR_ERR_INTERNAL_ERROR
, "%s",
1271 _("could not build absolute input file path"));
1275 ret
= conn
->driver
->domainSaveImageGetXMLDesc(conn
, absolute_file
,
1278 VIR_FREE(absolute_file
);
1285 virReportUnsupportedError();
1288 virDispatchError(conn
);
1294 * virDomainSaveImageDefineXML:
1295 * @conn: pointer to the hypervisor connection
1296 * @file: path to saved state file
1297 * @dxml: XML config for adjusting guest xml used on restore
1298 * @flags: bitwise-OR of virDomainSaveRestoreFlags
1300 * This updates the definition of a domain stored in a saved state
1301 * file. @file must be a file created previously by virDomainSave()
1302 * or virDomainSaveFlags().
1304 * @dxml can be used to alter host-specific portions of the domain XML
1305 * that will be used when restoring an image. For example, it is
1306 * possible to alter the backing filename that is associated with a
1307 * disk device, to match renaming done as part of backing up the disk
1308 * device while the domain is stopped.
1310 * Normally, the saved state file will remember whether the domain was
1311 * running or paused, and restore defaults to the same state.
1312 * Specifying VIR_DOMAIN_SAVE_RUNNING or VIR_DOMAIN_SAVE_PAUSED in
1313 * @flags will override the default saved into the file; omitting both
1314 * leaves the file's default unchanged. These two flags are mutually
1317 * Returns 0 in case of success and -1 in case of failure.
1322 virDomainSaveImageDefineXML(virConnectPtr conn
, const char *file
,
1323 const char *dxml
, unsigned int flags
)
1325 VIR_DEBUG("conn=%p, file=%s, dxml=%s, flags=0x%x",
1326 conn
, NULLSTR(file
), NULLSTR(dxml
), flags
);
1328 virResetLastError();
1330 virCheckConnectReturn(conn
, -1);
1331 virCheckReadOnlyGoto(conn
->flags
, error
);
1332 virCheckNonNullArgGoto(file
, error
);
1333 virCheckNonNullArgGoto(dxml
, error
);
1335 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_SAVE_RUNNING
,
1336 VIR_DOMAIN_SAVE_PAUSED
,
1339 if (conn
->driver
->domainSaveImageDefineXML
) {
1341 char *absolute_file
;
1343 /* We must absolutize the file path as the read is done out of process */
1344 if (!(absolute_file
= g_canonicalize_filename(file
, NULL
))) {
1345 virReportError(VIR_ERR_INTERNAL_ERROR
, "%s",
1346 _("could not build absolute input file path"));
1350 ret
= conn
->driver
->domainSaveImageDefineXML(conn
, absolute_file
,
1353 VIR_FREE(absolute_file
);
1360 virReportUnsupportedError();
1363 virDispatchError(conn
);
1369 * virDomainCoreDump:
1370 * @domain: a domain object
1371 * @to: path for the core file
1372 * @flags: bitwise-OR of virDomainCoreDumpFlags
1374 * This method will dump the core of a domain on a given file for analysis.
1375 * Note that for remote Xen Daemon the file path will be interpreted in
1376 * the remote host. Hypervisors may require the user to manually ensure
1377 * proper permissions on the file named by @to.
1379 * If @flags includes VIR_DUMP_CRASH, then leave the guest shut off with
1380 * a crashed state after the dump completes. If @flags includes
1381 * VIR_DUMP_LIVE, then make the core dump while continuing to allow
1382 * the guest to run; otherwise, the guest is suspended during the dump.
1383 * VIR_DUMP_RESET flag forces reset of the guest after dump.
1384 * The above three flags are mutually exclusive.
1386 * Additionally, if @flags includes VIR_DUMP_BYPASS_CACHE, then libvirt
1387 * will attempt to bypass the file system cache while creating the file,
1388 * or fail if it cannot do so for the given system; this can allow less
1389 * pressure on file system cache, but also risks slowing saves to NFS.
1391 * For more control over the output format, see virDomainCoreDumpWithFormat().
1393 * Returns 0 in case of success and -1 in case of failure.
1398 virDomainCoreDump(virDomainPtr domain
, const char *to
, unsigned int flags
)
1402 VIR_DOMAIN_DEBUG(domain
, "to=%s, flags=0x%x", to
, flags
);
1404 virResetLastError();
1406 virCheckDomainReturn(domain
, -1);
1407 conn
= domain
->conn
;
1409 virCheckReadOnlyGoto(conn
->flags
, error
);
1410 virCheckNonNullArgGoto(to
, error
);
1412 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DUMP_CRASH
, VIR_DUMP_LIVE
, error
);
1413 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DUMP_CRASH
, VIR_DUMP_RESET
, error
);
1414 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DUMP_LIVE
, VIR_DUMP_RESET
, error
);
1416 if (conn
->driver
->domainCoreDump
) {
1420 /* We must absolutize the file path as the save is done out of process */
1421 if (!(absolute_to
= g_canonicalize_filename(to
, NULL
))) {
1422 virReportError(VIR_ERR_INTERNAL_ERROR
, "%s",
1423 _("could not build absolute core file path"));
1427 ret
= conn
->driver
->domainCoreDump(domain
, absolute_to
, flags
);
1429 VIR_FREE(absolute_to
);
1436 virReportUnsupportedError();
1439 virDispatchError(domain
->conn
);
1444 * virDomainCoreDumpWithFormat:
1445 * @domain: a domain object
1446 * @to: path for the core file
1447 * @dumpformat: format of domain memory's dump (one of virDomainCoreDumpFormat enum)
1448 * @flags: bitwise-OR of virDomainCoreDumpFlags
1450 * This method will dump the core of a domain on a given file for analysis.
1451 * Note that for remote Xen Daemon the file path will be interpreted in
1452 * the remote host. Hypervisors may require the user to manually ensure
1453 * proper permissions on the file named by @to.
1455 * @dumpformat controls which format the dump will have; use of
1456 * VIR_DOMAIN_CORE_DUMP_FORMAT_RAW mirrors what virDomainCoreDump() will
1457 * perform. Not all hypervisors are able to support all formats.
1459 * If @flags includes VIR_DUMP_CRASH, then leave the guest shut off with
1460 * a crashed state after the dump completes. If @flags includes
1461 * VIR_DUMP_LIVE, then make the core dump while continuing to allow
1462 * the guest to run; otherwise, the guest is suspended during the dump.
1463 * VIR_DUMP_RESET flag forces reset of the guest after dump.
1464 * The above three flags are mutually exclusive.
1466 * Additionally, if @flags includes VIR_DUMP_BYPASS_CACHE, then libvirt
1467 * will attempt to bypass the file system cache while creating the file,
1468 * or fail if it cannot do so for the given system; this can allow less
1469 * pressure on file system cache, but also risks slowing saves to NFS.
1471 * Returns 0 in case of success and -1 in case of failure.
1476 virDomainCoreDumpWithFormat(virDomainPtr domain
, const char *to
,
1477 unsigned int dumpformat
, unsigned int flags
)
1481 VIR_DOMAIN_DEBUG(domain
, "to=%s, dumpformat=%u, flags=0x%x",
1482 to
, dumpformat
, flags
);
1484 virResetLastError();
1486 virCheckDomainReturn(domain
, -1);
1487 conn
= domain
->conn
;
1489 virCheckReadOnlyGoto(conn
->flags
, error
);
1490 virCheckNonNullArgGoto(to
, error
);
1492 if (dumpformat
>= VIR_DOMAIN_CORE_DUMP_FORMAT_LAST
) {
1493 virReportInvalidArg(flags
, _("dumpformat '%1$d' is not supported"),
1498 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DUMP_CRASH
, VIR_DUMP_LIVE
, error
);
1499 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DUMP_CRASH
, VIR_DUMP_RESET
, error
);
1500 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DUMP_LIVE
, VIR_DUMP_RESET
, error
);
1502 if (conn
->driver
->domainCoreDumpWithFormat
) {
1506 /* We must absolutize the file path as the save is done out of process */
1507 if (!(absolute_to
= g_canonicalize_filename(to
, NULL
))) {
1508 virReportError(VIR_ERR_INTERNAL_ERROR
, "%s",
1509 _("could not build absolute core file path"));
1513 ret
= conn
->driver
->domainCoreDumpWithFormat(domain
, absolute_to
,
1516 VIR_FREE(absolute_to
);
1523 virReportUnsupportedError();
1526 virDispatchError(domain
->conn
);
1532 * virDomainScreenshot:
1533 * @domain: a domain object
1534 * @stream: stream to use as output
1535 * @screen: monitor ID to take screenshot from
1536 * @flags: extra flags; not used yet, so callers should always pass 0
1538 * Take a screenshot of current domain console as a stream. The image format
1539 * is hypervisor specific. Moreover, some hypervisors supports multiple
1540 * displays per domain. These can be distinguished by @screen argument.
1542 * This call sets up a stream; subsequent use of stream API is necessary
1543 * to transfer actual data, determine how much data is successfully
1544 * transferred, and detect any errors.
1546 * The screen ID is the sequential number of screen. In case of multiple
1547 * graphics cards, heads are enumerated before devices, e.g. having
1548 * two graphics cards, both with four heads, screen ID 5 addresses
1549 * the second head on the second card.
1551 * Returns a string representing the mime-type of the image format, or
1552 * NULL upon error. The caller must free() the returned value.
1557 virDomainScreenshot(virDomainPtr domain
,
1558 virStreamPtr stream
,
1559 unsigned int screen
,
1562 VIR_DOMAIN_DEBUG(domain
, "stream=%p, flags=0x%x", stream
, flags
);
1564 virResetLastError();
1566 virCheckDomainReturn(domain
, NULL
);
1567 virCheckStreamGoto(stream
, error
);
1568 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
1570 if (domain
->conn
!= stream
->conn
) {
1571 virReportInvalidArg(stream
,
1572 _("stream must match connection of domain '%1$s'"),
1577 if (domain
->conn
->driver
->domainScreenshot
) {
1579 ret
= domain
->conn
->driver
->domainScreenshot(domain
, stream
,
1587 virReportUnsupportedError();
1590 virDispatchError(domain
->conn
);
1596 * virDomainShutdown:
1597 * @domain: a domain object
1599 * Shutdown a domain, the domain object is still usable thereafter, but
1600 * the domain OS is being stopped. Note that the guest OS may ignore the
1601 * request. Additionally, the hypervisor may check and support the domain
1602 * 'on_poweroff' XML setting resulting in a domain that reboots instead of
1603 * shutting down. For guests that react to a shutdown request, the differences
1604 * from virDomainDestroy() are that the guests disk storage will be in a
1605 * stable state rather than having the (virtual) power cord pulled, and
1606 * this command returns as soon as the shutdown request is issued rather
1607 * than blocking until the guest is no longer running.
1609 * If the domain is transient and has any snapshot metadata (see
1610 * virDomainSnapshotNum()), then that metadata will automatically
1611 * be deleted when the domain quits.
1613 * Returns 0 in case of success and -1 in case of failure.
1618 virDomainShutdown(virDomainPtr domain
)
1622 VIR_DOMAIN_DEBUG(domain
);
1624 virResetLastError();
1626 virCheckDomainReturn(domain
, -1);
1627 conn
= domain
->conn
;
1629 virCheckReadOnlyGoto(conn
->flags
, error
);
1631 if (conn
->driver
->domainShutdown
) {
1633 ret
= conn
->driver
->domainShutdown(domain
);
1639 virReportUnsupportedError();
1642 virDispatchError(domain
->conn
);
1648 * virDomainShutdownFlags:
1649 * @domain: a domain object
1650 * @flags: bitwise-OR of virDomainShutdownFlagValues
1652 * Shutdown a domain, the domain object is still usable thereafter but
1653 * the domain OS is being stopped. Note that the guest OS may ignore the
1654 * request. Additionally, the hypervisor may check and support the domain
1655 * 'on_poweroff' XML setting resulting in a domain that reboots instead of
1656 * shutting down. For guests that react to a shutdown request, the differences
1657 * from virDomainDestroy() are that the guest's disk storage will be in a
1658 * stable state rather than having the (virtual) power cord pulled, and
1659 * this command returns as soon as the shutdown request is issued rather
1660 * than blocking until the guest is no longer running.
1662 * If the domain is transient and has any snapshot metadata (see
1663 * virDomainSnapshotNum()), then that metadata will automatically
1664 * be deleted when the domain quits.
1666 * If @flags is set to zero, then the hypervisor will choose the
1667 * method of shutdown it considers best. To have greater control
1668 * pass one or more of the virDomainShutdownFlagValues. The order
1669 * in which the hypervisor tries each shutdown method is undefined,
1670 * and a hypervisor is not required to support all methods.
1672 * To use guest agent (VIR_DOMAIN_SHUTDOWN_GUEST_AGENT) the domain XML
1673 * must have <channel> configured.
1675 * Returns 0 in case of success and -1 in case of failure.
1680 virDomainShutdownFlags(virDomainPtr domain
, unsigned int flags
)
1684 VIR_DOMAIN_DEBUG(domain
, "flags=0x%x", flags
);
1686 virResetLastError();
1688 virCheckDomainReturn(domain
, -1);
1689 conn
= domain
->conn
;
1691 virCheckReadOnlyGoto(conn
->flags
, error
);
1693 if (conn
->driver
->domainShutdownFlags
) {
1695 ret
= conn
->driver
->domainShutdownFlags(domain
, flags
);
1701 virReportUnsupportedError();
1704 virDispatchError(domain
->conn
);
1711 * @domain: a domain object
1712 * @flags: bitwise-OR of virDomainRebootFlagValues
1714 * Reboot a domain, the domain object is still usable thereafter, but
1715 * the domain OS is being stopped for a restart.
1716 * Note that the guest OS may ignore the request.
1717 * Additionally, the hypervisor may check and support the domain
1718 * 'on_reboot' XML setting resulting in a domain that shuts down instead
1721 * If @flags is set to zero, then the hypervisor will choose the
1722 * method of shutdown it considers best. To have greater control
1723 * pass one or more of the virDomainRebootFlagValues. The order
1724 * in which the hypervisor tries each shutdown method is undefined,
1725 * and a hypervisor is not required to support all methods.
1727 * To use guest agent (VIR_DOMAIN_REBOOT_GUEST_AGENT) the domain XML
1728 * must have <channel> configured.
1730 * Due to implementation limitations in some drivers (the qemu driver,
1731 * for instance) it is not advised to migrate or save a guest that is
1732 * rebooting as a result of this API. Migrating such a guest can lead
1733 * to a plain shutdown on the destination.
1735 * Returns 0 in case of success and -1 in case of failure.
1740 virDomainReboot(virDomainPtr domain
, unsigned int flags
)
1744 VIR_DOMAIN_DEBUG(domain
, "flags=0x%x", flags
);
1746 virResetLastError();
1748 virCheckDomainReturn(domain
, -1);
1749 conn
= domain
->conn
;
1751 virCheckReadOnlyGoto(conn
->flags
, error
);
1753 if (conn
->driver
->domainReboot
) {
1755 ret
= conn
->driver
->domainReboot(domain
, flags
);
1761 virReportUnsupportedError();
1764 virDispatchError(domain
->conn
);
1771 * @domain: a domain object
1772 * @flags: extra flags; not used yet, so callers should always pass 0
1774 * Reset a domain immediately without any guest OS shutdown.
1775 * Reset emulates the power reset button on a machine, where all
1776 * hardware sees the RST line set and reinitializes internal state.
1778 * Note that there is a risk of data loss caused by reset without any
1779 * guest OS shutdown.
1781 * Returns 0 in case of success and -1 in case of failure.
1786 virDomainReset(virDomainPtr domain
, unsigned int flags
)
1790 VIR_DOMAIN_DEBUG(domain
, "flags=0x%x", flags
);
1792 virResetLastError();
1794 virCheckDomainReturn(domain
, -1);
1795 conn
= domain
->conn
;
1797 virCheckReadOnlyGoto(conn
->flags
, error
);
1799 if (conn
->driver
->domainReset
) {
1801 ret
= conn
->driver
->domainReset(domain
, flags
);
1807 virReportUnsupportedError();
1810 virDispatchError(domain
->conn
);
1817 * @domain: a domain object
1819 * Get the public name for that domain
1821 * Returns a pointer to the name or NULL, the string need not be deallocated
1822 * its lifetime will be the same as the domain object.
1827 virDomainGetName(virDomainPtr domain
)
1829 VIR_DEBUG("domain=%p", domain
);
1831 virResetLastError();
1833 virCheckDomainReturn(domain
, NULL
);
1835 return domain
->name
;
1841 * @domain: a domain object
1842 * @uuid: pointer to a VIR_UUID_BUFLEN bytes array
1844 * Get the UUID for a domain
1846 * Returns -1 in case of error, 0 in case of success
1851 virDomainGetUUID(virDomainPtr domain
, unsigned char *uuid
)
1853 VIR_DOMAIN_DEBUG(domain
, "uuid=%p", uuid
);
1855 virResetLastError();
1857 virCheckDomainReturn(domain
, -1);
1858 virCheckNonNullArgGoto(uuid
, error
);
1860 memcpy(uuid
, &domain
->uuid
[0], VIR_UUID_BUFLEN
);
1865 virDispatchError(domain
->conn
);
1871 * virDomainGetUUIDString:
1872 * @domain: a domain object
1873 * @buf: pointer to a VIR_UUID_STRING_BUFLEN bytes array
1875 * Get the UUID for a domain as string. For more information about
1878 * Returns -1 in case of error, 0 in case of success
1883 virDomainGetUUIDString(virDomainPtr domain
, char *buf
)
1885 VIR_DOMAIN_DEBUG(domain
, "buf=%p", buf
);
1887 virResetLastError();
1889 virCheckDomainReturn(domain
, -1);
1890 virCheckNonNullArgGoto(buf
, error
);
1892 virUUIDFormat(domain
->uuid
, buf
);
1896 virDispatchError(domain
->conn
);
1903 * @domain: a domain object
1905 * Get the hypervisor ID number for the domain
1907 * Returns the domain ID number or (unsigned int) -1 in case of error
1912 virDomainGetID(virDomainPtr domain
)
1914 VIR_DOMAIN_DEBUG(domain
);
1916 virResetLastError();
1918 virCheckDomainReturn(domain
, (unsigned int)-1);
1925 * virDomainGetOSType:
1926 * @domain: a domain object
1928 * Get the type of domain operation system.
1930 * Returns the new string or NULL in case of error, the string must be
1931 * freed by the caller.
1936 virDomainGetOSType(virDomainPtr domain
)
1940 VIR_DOMAIN_DEBUG(domain
);
1942 virResetLastError();
1944 virCheckDomainReturn(domain
, NULL
);
1945 conn
= domain
->conn
;
1947 if (conn
->driver
->domainGetOSType
) {
1949 ret
= conn
->driver
->domainGetOSType(domain
);
1955 virReportUnsupportedError();
1958 virDispatchError(domain
->conn
);
1964 * virDomainGetMaxMemory:
1965 * @domain: a domain object or NULL
1967 * Retrieve the maximum amount of physical memory allocated to a
1968 * domain. If domain is NULL, then this get the amount of memory reserved
1969 * to Domain0 i.e. the domain where the application runs.
1971 * Returns the memory size in kibibytes (blocks of 1024 bytes), or 0 in
1977 virDomainGetMaxMemory(virDomainPtr domain
)
1981 VIR_DOMAIN_DEBUG(domain
);
1983 virResetLastError();
1985 virCheckDomainReturn(domain
, 0);
1986 conn
= domain
->conn
;
1988 if (conn
->driver
->domainGetMaxMemory
) {
1989 unsigned long long ret
;
1990 ret
= conn
->driver
->domainGetMaxMemory(domain
);
1993 if ((unsigned long) ret
!= ret
) {
1994 virReportError(VIR_ERR_OVERFLOW
, _("result too large: %1$llu"),
2001 virReportUnsupportedError();
2004 virDispatchError(domain
->conn
);
2010 * virDomainSetMaxMemory:
2011 * @domain: a domain object or NULL
2012 * @memory: the memory size in kibibytes (blocks of 1024 bytes)
2014 * Dynamically change the maximum amount of physical memory allocated to a
2015 * domain. If domain is NULL, then this change the amount of memory reserved
2016 * to Domain0 i.e. the domain where the application runs.
2017 * This function may require privileged access to the hypervisor.
2019 * This command is hypervisor-specific for whether active, persistent,
2020 * or both configurations are changed; for more control, use
2021 * virDomainSetMemoryFlags().
2023 * Returns 0 in case of success and -1 in case of failure.
2028 virDomainSetMaxMemory(virDomainPtr domain
, unsigned long memory
)
2032 VIR_DOMAIN_DEBUG(domain
, "memory=%lu", memory
);
2034 virResetLastError();
2036 virCheckDomainReturn(domain
, -1);
2037 conn
= domain
->conn
;
2039 virCheckReadOnlyGoto(conn
->flags
, error
);
2040 virCheckNonZeroArgGoto(memory
, error
);
2042 if (virMemoryMaxValue(true) / 1024 <= memory
) {
2043 virReportError(VIR_ERR_OVERFLOW
, _("input too large: %1$lu"),
2048 if (conn
->driver
->domainSetMaxMemory
) {
2050 ret
= conn
->driver
->domainSetMaxMemory(domain
, memory
);
2056 virReportUnsupportedError();
2059 virDispatchError(domain
->conn
);
2065 * virDomainSetMemory:
2066 * @domain: a domain object or NULL
2067 * @memory: the memory size in kibibytes (blocks of 1024 bytes)
2069 * Dynamically change the target amount of physical memory allocated to a
2070 * domain. If domain is NULL, then this change the amount of memory reserved
2071 * to Domain0 i.e. the domain where the application runs.
2072 * This function may require privileged access to the hypervisor.
2074 * This command is hypervisor-specific for whether active, persistent,
2075 * or both configurations are changed; for more control, use
2076 * virDomainSetMemoryFlags().
2078 * Returns 0 in case of success and -1 in case of failure.
2083 virDomainSetMemory(virDomainPtr domain
, unsigned long memory
)
2087 VIR_DOMAIN_DEBUG(domain
, "memory=%lu", memory
);
2089 virResetLastError();
2091 virCheckDomainReturn(domain
, -1);
2092 conn
= domain
->conn
;
2094 virCheckReadOnlyGoto(conn
->flags
, error
);
2095 virCheckNonZeroArgGoto(memory
, error
);
2097 if (virMemoryMaxValue(true) / 1024 <= memory
) {
2098 virReportError(VIR_ERR_OVERFLOW
, _("input too large: %1$lu"),
2103 if (conn
->driver
->domainSetMemory
) {
2105 ret
= conn
->driver
->domainSetMemory(domain
, memory
);
2111 virReportUnsupportedError();
2114 virDispatchError(domain
->conn
);
2120 * virDomainSetMemoryFlags:
2121 * @domain: a domain object or NULL
2122 * @memory: the memory size in kibibytes (blocks of 1024 bytes)
2123 * @flags: bitwise-OR of virDomainMemoryModFlags
2125 * Dynamically change the target amount of physical memory allocated to a
2126 * domain. If domain is NULL, then this change the amount of memory reserved
2127 * to Domain0 i.e. the domain where the application runs.
2128 * This function may require privileged access to the hypervisor.
2130 * @flags may include VIR_DOMAIN_AFFECT_LIVE or VIR_DOMAIN_AFFECT_CONFIG.
2131 * Both flags may be set. If VIR_DOMAIN_AFFECT_LIVE is set, the change affects
2132 * a running domain and will fail if domain is not active.
2133 * If VIR_DOMAIN_AFFECT_CONFIG is set, the change affects persistent state,
2134 * and will fail for transient domains. If neither flag is specified
2135 * (that is, @flags is VIR_DOMAIN_AFFECT_CURRENT), then an inactive domain
2136 * modifies persistent setup, while an active domain is hypervisor-dependent
2137 * on whether just live or both live and persistent state is changed.
2138 * If VIR_DOMAIN_MEM_MAXIMUM is set, the change affects domain's maximum memory
2139 * size rather than current memory size.
2140 * Not all hypervisors can support all flag combinations.
2142 * Returns 0 in case of success, -1 in case of failure.
2147 virDomainSetMemoryFlags(virDomainPtr domain
, unsigned long memory
,
2152 VIR_DOMAIN_DEBUG(domain
, "memory=%lu, flags=0x%x", memory
, flags
);
2154 virResetLastError();
2156 virCheckDomainReturn(domain
, -1);
2157 conn
= domain
->conn
;
2159 virCheckReadOnlyGoto(conn
->flags
, error
);
2160 virCheckNonZeroArgGoto(memory
, error
);
2162 if (virMemoryMaxValue(true) / 1024 <= memory
) {
2163 virReportError(VIR_ERR_OVERFLOW
, _("input too large: %1$lu"),
2168 if (conn
->driver
->domainSetMemoryFlags
) {
2170 ret
= conn
->driver
->domainSetMemoryFlags(domain
, memory
, flags
);
2176 virReportUnsupportedError();
2179 virDispatchError(domain
->conn
);
2185 * virDomainSetMemoryStatsPeriod:
2186 * @domain: a domain object or NULL
2187 * @period: the period in seconds for stats collection
2188 * @flags: bitwise-OR of virDomainMemoryModFlags
2190 * Dynamically change the domain memory balloon driver statistics collection
2191 * period. Use 0 to disable and a positive value to enable.
2193 * @flags may include VIR_DOMAIN_AFFECT_LIVE or VIR_DOMAIN_AFFECT_CONFIG.
2194 * Both flags may be set. If VIR_DOMAIN_AFFECT_LIVE is set, the change affects
2195 * a running domain and will fail if domain is not active.
2196 * If VIR_DOMAIN_AFFECT_CONFIG is set, the change affects persistent state,
2197 * and will fail for transient domains. If neither flag is specified
2198 * (that is, @flags is VIR_DOMAIN_AFFECT_CURRENT), then an inactive domain
2199 * modifies persistent setup, while an active domain is hypervisor-dependent
2200 * on whether just live or both live and persistent state is changed.
2202 * Not all hypervisors can support all flag combinations.
2204 * Returns 0 in case of success, -1 in case of failure.
2209 virDomainSetMemoryStatsPeriod(virDomainPtr domain
, int period
,
2214 VIR_DOMAIN_DEBUG(domain
, "period=%d, flags=0x%x", period
, flags
);
2216 virResetLastError();
2218 virCheckDomainReturn(domain
, -1);
2219 conn
= domain
->conn
;
2221 virCheckReadOnlyGoto(conn
->flags
, error
);
2223 /* This must be positive to set the balloon collection period */
2224 virCheckNonNegativeArgGoto(period
, error
);
2226 if (conn
->driver
->domainSetMemoryStatsPeriod
) {
2228 ret
= conn
->driver
->domainSetMemoryStatsPeriod(domain
, period
, flags
);
2234 virReportUnsupportedError();
2237 virDispatchError(domain
->conn
);
2243 * virDomainSetMemoryParameters:
2244 * @domain: pointer to domain object
2245 * @params: pointer to memory parameter objects
2246 * @nparams: number of memory parameter (this value can be the same or
2247 * less than the number of parameters supported)
2248 * @flags: bitwise-OR of virDomainModificationImpact
2250 * Change all or a subset of the memory tunables.
2251 * This function may require privileged access to the hypervisor.
2253 * Possible values for all *_limit memory tunables are in range from 0 to
2254 * VIR_DOMAIN_MEMORY_PARAM_UNLIMITED.
2256 * Returns -1 in case of error, 0 in case of success.
2261 virDomainSetMemoryParameters(virDomainPtr domain
,
2262 virTypedParameterPtr params
,
2263 int nparams
, unsigned int flags
)
2267 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%d, flags=0x%x",
2268 params
, nparams
, flags
);
2269 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
2271 virResetLastError();
2273 virCheckDomainReturn(domain
, -1);
2274 conn
= domain
->conn
;
2276 virCheckReadOnlyGoto(conn
->flags
, error
);
2277 virCheckNonNullArgGoto(params
, error
);
2278 virCheckPositiveArgGoto(nparams
, error
);
2280 if (virTypedParameterValidateSet(conn
, params
, nparams
) < 0)
2283 if (conn
->driver
->domainSetMemoryParameters
) {
2285 ret
= conn
->driver
->domainSetMemoryParameters(domain
, params
, nparams
, flags
);
2291 virReportUnsupportedError();
2294 virDispatchError(domain
->conn
);
2300 * virDomainGetMemoryParameters:
2301 * @domain: pointer to domain object
2302 * @params: pointer to memory parameter object
2303 * (return value, allocated by the caller)
2304 * @nparams: pointer to number of memory parameters; input and output
2305 * @flags: bitwise-OR of virDomainModificationImpact and virTypedParameterFlags
2307 * Get all memory parameters. On input, @nparams gives the size of the
2308 * @params array; on output, @nparams gives how many slots were filled
2309 * with parameter information, which might be less but will not exceed
2312 * As a special case, calling with @params as NULL and @nparams as 0 on
2313 * input will cause @nparams on output to contain the number of parameters
2314 * supported by the hypervisor. The caller should then allocate @params
2315 * array, i.e. (sizeof(@virTypedParameter) * @nparams) bytes and call the API
2318 * Here is a sample code snippet:
2320 * if (virDomainGetMemoryParameters(dom, NULL, &nparams, 0) == 0 &&
2322 * if ((params = malloc(sizeof(*params) * nparams)) == NULL)
2324 * memset(params, 0, sizeof(*params) * nparams);
2325 * if (virDomainGetMemoryParameters(dom, params, &nparams, 0))
2329 * This function may require privileged access to the hypervisor. This function
2330 * expects the caller to allocate the @params.
2332 * Returns -1 in case of error, 0 in case of success.
2337 virDomainGetMemoryParameters(virDomainPtr domain
,
2338 virTypedParameterPtr params
,
2339 int *nparams
, unsigned int flags
)
2344 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%d, flags=0x%x",
2345 params
, (nparams
) ? *nparams
: -1, flags
);
2347 virResetLastError();
2349 virCheckDomainReturn(domain
, -1);
2350 virCheckNonNullArgGoto(nparams
, error
);
2351 virCheckNonNegativeArgGoto(*nparams
, error
);
2353 virCheckNonNullArgGoto(params
, error
);
2355 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
2356 VIR_DRV_FEATURE_TYPED_PARAM_STRING
);
2360 flags
|= VIR_TYPED_PARAM_STRING_OKAY
;
2362 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_AFFECT_LIVE
,
2363 VIR_DOMAIN_AFFECT_CONFIG
,
2366 conn
= domain
->conn
;
2368 if (conn
->driver
->domainGetMemoryParameters
) {
2370 ret
= conn
->driver
->domainGetMemoryParameters(domain
, params
, nparams
, flags
);
2375 virReportUnsupportedError();
2378 virDispatchError(domain
->conn
);
2384 * virDomainSetNumaParameters:
2385 * @domain: pointer to domain object
2386 * @params: pointer to numa parameter objects
2387 * @nparams: number of numa parameters (this value can be the same or
2388 * less than the number of parameters supported)
2389 * @flags: bitwise-OR of virDomainModificationImpact
2391 * Change all or a subset of the numa tunables.
2392 * This function may require privileged access to the hypervisor.
2394 * Changing live configuration may be possible only in some cases. For
2395 * instance, for QEMU driver the mode (VIR_DOMAIN_NUMA_MODE) can not be
2396 * changed, and changing the nodeset (VIR_DOMAIN_NUMA_NODESET) is possible
2397 * only for VIR_DOMAIN_NUMATUNE_MEM_RESTRICTIVE mode.
2399 * Changing persistent configuration does not pose such limitations.
2401 * Returns -1 in case of error, 0 in case of success.
2406 virDomainSetNumaParameters(virDomainPtr domain
,
2407 virTypedParameterPtr params
,
2408 int nparams
, unsigned int flags
)
2412 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%d, flags=0x%x",
2413 params
, nparams
, flags
);
2414 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
2416 virResetLastError();
2418 virCheckDomainReturn(domain
, -1);
2419 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
2420 virCheckNonNullArgGoto(params
, error
);
2421 virCheckPositiveArgGoto(nparams
, error
);
2422 if (virTypedParameterValidateSet(domain
->conn
, params
, nparams
) < 0)
2425 conn
= domain
->conn
;
2427 if (conn
->driver
->domainSetNumaParameters
) {
2429 ret
= conn
->driver
->domainSetNumaParameters(domain
, params
, nparams
,
2436 virReportUnsupportedError();
2439 virDispatchError(domain
->conn
);
2445 * virDomainGetNumaParameters:
2446 * @domain: pointer to domain object
2447 * @params: pointer to numa parameter object
2448 * (return value, allocated by the caller)
2449 * @nparams: pointer to number of numa parameters
2450 * @flags: bitwise-OR of virDomainModificationImpact and virTypedParameterFlags
2452 * Get all numa parameters. On input, @nparams gives the size of the
2453 * @params array; on output, @nparams gives how many slots were filled
2454 * with parameter information, which might be less but will not exceed
2457 * As a special case, calling with @params as NULL and @nparams as 0 on
2458 * input will cause @nparams on output to contain the number of parameters
2459 * supported by the hypervisor. The caller should then allocate @params
2460 * array, i.e. (sizeof(@virTypedParameter) * @nparams) bytes and call the API
2463 * See virDomainGetMemoryParameters() for an equivalent usage example.
2465 * This function may require privileged access to the hypervisor. This function
2466 * expects the caller to allocate the @params.
2468 * Returns -1 in case of error, 0 in case of success.
2473 virDomainGetNumaParameters(virDomainPtr domain
,
2474 virTypedParameterPtr params
,
2475 int *nparams
, unsigned int flags
)
2480 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%d, flags=0x%x",
2481 params
, (nparams
) ? *nparams
: -1, flags
);
2483 virResetLastError();
2485 virCheckDomainReturn(domain
, -1);
2486 virCheckNonNullArgGoto(nparams
, error
);
2487 virCheckNonNegativeArgGoto(*nparams
, error
);
2489 virCheckNonNullArgGoto(params
, error
);
2491 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
2492 VIR_DRV_FEATURE_TYPED_PARAM_STRING
);
2496 flags
|= VIR_TYPED_PARAM_STRING_OKAY
;
2498 conn
= domain
->conn
;
2500 if (conn
->driver
->domainGetNumaParameters
) {
2502 ret
= conn
->driver
->domainGetNumaParameters(domain
, params
, nparams
,
2508 virReportUnsupportedError();
2511 virDispatchError(domain
->conn
);
2517 * virDomainSetBlkioParameters:
2518 * @domain: pointer to domain object
2519 * @params: pointer to blkio parameter objects
2520 * @nparams: number of blkio parameters (this value can be the same or
2521 * less than the number of parameters supported)
2522 * @flags: bitwise-OR of virDomainModificationImpact
2524 * Change all or a subset of the blkio tunables.
2525 * This function may require privileged access to the hypervisor.
2527 * Returns -1 in case of error, 0 in case of success.
2532 virDomainSetBlkioParameters(virDomainPtr domain
,
2533 virTypedParameterPtr params
,
2534 int nparams
, unsigned int flags
)
2538 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%d, flags=0x%x",
2539 params
, nparams
, flags
);
2540 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
2542 virResetLastError();
2544 virCheckDomainReturn(domain
, -1);
2545 conn
= domain
->conn
;
2547 virCheckReadOnlyGoto(conn
->flags
, error
);
2548 virCheckNonNullArgGoto(params
, error
);
2549 virCheckNonNegativeArgGoto(nparams
, error
);
2551 if (virTypedParameterValidateSet(conn
, params
, nparams
) < 0)
2554 if (conn
->driver
->domainSetBlkioParameters
) {
2556 ret
= conn
->driver
->domainSetBlkioParameters(domain
, params
, nparams
, flags
);
2562 virReportUnsupportedError();
2565 virDispatchError(domain
->conn
);
2571 * virDomainGetBlkioParameters:
2572 * @domain: pointer to domain object
2573 * @params: pointer to blkio parameter object
2574 * (return value, allocated by the caller)
2575 * @nparams: pointer to number of blkio parameters; input and output
2576 * @flags: bitwise-OR of virDomainModificationImpact and virTypedParameterFlags
2578 * Get all blkio parameters. On input, @nparams gives the size of the
2579 * @params array; on output, @nparams gives how many slots were filled
2580 * with parameter information, which might be less but will not exceed
2583 * As a special case, calling with @params as NULL and @nparams as 0 on
2584 * input will cause @nparams on output to contain the number of parameters
2585 * supported by the hypervisor. The caller should then allocate @params
2586 * array, i.e. (sizeof(@virTypedParameter) * @nparams) bytes and call the API
2589 * See virDomainGetMemoryParameters() for an equivalent usage example.
2591 * This function may require privileged access to the hypervisor. This function
2592 * expects the caller to allocate the @params.
2594 * Returns -1 in case of error, 0 in case of success.
2599 virDomainGetBlkioParameters(virDomainPtr domain
,
2600 virTypedParameterPtr params
,
2601 int *nparams
, unsigned int flags
)
2606 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%d, flags=0x%x",
2607 params
, (nparams
) ? *nparams
: -1, flags
);
2609 virResetLastError();
2611 virCheckDomainReturn(domain
, -1);
2612 virCheckNonNullArgGoto(nparams
, error
);
2613 virCheckNonNegativeArgGoto(*nparams
, error
);
2615 virCheckNonNullArgGoto(params
, error
);
2617 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
2618 VIR_DRV_FEATURE_TYPED_PARAM_STRING
);
2622 flags
|= VIR_TYPED_PARAM_STRING_OKAY
;
2624 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_AFFECT_LIVE
,
2625 VIR_DOMAIN_AFFECT_CONFIG
,
2628 conn
= domain
->conn
;
2630 if (conn
->driver
->domainGetBlkioParameters
) {
2632 ret
= conn
->driver
->domainGetBlkioParameters(domain
, params
, nparams
, flags
);
2637 virReportUnsupportedError();
2640 virDispatchError(domain
->conn
);
2647 * @domain: a domain object
2648 * @info: pointer to a virDomainInfo structure allocated by the user
2650 * Extract information about a domain. Note that if the connection
2651 * used to get the domain is limited only a partial set of the information
2654 * Returns 0 in case of success and -1 in case of failure.
2659 virDomainGetInfo(virDomainPtr domain
, virDomainInfoPtr info
)
2663 VIR_DOMAIN_DEBUG(domain
, "info=%p", info
);
2665 virResetLastError();
2668 memset(info
, 0, sizeof(*info
));
2670 virCheckDomainReturn(domain
, -1);
2671 virCheckNonNullArgGoto(info
, error
);
2673 conn
= domain
->conn
;
2675 if (conn
->driver
->domainGetInfo
) {
2677 ret
= conn
->driver
->domainGetInfo(domain
, info
);
2683 virReportUnsupportedError();
2686 virDispatchError(domain
->conn
);
2692 * virDomainGetState:
2693 * @domain: a domain object
2694 * @state: returned state of the domain (one of virDomainState)
2695 * @reason: returned reason which led to @state (one of virDomain*Reason
2696 * corresponding to the current state); it is allowed to be NULL
2697 * @flags: extra flags; not used yet, so callers should always pass 0
2699 * Extract domain state. Each state can be accompanied with a reason (if known)
2700 * which led to the state.
2702 * Returns 0 in case of success and -1 in case of failure.
2707 virDomainGetState(virDomainPtr domain
,
2714 VIR_DOMAIN_DEBUG(domain
, "state=%p, reason=%p, flags=0x%x",
2715 state
, reason
, flags
);
2717 virResetLastError();
2719 virCheckDomainReturn(domain
, -1);
2720 virCheckNonNullArgGoto(state
, error
);
2722 conn
= domain
->conn
;
2723 if (conn
->driver
->domainGetState
) {
2725 ret
= conn
->driver
->domainGetState(domain
, state
, reason
, flags
);
2731 virReportUnsupportedError();
2734 virDispatchError(domain
->conn
);
2740 * virDomainGetControlInfo:
2741 * @domain: a domain object
2742 * @info: pointer to a virDomainControlInfo structure allocated by the user
2743 * @flags: extra flags; not used yet, so callers should always pass 0
2745 * Extract details about current state of control interface to a domain.
2747 * Returns 0 in case of success and -1 in case of failure.
2752 virDomainGetControlInfo(virDomainPtr domain
,
2753 virDomainControlInfoPtr info
,
2758 VIR_DOMAIN_DEBUG(domain
, "info=%p, flags=0x%x", info
, flags
);
2760 virResetLastError();
2762 virCheckDomainReturn(domain
, -1);
2763 virCheckNonNullArgGoto(info
, error
);
2765 conn
= domain
->conn
;
2766 if (conn
->driver
->domainGetControlInfo
) {
2768 ret
= conn
->driver
->domainGetControlInfo(domain
, info
, flags
);
2774 virReportUnsupportedError();
2777 virDispatchError(domain
->conn
);
2783 * virDomainGetXMLDesc:
2784 * @domain: a domain object
2785 * @flags: bitwise-OR of virDomainXMLFlags
2787 * Provide an XML description of the domain. The description may be reused
2788 * later to relaunch the domain with virDomainCreateXML().
2790 * No security-sensitive data will be included unless @flags contains
2791 * VIR_DOMAIN_XML_SECURE; this flag is rejected on read-only
2792 * connections. If @flags includes VIR_DOMAIN_XML_INACTIVE, then the
2793 * XML represents the configuration that will be used on the next boot
2794 * of a persistent domain; otherwise, the configuration represents the
2795 * currently running domain. If @flags contains
2796 * VIR_DOMAIN_XML_UPDATE_CPU, then the portion of the domain XML
2797 * describing CPU capabilities is modified to match actual
2798 * capabilities of the host.
2800 * If @flags contains VIR_DOMAIN_XML_MIGRATABLE, the XML is altered to
2801 * assist in migrations, since the source and destination may be
2802 * running different libvirt versions. This may include trimming
2803 * redundant or default information that might confuse an older
2804 * recipient, or exposing internal details that aid a newer recipient;
2805 * this flag is rejected on read-only connections, and the resulting
2806 * XML might not validate against the schema, so it is mainly for
2809 * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case
2810 * of error. The caller must free() the returned value.
2815 virDomainGetXMLDesc(virDomainPtr domain
, unsigned int flags
)
2819 VIR_DOMAIN_DEBUG(domain
, "flags=0x%x", flags
);
2821 virResetLastError();
2823 virCheckDomainReturn(domain
, NULL
);
2824 conn
= domain
->conn
;
2826 if ((conn
->flags
& VIR_CONNECT_RO
) &&
2827 (flags
& (VIR_DOMAIN_XML_SECURE
| VIR_DOMAIN_XML_MIGRATABLE
))) {
2828 virReportError(VIR_ERR_OPERATION_DENIED
, "%s",
2829 _("virDomainGetXMLDesc with secure flag"));
2833 if (conn
->driver
->domainGetXMLDesc
) {
2835 ret
= conn
->driver
->domainGetXMLDesc(domain
, flags
);
2841 virReportUnsupportedError();
2844 virDispatchError(domain
->conn
);
2850 * virConnectDomainXMLFromNative:
2851 * @conn: a connection object
2852 * @nativeFormat: configuration format importing from
2853 * @nativeConfig: the configuration data to import
2854 * @flags: extra flags; not used yet, so callers should always pass 0
2856 * Reads native configuration data describing a domain, and
2857 * generates libvirt domain XML. The format of the native
2858 * data is hypervisor dependent.
2860 * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case
2861 * of error. The caller must free() the returned value.
2866 virConnectDomainXMLFromNative(virConnectPtr conn
,
2867 const char *nativeFormat
,
2868 const char *nativeConfig
,
2871 VIR_DEBUG("conn=%p, format=%s, config=%s, flags=0x%x",
2872 conn
, NULLSTR(nativeFormat
), NULLSTR(nativeConfig
), flags
);
2874 virResetLastError();
2876 virCheckConnectReturn(conn
, NULL
);
2877 virCheckReadOnlyGoto(conn
->flags
, error
);
2879 virCheckNonNullArgGoto(nativeFormat
, error
);
2880 virCheckNonNullArgGoto(nativeConfig
, error
);
2882 if (conn
->driver
->connectDomainXMLFromNative
) {
2884 ret
= conn
->driver
->connectDomainXMLFromNative(conn
,
2893 virReportUnsupportedError();
2896 virDispatchError(conn
);
2902 * virConnectDomainXMLToNative:
2903 * @conn: a connection object
2904 * @nativeFormat: configuration format exporting to
2905 * @domainXml: the domain configuration to export
2906 * @flags: extra flags; not used yet, so callers should always pass 0
2908 * Reads a domain XML configuration document, and generates
2909 * a native configuration file describing the domain.
2910 * The format of the native data is hypervisor dependent.
2912 * Note that certain hypervisor drivers such as the QEMU driver configure many
2913 * aspects of the domain dynamically via hypervisor APIs and that may not be
2914 * part of the returned native configuration format. Similarly certain resources
2915 * are passed to the hypervisor via file descriptors, which are not part of the
2916 * native configuration returned by this API. Such configuration is thus not
2917 * trivially usable outside of libvirt.
2919 * Returns a 0 terminated UTF-8 encoded native config datafile, or
2920 * NULL in case of error. The caller must free() the returned value.
2925 virConnectDomainXMLToNative(virConnectPtr conn
,
2926 const char *nativeFormat
,
2927 const char *domainXml
,
2930 VIR_DEBUG("conn=%p, format=%s, xml=%s, flags=0x%x",
2931 conn
, NULLSTR(nativeFormat
), NULLSTR(domainXml
), flags
);
2933 virResetLastError();
2935 virCheckConnectReturn(conn
, NULL
);
2936 virCheckReadOnlyGoto(conn
->flags
, error
);
2938 virCheckNonNullArgGoto(nativeFormat
, error
);
2939 virCheckNonNullArgGoto(domainXml
, error
);
2941 if (conn
->driver
->connectDomainXMLToNative
) {
2943 ret
= conn
->driver
->connectDomainXMLToNative(conn
,
2952 virReportUnsupportedError();
2955 virDispatchError(conn
);
2964 * - Get ready to accept incoming VM
2965 * - Generate optional cookie to pass to src
2968 * - Start migration and wait for send completion
2969 * - Kill off VM if successful, resume if failed
2972 * - Wait for recv completion and check status
2973 * - Kill off VM if unsuccessful
2977 virDomainMigrateVersion1(virDomainPtr domain
,
2978 virConnectPtr dconn
,
2979 unsigned long flags
,
2982 unsigned long bandwidth
)
2984 g_autofree
char *uri_out
= NULL
;
2985 g_autofree
char *cookie
= NULL
;
2986 int cookielen
= 0, ret
;
2988 unsigned int destflags
;
2990 VIR_DOMAIN_DEBUG(domain
,
2991 "dconn=%p, flags=0x%lx, dname=%s, uri=%s, bandwidth=%lu",
2992 dconn
, flags
, NULLSTR(dname
), NULLSTR(uri
), bandwidth
);
2994 virCheckNonEmptyOptStringArgReturn(dname
, NULL
);
2996 ret
= virDomainGetInfo(domain
, &info
);
2997 if (ret
== 0 && info
.state
== VIR_DOMAIN_PAUSED
)
2998 flags
|= VIR_MIGRATE_PAUSED
;
3000 destflags
= flags
& ~(VIR_MIGRATE_ABORT_ON_ERROR
|
3001 VIR_MIGRATE_AUTO_CONVERGE
);
3003 /* Prepare the migration.
3005 * The destination host may return a cookie, or leave cookie as
3008 * The destination host MUST set uri_out if uri_in is NULL.
3010 * If uri_in is non-NULL, then the destination host may modify
3011 * the URI by setting uri_out. If it does not wish to modify
3012 * the URI, it should leave uri_out as NULL.
3014 if (dconn
->driver
->domainMigratePrepare
3015 (dconn
, &cookie
, &cookielen
, uri
, &uri_out
, destflags
, dname
,
3019 if (uri
== NULL
&& uri_out
== NULL
) {
3020 virReportError(VIR_ERR_INTERNAL_ERROR
, "%s",
3021 _("domainMigratePrepare did not set uri"));
3025 uri
= uri_out
; /* Did domainMigratePrepare change URI? */
3027 /* Perform the migration. The driver isn't supposed to return
3028 * until the migration is complete.
3030 if (domain
->conn
->driver
->domainMigratePerform
3031 (domain
, cookie
, cookielen
, uri
, flags
, dname
, bandwidth
) == -1)
3034 /* Get the destination domain and return it or error.
3035 * 'domain' no longer actually exists at this point
3036 * (or so we hope), but we still use the object in memory
3037 * in order to get the name.
3039 dname
= dname
? dname
: domain
->name
;
3040 if (dconn
->driver
->domainMigrateFinish
)
3041 return dconn
->driver
->domainMigrateFinish
3042 (dconn
, dname
, cookie
, cookielen
, uri
, destflags
);
3044 return virDomainLookupByName(dconn
, dname
);
3052 * - Generate XML to pass to dst
3055 * - Get ready to accept incoming VM
3056 * - Generate optional cookie to pass to src
3059 * - Start migration and wait for send completion
3060 * - Kill off VM if successful, resume if failed
3063 * - Wait for recv completion and check status
3064 * - Kill off VM if unsuccessful
3068 virDomainMigrateVersion2(virDomainPtr domain
,
3069 virConnectPtr dconn
,
3070 unsigned long flags
,
3073 unsigned long bandwidth
)
3075 virDomainPtr ddomain
= NULL
;
3076 g_autofree
char *uri_out
= NULL
;
3077 g_autofree
char *cookie
= NULL
;
3078 g_autofree
char *dom_xml
= NULL
;
3079 int cookielen
= 0, ret
;
3081 virErrorPtr orig_err
= NULL
;
3082 unsigned int getxml_flags
= 0;
3084 unsigned long destflags
;
3086 VIR_DOMAIN_DEBUG(domain
,
3087 "dconn=%p, flags=0x%lx, dname=%s, uri=%s, bandwidth=%lu",
3088 dconn
, flags
, NULLSTR(dname
), NULLSTR(uri
), bandwidth
);
3090 virCheckNonEmptyOptStringArgReturn(dname
, NULL
);
3092 /* Prepare the migration.
3094 * The destination host may return a cookie, or leave cookie as
3097 * The destination host MUST set uri_out if uri_in is NULL.
3099 * If uri_in is non-NULL, then the destination host may modify
3100 * the URI by setting uri_out. If it does not wish to modify
3101 * the URI, it should leave uri_out as NULL.
3104 /* In version 2 of the protocol, the prepare step is slightly
3105 * different. We fetch the domain XML of the source domain
3106 * and pass it to Prepare2.
3108 if (!domain
->conn
->driver
->domainGetXMLDesc
) {
3109 virReportUnsupportedError();
3113 ret
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
3114 VIR_DRV_FEATURE_XML_MIGRATABLE
);
3118 getxml_flags
|= VIR_DOMAIN_XML_MIGRATABLE
;
3120 getxml_flags
|= VIR_DOMAIN_XML_SECURE
| VIR_DOMAIN_XML_UPDATE_CPU
;
3122 dom_xml
= domain
->conn
->driver
->domainGetXMLDesc(domain
, getxml_flags
);
3126 ret
= virDomainGetInfo(domain
, &info
);
3127 if (ret
== 0 && info
.state
== VIR_DOMAIN_PAUSED
)
3128 flags
|= VIR_MIGRATE_PAUSED
;
3130 destflags
= flags
& ~(VIR_MIGRATE_ABORT_ON_ERROR
|
3131 VIR_MIGRATE_AUTO_CONVERGE
);
3133 VIR_DEBUG("Prepare2 %p flags=0x%lx", dconn
, destflags
);
3134 ret
= dconn
->driver
->domainMigratePrepare2
3135 (dconn
, &cookie
, &cookielen
, uri
, &uri_out
, destflags
, dname
,
3136 bandwidth
, dom_xml
);
3140 if (uri
== NULL
&& uri_out
== NULL
) {
3141 virReportError(VIR_ERR_INTERNAL_ERROR
, "%s",
3142 _("domainMigratePrepare2 did not set uri"));
3144 /* Make sure Finish doesn't overwrite the error */
3145 virErrorPreserveLast(&orig_err
);
3149 uri
= uri_out
; /* Did domainMigratePrepare2 change URI? */
3151 /* Perform the migration. The driver isn't supposed to return
3152 * until the migration is complete.
3154 VIR_DEBUG("Perform %p", domain
->conn
);
3155 ret
= domain
->conn
->driver
->domainMigratePerform
3156 (domain
, cookie
, cookielen
, uri
, flags
, dname
, bandwidth
);
3158 /* Perform failed. Make sure Finish doesn't overwrite the error */
3160 virErrorPreserveLast(&orig_err
);
3162 /* If Perform returns < 0, then we need to cancel the VM
3163 * startup on the destination
3165 cancelled
= ret
< 0 ? 1 : 0;
3168 /* In version 2 of the migration protocol, we pass the
3169 * status code from the sender to the destination host,
3170 * so it can do any cleanup if the migration failed.
3172 dname
= dname
? dname
: domain
->name
;
3173 VIR_DEBUG("Finish2 %p ret=%d", dconn
, ret
);
3174 ddomain
= dconn
->driver
->domainMigrateFinish2
3175 (dconn
, dname
, cookie
, cookielen
, uri
, destflags
, cancelled
);
3176 if (cancelled
&& ddomain
)
3177 VIR_ERROR(_("finish step ignored that migration was cancelled"));
3180 virErrorRestore(&orig_err
);
3189 * - Generate XML to pass to dst
3190 * - Generate optional cookie to pass to dst
3193 * - Get ready to accept incoming VM
3194 * - Generate optional cookie to pass to src
3197 * - Start migration and wait for send completion
3198 * - Generate optional cookie to pass to dst
3201 * - Wait for recv completion and check status
3202 * - Kill off VM if failed, resume if success
3203 * - Generate optional cookie to pass to src
3206 * - Kill off VM if success, resume if failed
3208 * If useParams is true, params and nparams contain migration parameters and
3209 * we know it's safe to call the API which supports extensible parameters.
3210 * Otherwise, we have to use xmlin, dname, uri, and bandwidth and pass them
3211 * to the old-style APIs.
3214 virDomainMigrateVersion3Full(virDomainPtr domain
,
3215 virConnectPtr dconn
,
3219 unsigned long long bandwidth
,
3220 virTypedParameterPtr params
,
3225 virDomainPtr ddomain
= NULL
;
3226 g_autofree
char *uri_out
= NULL
;
3227 g_autofree
char *cookiein
= NULL
;
3228 g_autofree
char *cookieout
= NULL
;
3229 g_autofree
char *dom_xml
= NULL
;
3230 int cookieinlen
= 0;
3231 int cookieoutlen
= 0;
3234 virErrorPtr orig_err
= NULL
;
3236 unsigned long protection
= 0;
3237 bool notify_source
= true;
3238 unsigned int destflags
;
3240 virTypedParameterPtr tmp
;
3242 VIR_DOMAIN_DEBUG(domain
,
3243 "dconn=%p, xmlin=%s, dname=%s, uri=%s, bandwidth=%llu, "
3244 "params=%p, nparams=%d, useParams=%d, flags=0x%x",
3245 dconn
, NULLSTR(xmlin
), NULLSTR(dname
), NULLSTR(uri
),
3246 bandwidth
, params
, nparams
, useParams
, flags
);
3247 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
3249 virCheckNonEmptyOptStringArgReturn(dname
, NULL
);
3252 (!domain
->conn
->driver
->domainMigrateBegin3
||
3253 !domain
->conn
->driver
->domainMigratePerform3
||
3254 !domain
->conn
->driver
->domainMigrateConfirm3
||
3255 !dconn
->driver
->domainMigratePrepare3
||
3256 !dconn
->driver
->domainMigrateFinish3
)) ||
3258 (!domain
->conn
->driver
->domainMigrateBegin3Params
||
3259 !domain
->conn
->driver
->domainMigratePerform3Params
||
3260 !domain
->conn
->driver
->domainMigrateConfirm3Params
||
3261 !dconn
->driver
->domainMigratePrepare3Params
||
3262 !dconn
->driver
->domainMigrateFinish3Params
))) {
3263 virReportUnsupportedError();
3267 virTypedParamsCopy(&tmp
, params
, nparams
);
3270 ret
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
3271 VIR_DRV_FEATURE_MIGRATE_CHANGE_PROTECTION
);
3275 protection
= VIR_MIGRATE_CHANGE_PROTECTION
;
3277 VIR_DEBUG("Begin3 %p", domain
->conn
);
3279 dom_xml
= domain
->conn
->driver
->domainMigrateBegin3Params
3280 (domain
, params
, nparams
, &cookieout
, &cookieoutlen
,
3281 flags
| protection
);
3283 dom_xml
= domain
->conn
->driver
->domainMigrateBegin3
3284 (domain
, xmlin
, &cookieout
, &cookieoutlen
,
3285 flags
| protection
, dname
, bandwidth
);
3291 /* If source is new enough to support extensible migration parameters,
3292 * it's certainly new enough to support virDomainGetState. */
3293 ret
= virDomainGetState(domain
, &state
, NULL
, 0);
3295 ret
= virDomainGetInfo(domain
, &info
);
3299 state
== VIR_DOMAIN_PAUSED
&&
3300 !(flags
& VIR_MIGRATE_POSTCOPY_RESUME
))
3301 flags
|= VIR_MIGRATE_PAUSED
;
3303 destflags
= flags
& ~(VIR_MIGRATE_ABORT_ON_ERROR
|
3304 VIR_MIGRATE_AUTO_CONVERGE
);
3306 VIR_DEBUG("Prepare3 %p flags=0x%x", dconn
, destflags
);
3307 cookiein
= g_steal_pointer(&cookieout
);
3308 cookieinlen
= cookieoutlen
;
3311 if (virTypedParamsReplaceString(¶ms
, &nparams
,
3312 VIR_MIGRATE_PARAM_DEST_XML
,
3315 ret
= dconn
->driver
->domainMigratePrepare3Params
3316 (dconn
, params
, nparams
, cookiein
, cookieinlen
,
3317 &cookieout
, &cookieoutlen
, &uri_out
, destflags
);
3319 ret
= dconn
->driver
->domainMigratePrepare3
3320 (dconn
, cookiein
, cookieinlen
, &cookieout
, &cookieoutlen
,
3321 uri
, &uri_out
, destflags
, dname
, bandwidth
, dom_xml
);
3325 /* Begin already started a migration job so we need to cancel it by
3326 * calling Confirm while making sure it doesn't overwrite the error
3328 virErrorPreserveLast(&orig_err
);
3335 /* Did domainMigratePrepare3 change URI? */
3339 virTypedParamsReplaceString(¶ms
, &nparams
,
3340 VIR_MIGRATE_PARAM_URI
,
3342 virErrorPreserveLast(&orig_err
);
3346 virTypedParamsGetString(params
, nparams
,
3347 VIR_MIGRATE_PARAM_URI
, &uri
) <= 0) {
3348 virReportError(VIR_ERR_INTERNAL_ERROR
, "%s",
3349 _("domainMigratePrepare3 did not set uri"));
3350 virErrorPreserveLast(&orig_err
);
3354 if (flags
& VIR_MIGRATE_OFFLINE
) {
3355 VIR_DEBUG("Offline migration, skipping Perform phase");
3356 VIR_FREE(cookieout
);
3362 /* Perform the migration. The driver isn't supposed to return
3363 * until the migration is complete. The src VM should remain
3364 * running, but in paused state until the destination can
3365 * confirm migration completion.
3367 VIR_DEBUG("Perform3 %p uri=%s", domain
->conn
, uri
);
3369 cookiein
= g_steal_pointer(&cookieout
);
3370 cookieinlen
= cookieoutlen
;
3372 /* dconnuri not relevant in non-P2P modes, so left NULL here */
3374 ret
= domain
->conn
->driver
->domainMigratePerform3Params
3375 (domain
, NULL
, params
, nparams
, cookiein
, cookieinlen
,
3376 &cookieout
, &cookieoutlen
, flags
| protection
);
3378 ret
= domain
->conn
->driver
->domainMigratePerform3
3379 (domain
, NULL
, cookiein
, cookieinlen
,
3380 &cookieout
, &cookieoutlen
, NULL
,
3381 uri
, flags
| protection
, dname
, bandwidth
);
3384 /* Perform failed. Make sure Finish doesn't overwrite the error */
3386 virErrorPreserveLast(&orig_err
);
3387 /* Perform failed so we don't need to call confirm to let source know
3388 * about the failure.
3390 notify_source
= false;
3393 /* If Perform returns < 0, then we need to cancel the VM
3394 * startup on the destination
3396 cancelled
= ret
< 0 ? 1 : 0;
3400 * The status code from the source is passed to the destination.
3401 * The dest can cleanup if the source indicated it failed to
3402 * send all migration data. Returns NULL for ddomain if
3403 * the dest was unable to complete migration.
3405 VIR_DEBUG("Finish3 %p ret=%d", dconn
, ret
);
3407 cookiein
= g_steal_pointer(&cookieout
);
3408 cookieinlen
= cookieoutlen
;
3411 if (virTypedParamsGetString(params
, nparams
,
3412 VIR_MIGRATE_PARAM_DEST_NAME
, NULL
) <= 0 &&
3413 virTypedParamsReplaceString(¶ms
, &nparams
,
3414 VIR_MIGRATE_PARAM_DEST_NAME
,
3415 domain
->name
) < 0) {
3418 ddomain
= dconn
->driver
->domainMigrateFinish3Params
3419 (dconn
, params
, nparams
, cookiein
, cookieinlen
,
3420 &cookieout
, &cookieoutlen
, destflags
, cancelled
);
3423 dname
= dname
? dname
: domain
->name
;
3424 ddomain
= dconn
->driver
->domainMigrateFinish3
3425 (dconn
, dname
, cookiein
, cookieinlen
, &cookieout
, &cookieoutlen
,
3426 NULL
, uri
, destflags
, cancelled
);
3431 VIR_ERROR(_("finish step ignored that migration was cancelled"));
3433 /* If Finish reported a useful error, use it instead of the
3434 * original "migration unexpectedly failed" error.
3436 * This is ugly but we can't do better with the APIs we have. We
3437 * only replace the error if Finish was called with cancelled == 1
3438 * and reported a real error (old libvirt would report an error
3439 * from RPC instead of MIGRATE_FINISH_OK), which only happens when
3440 * the domain died on destination. To further reduce a possibility
3441 * of false positives we also check that Perform returned
3442 * VIR_ERR_OPERATION_FAILED.
3445 orig_err
->domain
== VIR_FROM_QEMU
&&
3446 orig_err
->code
== VIR_ERR_OPERATION_FAILED
) {
3447 virErrorPtr err
= virGetLastError();
3449 err
->domain
== VIR_FROM_QEMU
&&
3450 err
->code
!= VIR_ERR_MIGRATE_FINISH_OK
) {
3451 g_clear_pointer(&orig_err
, virFreeError
);
3457 /* If ddomain is NULL, then we were unable to start
3458 * the guest on the target, and must restart on the
3459 * source. There is a small chance that the ddomain
3460 * is NULL due to an RPC failure, in which case
3461 * ddomain could in fact be running on the dest.
3462 * The lock manager plugins should take care of
3463 * safety in this scenario.
3465 cancelled
= ddomain
== NULL
? 1 : 0;
3467 /* If finish3 set an error, and we don't have an earlier
3468 * one we need to preserve it in case confirm3 overwrites
3471 virErrorPreserveLast(&orig_err
);
3475 * If cancelled, then src VM will be restarted, else it will be killed.
3476 * Don't do this if migration failed on source and thus it was already
3479 if (notify_source
) {
3480 VIR_DEBUG("Confirm3 %p ret=%d domain=%p", domain
->conn
, ret
, domain
);
3482 cookiein
= g_steal_pointer(&cookieout
);
3483 cookieinlen
= cookieoutlen
;
3486 ret
= domain
->conn
->driver
->domainMigrateConfirm3Params
3487 (domain
, params
, nparams
, cookiein
, cookieinlen
,
3488 flags
| protection
, cancelled
);
3490 ret
= domain
->conn
->driver
->domainMigrateConfirm3
3491 (domain
, cookiein
, cookieinlen
,
3492 flags
| protection
, cancelled
);
3494 /* If Confirm3 returns -1, there's nothing more we can
3495 * do, but fortunately worst case is that there is a
3496 * domain left in 'paused' state on source.
3499 VIR_WARN("Guest %s probably left in 'paused' state on source",
3505 virErrorRestore(&orig_err
);
3506 virTypedParamsFree(params
, nparams
);
3512 virDomainMigrateVersion3(virDomainPtr domain
,
3513 virConnectPtr dconn
,
3515 unsigned long flags
,
3518 unsigned long bandwidth
)
3520 return virDomainMigrateVersion3Full(domain
, dconn
, xmlin
, dname
, uri
,
3521 bandwidth
, NULL
, 0, false, flags
);
3526 virDomainMigrateVersion3Params(virDomainPtr domain
,
3527 virConnectPtr dconn
,
3528 virTypedParameterPtr params
,
3532 return virDomainMigrateVersion3Full(domain
, dconn
, NULL
, NULL
, NULL
, 0,
3533 params
, nparams
, true, flags
);
3537 virDomainMigrateCheckNotLocal(const char *dconnuri
)
3539 g_autoptr(virURI
) tempuri
= NULL
;
3541 if (!(tempuri
= virURIParse(dconnuri
)))
3545 * If someone migrates explicitly to a unix socket, then they have to know
3546 * what they are doing and it most probably was not a mistake.
3548 if ((tempuri
->server
&& STRPREFIX(tempuri
->server
, "localhost")) ||
3549 (!tempuri
->server
&& !virURICheckUnixSocket(tempuri
))) {
3550 virReportInvalidArg(dconnuri
, "%s",
3551 _("Attempt to migrate guest to the same host"));
3560 virDomainMigrateUnmanagedProto2(virDomainPtr domain
,
3561 const char *dconnuri
,
3562 virTypedParameterPtr params
,
3566 /* uri parameter is added for direct case */
3567 const char *compatParams
[] = { VIR_MIGRATE_PARAM_DEST_NAME
,
3568 VIR_MIGRATE_PARAM_BANDWIDTH
,
3569 VIR_MIGRATE_PARAM_URI
};
3570 const char *uri
= NULL
;
3571 const char *miguri
= NULL
;
3572 const char *dname
= NULL
;
3573 unsigned long long bandwidth
= 0;
3575 if (!virTypedParamsCheck(params
, nparams
, compatParams
,
3576 G_N_ELEMENTS(compatParams
))) {
3577 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
3578 _("Some parameters are not supported by migration protocol 2"));
3582 if (virTypedParamsGetString(params
, nparams
,
3583 VIR_MIGRATE_PARAM_URI
, &miguri
) < 0 ||
3584 virTypedParamsGetString(params
, nparams
,
3585 VIR_MIGRATE_PARAM_DEST_NAME
, &dname
) < 0 ||
3586 virTypedParamsGetULLong(params
, nparams
,
3587 VIR_MIGRATE_PARAM_BANDWIDTH
, &bandwidth
) < 0) {
3591 virCheckNonEmptyOptStringArgReturn(dname
, -1);
3593 if (flags
& VIR_MIGRATE_PEER2PEER
) {
3595 virReportError(VIR_ERR_INTERNAL_ERROR
, "%s",
3596 _("Unable to override peer2peer migration URI"));
3604 return domain
->conn
->driver
->domainMigratePerform
3605 (domain
, NULL
, 0, uri
, flags
, dname
, bandwidth
);
3610 virDomainMigrateUnmanagedProto3(virDomainPtr domain
,
3611 const char *dconnuri
,
3612 virTypedParameterPtr params
,
3616 const char *compatParams
[] = { VIR_MIGRATE_PARAM_URI
,
3617 VIR_MIGRATE_PARAM_DEST_NAME
,
3618 VIR_MIGRATE_PARAM_DEST_XML
,
3619 VIR_MIGRATE_PARAM_BANDWIDTH
};
3620 const char *miguri
= NULL
;
3621 const char *dname
= NULL
;
3622 const char *xmlin
= NULL
;
3623 unsigned long long bandwidth
= 0;
3625 if (!virTypedParamsCheck(params
, nparams
, compatParams
,
3626 G_N_ELEMENTS(compatParams
))) {
3627 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
3628 _("Some parameters are not supported by migration protocol 3"));
3632 if (virTypedParamsGetString(params
, nparams
,
3633 VIR_MIGRATE_PARAM_URI
, &miguri
) < 0 ||
3634 virTypedParamsGetString(params
, nparams
,
3635 VIR_MIGRATE_PARAM_DEST_NAME
, &dname
) < 0 ||
3636 virTypedParamsGetString(params
, nparams
,
3637 VIR_MIGRATE_PARAM_DEST_XML
, &xmlin
) < 0 ||
3638 virTypedParamsGetULLong(params
, nparams
,
3639 VIR_MIGRATE_PARAM_BANDWIDTH
, &bandwidth
) < 0) {
3643 virCheckNonEmptyOptStringArgReturn(dname
, -1);
3645 return domain
->conn
->driver
->domainMigratePerform3
3646 (domain
, xmlin
, NULL
, 0, NULL
, NULL
, dconnuri
,
3647 miguri
, flags
, dname
, bandwidth
);
3652 * In normal migration, the libvirt client coordinates communication
3653 * between the 2 libvirtd instances on source & dest hosts.
3655 * This function encapsulates 2 alternatives to the above case.
3657 * 1. peer-2-peer migration, the libvirt client only talks to the source
3658 * libvirtd instance. The source libvirtd then opens its own
3659 * connection to the destination and coordinates migration itself.
3661 * 2. direct migration, where there is no requirement for a libvirtd instance
3662 * on the dest host. Eg, XenD can talk direct to XenD, so libvirtd on dest
3663 * does not need to be involved at all, or even running.
3666 virDomainMigrateUnmanagedParams(virDomainPtr domain
,
3667 const char *dconnuri
,
3668 virTypedParameterPtr params
,
3674 VIR_DOMAIN_DEBUG(domain
, "dconnuri=%s, params=%p, nparams=%d, flags=0x%x",
3675 NULLSTR(dconnuri
), params
, nparams
, flags
);
3676 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
3678 if ((flags
& VIR_MIGRATE_PEER2PEER
) &&
3679 virDomainMigrateCheckNotLocal(dconnuri
) < 0)
3682 if (flags
& VIR_MIGRATE_PEER2PEER
) {
3683 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
3684 VIR_DRV_FEATURE_MIGRATION_PARAMS
);
3688 VIR_DEBUG("Using migration protocol 3 with extensible parameters");
3689 if (!domain
->conn
->driver
->domainMigratePerform3Params
) {
3690 virReportUnsupportedError();
3693 return domain
->conn
->driver
->domainMigratePerform3Params
3694 (domain
, dconnuri
, params
, nparams
,
3695 NULL
, 0, NULL
, NULL
, flags
);
3699 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
3700 VIR_DRV_FEATURE_MIGRATION_V3
);
3704 VIR_DEBUG("Using migration protocol 3");
3705 if (!domain
->conn
->driver
->domainMigratePerform3
) {
3706 virReportUnsupportedError();
3709 return virDomainMigrateUnmanagedProto3(domain
, dconnuri
,
3710 params
, nparams
, flags
);
3712 VIR_DEBUG("Using migration protocol 2");
3713 if (!domain
->conn
->driver
->domainMigratePerform
) {
3714 virReportUnsupportedError();
3717 return virDomainMigrateUnmanagedProto2(domain
, dconnuri
,
3718 params
, nparams
, flags
);
3724 virDomainMigrateUnmanaged(virDomainPtr domain
,
3728 const char *dconnuri
,
3730 unsigned long long bandwidth
)
3733 virTypedParameterPtr params
= NULL
;
3738 virTypedParamsAddString(¶ms
, &nparams
, &maxparams
,
3739 VIR_MIGRATE_PARAM_URI
, miguri
) < 0)
3742 virTypedParamsAddString(¶ms
, &nparams
, &maxparams
,
3743 VIR_MIGRATE_PARAM_DEST_NAME
, dname
) < 0)
3746 virTypedParamsAddString(¶ms
, &nparams
, &maxparams
,
3747 VIR_MIGRATE_PARAM_DEST_XML
, xmlin
) < 0)
3749 if (virTypedParamsAddULLong(¶ms
, &nparams
, &maxparams
,
3750 VIR_MIGRATE_PARAM_BANDWIDTH
, bandwidth
) < 0)
3753 ret
= virDomainMigrateUnmanagedParams(domain
, dconnuri
, params
,
3757 virTypedParamsFree(params
, nparams
);
3765 * @domain: a domain object
3766 * @dconn: destination host (a connection object)
3767 * @flags: bitwise-OR of virDomainMigrateFlags
3768 * @dname: (optional) rename domain to this at destination
3769 * @uri: (optional) dest hostname/URI as seen from the source host
3770 * @bandwidth: (optional) specify migration bandwidth limit in MiB/s
3772 * Migrate the domain object from its current host to the destination
3773 * host given by dconn (a connection to the destination host).
3775 * This function is similar to virDomainMigrate3, but it only supports a fixed
3776 * set of parameters: @dname corresponds to VIR_MIGRATE_PARAM_DEST_NAME, @uri
3777 * is VIR_MIGRATE_PARAM_URI, and @bandwidth is VIR_MIGRATE_PARAM_BANDWIDTH.
3779 * virDomainFree should be used to free the resources after the
3780 * returned domain object is no longer needed.
3782 * Returns the new domain object if the migration was successful,
3783 * or NULL in case of error. Note that the new domain object
3784 * exists in the scope of the destination connection (dconn).
3789 virDomainMigrate(virDomainPtr domain
,
3790 virConnectPtr dconn
,
3791 unsigned long flags
,
3794 unsigned long bandwidth
)
3796 virDomainPtr ddomain
= NULL
;
3801 VIR_DOMAIN_DEBUG(domain
,
3802 "dconn=%p, flags=0x%lx, dname=%s, uri=%s, bandwidth=%lu",
3803 dconn
, flags
, NULLSTR(dname
), NULLSTR(uri
), bandwidth
);
3805 virResetLastError();
3807 /* First checkout the source */
3808 virCheckDomainReturn(domain
, NULL
);
3809 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
3811 /* Now checkout the destination */
3812 virCheckConnectGoto(dconn
, error
);
3813 virCheckReadOnlyGoto(dconn
->flags
, error
);
3815 virCheckNonEmptyOptStringArgReturn(dname
, NULL
);
3817 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_MIGRATE_NON_SHARED_DISK
,
3818 VIR_MIGRATE_NON_SHARED_INC
,
3821 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_MIGRATE_TUNNELLED
,
3822 VIR_MIGRATE_PARALLEL
,
3825 VIR_REQUIRE_FLAG_GOTO(VIR_MIGRATE_NON_SHARED_SYNCHRONOUS_WRITES
,
3826 VIR_MIGRATE_NON_SHARED_DISK
| VIR_MIGRATE_NON_SHARED_INC
,
3829 if (flags
& VIR_MIGRATE_OFFLINE
) {
3830 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
3831 VIR_DRV_FEATURE_MIGRATION_OFFLINE
);
3834 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
3835 _("offline migration is not supported by the source host"));
3839 rc
= VIR_DRV_SUPPORTS_FEATURE(dconn
->driver
, dconn
,
3840 VIR_DRV_FEATURE_MIGRATION_OFFLINE
);
3843 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
3844 _("offline migration is not supported by the destination host"));
3849 if (flags
& VIR_MIGRATE_PEER2PEER
) {
3850 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
3851 VIR_DRV_FEATURE_MIGRATION_P2P
);
3855 g_autofree
char *dstURI
= NULL
;
3857 dstURI
= virConnectGetURI(dconn
);
3862 VIR_DEBUG("Using peer2peer migration");
3863 if (virDomainMigrateUnmanaged(domain
, NULL
, flags
, dname
,
3864 uri
? uri
: dstURI
, NULL
, bandwidth
) < 0)
3867 ddomain
= virDomainLookupByName(dconn
, dname
? dname
: domain
->name
);
3869 /* This driver does not support peer to peer migration */
3870 virReportUnsupportedError();
3874 /* Change protection requires support only on source side, and
3875 * is only needed in v3 migration, which automatically re-adds
3876 * the flag for just the source side. We mask it out for
3877 * non-peer2peer to allow migration from newer source to an
3878 * older destination that rejects the flag. */
3879 if (flags
& VIR_MIGRATE_CHANGE_PROTECTION
) {
3880 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
3881 VIR_DRV_FEATURE_MIGRATE_CHANGE_PROTECTION
);
3884 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
3885 _("cannot enforce change protection"));
3889 flags
&= ~VIR_MIGRATE_CHANGE_PROTECTION
;
3890 if (flags
& VIR_MIGRATE_TUNNELLED
) {
3891 virReportError(VIR_ERR_OPERATION_INVALID
, "%s",
3892 _("cannot perform tunnelled migration without using peer2peer flag"));
3896 /* Check that migration is supported by both drivers. */
3897 rc_src
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
3898 VIR_DRV_FEATURE_MIGRATION_V3
);
3901 rc_dst
= VIR_DRV_SUPPORTS_FEATURE(dconn
->driver
, dconn
,
3902 VIR_DRV_FEATURE_MIGRATION_V3
);
3905 if (rc_src
&& rc_dst
) {
3906 VIR_DEBUG("Using migration protocol 3");
3907 ddomain
= virDomainMigrateVersion3(domain
, dconn
, NULL
,
3908 flags
, dname
, uri
, bandwidth
);
3912 rc_src
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
3913 VIR_DRV_FEATURE_MIGRATION_V2
);
3916 rc_dst
= VIR_DRV_SUPPORTS_FEATURE(dconn
->driver
, dconn
,
3917 VIR_DRV_FEATURE_MIGRATION_V2
);
3920 if (rc_src
&& rc_dst
) {
3921 VIR_DEBUG("Using migration protocol 2");
3922 ddomain
= virDomainMigrateVersion2(domain
, dconn
, flags
,
3923 dname
, uri
, bandwidth
);
3927 rc_src
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
3928 VIR_DRV_FEATURE_MIGRATION_V1
);
3931 rc_dst
= VIR_DRV_SUPPORTS_FEATURE(dconn
->driver
, dconn
,
3932 VIR_DRV_FEATURE_MIGRATION_V1
);
3935 if (rc_src
&& rc_dst
) {
3936 VIR_DEBUG("Using migration protocol 1");
3937 ddomain
= virDomainMigrateVersion1(domain
, dconn
, flags
,
3938 dname
, uri
, bandwidth
);
3942 /* This driver does not support any migration method */
3943 virReportUnsupportedError();
3948 if (ddomain
== NULL
)
3954 virDispatchError(domain
->conn
);
3960 * virDomainMigrate2:
3961 * @domain: a domain object
3962 * @dconn: destination host (a connection object)
3963 * @flags: bitwise-OR of virDomainMigrateFlags
3964 * @dxml: (optional) XML config for launching guest on target
3965 * @dname: (optional) rename domain to this at destination
3966 * @uri: (optional) dest hostname/URI as seen from the source host
3967 * @bandwidth: (optional) specify migration bandwidth limit in MiB/s
3969 * Migrate the domain object from its current host to the destination
3970 * host given by dconn (a connection to the destination host).
3972 * This function is similar to virDomainMigrate3, but it only supports a fixed
3973 * set of parameters: @dxml corresponds to VIR_MIGRATE_PARAM_DEST_XML, @dname
3974 * is VIR_MIGRATE_PARAM_DEST_NAME, @uri is VIR_MIGRATE_PARAM_URI, and
3975 * @bandwidth is VIR_MIGRATE_PARAM_BANDWIDTH.
3977 * virDomainFree should be used to free the resources after the
3978 * returned domain object is no longer needed.
3980 * Returns the new domain object if the migration was successful,
3981 * or NULL in case of error. Note that the new domain object
3982 * exists in the scope of the destination connection (dconn).
3987 virDomainMigrate2(virDomainPtr domain
,
3988 virConnectPtr dconn
,
3990 unsigned long flags
,
3993 unsigned long bandwidth
)
3995 virDomainPtr ddomain
= NULL
;
4000 VIR_DOMAIN_DEBUG(domain
,
4001 "dconn=%p, flags=0x%lx, dname=%s, uri=%s, bandwidth=%lu",
4002 dconn
, flags
, NULLSTR(dname
), NULLSTR(uri
), bandwidth
);
4004 virResetLastError();
4006 /* First checkout the source */
4007 virCheckDomainReturn(domain
, NULL
);
4008 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
4010 /* Now checkout the destination */
4011 virCheckConnectGoto(dconn
, error
);
4012 virCheckReadOnlyGoto(dconn
->flags
, error
);
4014 virCheckNonEmptyOptStringArgReturn(dname
, NULL
);
4016 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_MIGRATE_NON_SHARED_DISK
,
4017 VIR_MIGRATE_NON_SHARED_INC
,
4020 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_MIGRATE_TUNNELLED
,
4021 VIR_MIGRATE_PARALLEL
,
4024 VIR_REQUIRE_FLAG_GOTO(VIR_MIGRATE_NON_SHARED_SYNCHRONOUS_WRITES
,
4025 VIR_MIGRATE_NON_SHARED_DISK
| VIR_MIGRATE_NON_SHARED_INC
,
4028 if (flags
& VIR_MIGRATE_OFFLINE
) {
4029 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
4030 VIR_DRV_FEATURE_MIGRATION_OFFLINE
);
4033 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
4034 _("offline migration is not supported by the source host"));
4037 rc
= VIR_DRV_SUPPORTS_FEATURE(dconn
->driver
, dconn
,
4038 VIR_DRV_FEATURE_MIGRATION_OFFLINE
);
4041 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
4042 _("offline migration is not supported by the destination host"));
4047 if (flags
& VIR_MIGRATE_PEER2PEER
) {
4048 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
4049 VIR_DRV_FEATURE_MIGRATION_P2P
);
4053 g_autofree
char *dstURI
= virConnectGetURI(dconn
);
4057 VIR_DEBUG("Using peer2peer migration");
4058 if (virDomainMigrateUnmanaged(domain
, dxml
, flags
, dname
,
4059 dstURI
, uri
, bandwidth
) < 0)
4062 ddomain
= virDomainLookupByName(dconn
, dname
? dname
: domain
->name
);
4064 /* This driver does not support peer to peer migration */
4065 virReportUnsupportedError();
4069 /* Change protection requires support only on source side, and
4070 * is only needed in v3 migration, which automatically re-adds
4071 * the flag for just the source side. We mask it out for
4072 * non-peer2peer to allow migration from newer source to an
4073 * older destination that rejects the flag. */
4074 if (flags
& VIR_MIGRATE_CHANGE_PROTECTION
) {
4075 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
4076 VIR_DRV_FEATURE_MIGRATE_CHANGE_PROTECTION
);
4079 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
4080 _("cannot enforce change protection"));
4084 flags
&= ~VIR_MIGRATE_CHANGE_PROTECTION
;
4085 if (flags
& VIR_MIGRATE_TUNNELLED
) {
4086 virReportError(VIR_ERR_OPERATION_INVALID
, "%s",
4087 _("cannot perform tunnelled migration without using peer2peer flag"));
4091 /* Check that migration is supported by both drivers. */
4092 rc_src
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
4093 VIR_DRV_FEATURE_MIGRATION_V3
);
4096 rc_dst
= VIR_DRV_SUPPORTS_FEATURE(dconn
->driver
, dconn
,
4097 VIR_DRV_FEATURE_MIGRATION_V3
);
4100 if (rc_src
&& rc_dst
) {
4101 VIR_DEBUG("Using migration protocol 3");
4102 ddomain
= virDomainMigrateVersion3(domain
, dconn
, dxml
,
4103 flags
, dname
, uri
, bandwidth
);
4107 rc_src
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
4108 VIR_DRV_FEATURE_MIGRATION_V2
);
4111 rc_dst
= VIR_DRV_SUPPORTS_FEATURE(dconn
->driver
, dconn
,
4112 VIR_DRV_FEATURE_MIGRATION_V2
);
4115 if (rc_src
&& rc_dst
) {
4116 VIR_DEBUG("Using migration protocol 2");
4118 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
4119 _("Unable to change target guest XML during migration"));
4122 ddomain
= virDomainMigrateVersion2(domain
, dconn
, flags
,
4123 dname
, uri
, bandwidth
);
4127 rc_src
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
4128 VIR_DRV_FEATURE_MIGRATION_V1
);
4131 rc_dst
= VIR_DRV_SUPPORTS_FEATURE(dconn
->driver
, dconn
,
4132 VIR_DRV_FEATURE_MIGRATION_V1
);
4135 if (rc_src
&& rc_dst
) {
4136 VIR_DEBUG("Using migration protocol 1");
4138 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
4139 _("Unable to change target guest XML during migration"));
4142 ddomain
= virDomainMigrateVersion1(domain
, dconn
, flags
,
4143 dname
, uri
, bandwidth
);
4147 /* This driver does not support any migration method */
4148 virReportUnsupportedError();
4153 if (ddomain
== NULL
)
4159 virDispatchError(domain
->conn
);
4165 * virDomainMigrate3:
4166 * @domain: a domain object
4167 * @dconn: destination host (a connection object)
4168 * @params: (optional) migration parameters
4169 * @nparams: (optional) number of migration parameters in @params
4170 * @flags: bitwise-OR of virDomainMigrateFlags
4172 * Migrate the domain object from its current host to the destination host
4173 * given by dconn (a connection to the destination host).
4175 * See VIR_MIGRATE_PARAM_* and virDomainMigrateFlags for detailed description
4176 * of accepted migration parameters and flags.
4178 * See virDomainMigrateFlags documentation for description of individual flags.
4180 * VIR_MIGRATE_TUNNELLED and VIR_MIGRATE_PEER2PEER are not supported by this
4181 * API, use virDomainMigrateToURI3 instead.
4183 * There are many limitations on migration imposed by the underlying
4184 * technology - for example it may not be possible to migrate between
4185 * different processors even with the same architecture, or between
4186 * different types of hypervisor.
4188 * virDomainFree should be used to free the resources after the
4189 * returned domain object is no longer needed.
4191 * Returns the new domain object if the migration was successful,
4192 * or NULL in case of error. Note that the new domain object
4193 * exists in the scope of the destination connection (dconn).
4198 virDomainMigrate3(virDomainPtr domain
,
4199 virConnectPtr dconn
,
4200 virTypedParameterPtr params
,
4201 unsigned int nparams
,
4204 virDomainPtr ddomain
= NULL
;
4205 const char *compatParams
[] = { VIR_MIGRATE_PARAM_URI
,
4206 VIR_MIGRATE_PARAM_DEST_NAME
,
4207 VIR_MIGRATE_PARAM_DEST_XML
,
4208 VIR_MIGRATE_PARAM_BANDWIDTH
};
4209 const char *uri
= NULL
;
4210 const char *dname
= NULL
;
4211 const char *dxml
= NULL
;
4212 unsigned long long bandwidth
= 0;
4217 VIR_DOMAIN_DEBUG(domain
, "dconn=%p, params=%p, nparms=%u flags=0x%x",
4218 dconn
, params
, nparams
, flags
);
4219 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
4221 virResetLastError();
4223 /* First checkout the source */
4224 virCheckDomainReturn(domain
, NULL
);
4225 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
4227 /* Now checkout the destination */
4228 virCheckReadOnlyGoto(dconn
->flags
, error
);
4230 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_MIGRATE_NON_SHARED_DISK
,
4231 VIR_MIGRATE_NON_SHARED_INC
,
4234 VIR_REQUIRE_FLAG_GOTO(VIR_MIGRATE_NON_SHARED_SYNCHRONOUS_WRITES
,
4235 VIR_MIGRATE_NON_SHARED_DISK
| VIR_MIGRATE_NON_SHARED_INC
,
4238 if (flags
& VIR_MIGRATE_PEER2PEER
) {
4239 virReportInvalidArg(flags
, "%s",
4240 _("use virDomainMigrateToURI3 for peer-to-peer migration"));
4243 if (flags
& VIR_MIGRATE_TUNNELLED
) {
4244 virReportInvalidArg(flags
, "%s",
4245 _("cannot perform tunnelled migration without using peer2peer flag"));
4249 if (virTypedParamsGetString(params
, nparams
,
4250 VIR_MIGRATE_PARAM_URI
, &uri
) < 0 ||
4251 virTypedParamsGetString(params
, nparams
,
4252 VIR_MIGRATE_PARAM_DEST_NAME
, &dname
) < 0 ||
4253 virTypedParamsGetString(params
, nparams
,
4254 VIR_MIGRATE_PARAM_DEST_XML
, &dxml
) < 0 ||
4255 virTypedParamsGetULLong(params
, nparams
,
4256 VIR_MIGRATE_PARAM_BANDWIDTH
, &bandwidth
) < 0) {
4260 virCheckNonEmptyOptStringArgReturn(dname
, NULL
);
4262 if (flags
& VIR_MIGRATE_OFFLINE
) {
4263 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
4264 VIR_DRV_FEATURE_MIGRATION_OFFLINE
);
4267 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
4268 _("offline migration is not supported by the source host"));
4272 rc
= VIR_DRV_SUPPORTS_FEATURE(dconn
->driver
, dconn
,
4273 VIR_DRV_FEATURE_MIGRATION_OFFLINE
);
4276 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
4277 _("offline migration is not supported by the destination host"));
4282 /* Change protection requires support only on source side, and
4283 * is only needed in v3 migration, which automatically re-adds
4284 * the flag for just the source side. We mask it out to allow
4285 * migration from newer source to an older destination that
4286 * rejects the flag. */
4287 if (flags
& VIR_MIGRATE_CHANGE_PROTECTION
) {
4288 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
4289 VIR_DRV_FEATURE_MIGRATE_CHANGE_PROTECTION
);
4292 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
4293 _("cannot enforce change protection"));
4297 flags
&= ~VIR_MIGRATE_CHANGE_PROTECTION
;
4299 /* Prefer extensible API but fall back to older migration APIs if params
4300 * only contains parameters which were supported by the older API. */
4301 rc_src
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
4302 VIR_DRV_FEATURE_MIGRATION_PARAMS
);
4305 rc_dst
= VIR_DRV_SUPPORTS_FEATURE(dconn
->driver
, dconn
,
4306 VIR_DRV_FEATURE_MIGRATION_PARAMS
);
4309 if (rc_src
&& rc_dst
) {
4310 VIR_DEBUG("Using migration protocol 3 with extensible parameters");
4311 ddomain
= virDomainMigrateVersion3Params(domain
, dconn
, params
,
4316 if (!virTypedParamsCheck(params
, nparams
, compatParams
,
4317 G_N_ELEMENTS(compatParams
))) {
4318 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
4319 _("Migration APIs with extensible parameters are not supported but extended parameters were passed"));
4323 rc_src
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
4324 VIR_DRV_FEATURE_MIGRATION_V3
);
4327 rc_dst
= VIR_DRV_SUPPORTS_FEATURE(dconn
->driver
, dconn
,
4328 VIR_DRV_FEATURE_MIGRATION_V3
);
4331 if (rc_src
&& rc_dst
) {
4332 VIR_DEBUG("Using migration protocol 3");
4333 ddomain
= virDomainMigrateVersion3(domain
, dconn
, dxml
, flags
,
4334 dname
, uri
, bandwidth
);
4338 rc_src
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
4339 VIR_DRV_FEATURE_MIGRATION_V2
);
4342 rc_dst
= VIR_DRV_SUPPORTS_FEATURE(dconn
->driver
, dconn
,
4343 VIR_DRV_FEATURE_MIGRATION_V2
);
4346 if (rc_src
&& rc_dst
) {
4347 VIR_DEBUG("Using migration protocol 2");
4349 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
4350 _("Unable to change target guest XML during migration"));
4353 ddomain
= virDomainMigrateVersion2(domain
, dconn
, flags
,
4354 dname
, uri
, bandwidth
);
4358 rc_src
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
4359 VIR_DRV_FEATURE_MIGRATION_V1
);
4362 rc_dst
= VIR_DRV_SUPPORTS_FEATURE(dconn
->driver
, dconn
,
4363 VIR_DRV_FEATURE_MIGRATION_V1
);
4366 if (rc_src
&& rc_dst
) {
4367 VIR_DEBUG("Using migration protocol 1");
4369 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
4370 _("Unable to change target guest XML during migration"));
4373 ddomain
= virDomainMigrateVersion1(domain
, dconn
, flags
,
4374 dname
, uri
, bandwidth
);
4378 /* This driver does not support any migration method */
4379 virReportUnsupportedError();
4383 if (ddomain
== NULL
)
4389 virDispatchError(domain
->conn
);
4395 int virDomainMigrateUnmanagedCheckCompat(virDomainPtr domain
,
4400 VIR_EXCLUSIVE_FLAGS_RET(VIR_MIGRATE_NON_SHARED_DISK
,
4401 VIR_MIGRATE_NON_SHARED_INC
,
4404 VIR_REQUIRE_FLAG_RET(VIR_MIGRATE_NON_SHARED_SYNCHRONOUS_WRITES
,
4405 VIR_MIGRATE_NON_SHARED_DISK
| VIR_MIGRATE_NON_SHARED_INC
,
4408 if (flags
& VIR_MIGRATE_OFFLINE
) {
4409 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
4410 VIR_DRV_FEATURE_MIGRATION_OFFLINE
);
4414 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
4415 _("offline migration is not supported by the source host"));
4420 if (flags
& VIR_MIGRATE_PEER2PEER
) {
4421 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
4422 VIR_DRV_FEATURE_MIGRATION_P2P
);
4426 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
4427 _("p2p migration is not supported by the source host"));
4431 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
4432 VIR_DRV_FEATURE_MIGRATION_DIRECT
);
4435 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
4436 _("direct migration is not supported by the source host"));
4446 * virDomainMigrateToURI:
4447 * @domain: a domain object
4448 * @duri: mandatory URI for the destination host
4449 * @flags: bitwise-OR of virDomainMigrateFlags
4450 * @dname: (optional) rename domain to this at destination
4451 * @bandwidth: (optional) specify migration bandwidth limit in MiB/s
4453 * Migrate the domain object from its current host to the destination
4454 * host given by duri.
4456 * This function is similar to virDomainMigrateToURI3, but it only supports a
4457 * fixed set of parameters: @dname corresponds to VIR_MIGRATE_PARAM_DEST_NAME,
4458 * and @bandwidth corresponds to VIR_MIGRATE_PARAM_BANDWIDTH.
4460 * The operation of this API hinges on the VIR_MIGRATE_PEER2PEER flag.
4462 * If the VIR_MIGRATE_PEER2PEER flag IS set, the @duri parameter must be a
4463 * valid libvirt connection URI, by which the source libvirt driver can connect
4464 * to the destination libvirt. In other words, @duri corresponds to @dconnuri
4465 * of virDomainMigrateToURI3.
4467 * If the VIR_MIGRATE_PEER2PEER flag is NOT set, the @duri parameter takes a
4468 * hypervisor specific URI used to initiate the migration. In this case @duri
4469 * corresponds to VIR_MIGRATE_PARAM_URI of virDomainMigrateToURI3.
4471 * Returns 0 if the migration succeeded, -1 upon error.
4476 virDomainMigrateToURI(virDomainPtr domain
,
4478 unsigned long flags
,
4480 unsigned long bandwidth
)
4482 const char *dconnuri
= NULL
;
4483 const char *miguri
= NULL
;
4485 VIR_DOMAIN_DEBUG(domain
, "duri=%s, flags=0x%lx, dname=%s, bandwidth=%lu",
4486 NULLSTR(duri
), flags
, NULLSTR(dname
), bandwidth
);
4488 virResetLastError();
4490 /* First checkout the source */
4491 virCheckDomainReturn(domain
, -1);
4492 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
4493 virCheckNonNullArgGoto(duri
, error
);
4494 virCheckNonEmptyOptStringArgGoto(dname
, error
);
4496 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_MIGRATE_TUNNELLED
,
4497 VIR_MIGRATE_PARALLEL
,
4500 if (virDomainMigrateUnmanagedCheckCompat(domain
, flags
) < 0)
4503 if (flags
& VIR_MIGRATE_PEER2PEER
)
4508 if (virDomainMigrateUnmanaged(domain
, NULL
, flags
,
4509 dname
, dconnuri
, miguri
, bandwidth
) < 0)
4515 virDispatchError(domain
->conn
);
4521 * virDomainMigrateToURI2:
4522 * @domain: a domain object
4523 * @dconnuri: (optional) URI for target libvirtd if @flags includes VIR_MIGRATE_PEER2PEER
4524 * @miguri: (optional) URI for invoking the migration, not if @flags includs VIR_MIGRATE_TUNNELLED
4525 * @dxml: (optional) XML config for launching guest on target
4526 * @flags: bitwise-OR of virDomainMigrateFlags
4527 * @dname: (optional) rename domain to this at destination
4528 * @bandwidth: (optional) specify migration bandwidth limit in MiB/s
4530 * Migrate the domain object from its current host to the destination
4531 * host given by @dconnuri.
4533 * This function is similar to virDomainMigrateToURI3, but it only supports a
4534 * fixed set of parameters: @miguri corresponds to VIR_MIGRATE_PARAM_URI, @dxml
4535 * is VIR_MIGRATE_PARAM_DEST_XML, @dname is VIR_MIGRATE_PARAM_DEST_NAME, and
4536 * @bandwidth corresponds to VIR_MIGRATE_PARAM_BANDWIDTH.
4538 * The operation of this API hinges on the VIR_MIGRATE_PEER2PEER flag.
4540 * If the VIR_MIGRATE_PEER2PEER flag IS set, the @dconnuri parameter must be a
4541 * valid libvirt connection URI, by which the source libvirt driver can connect
4542 * to the destination libvirt. In other words, @dconnuri has the same semantics
4543 * as in virDomainMigrateToURI3.
4545 * If the VIR_MIGRATE_PEER2PEER flag is NOT set, the @dconnuri must be NULL
4546 * and the @miguri parameter takes a hypervisor specific URI used to initiate
4547 * the migration. In this case @miguri corresponds to VIR_MIGRATE_PARAM_URI of
4548 * virDomainMigrateToURI3.
4550 * Returns 0 if the migration succeeded, -1 upon error.
4555 virDomainMigrateToURI2(virDomainPtr domain
,
4556 const char *dconnuri
,
4559 unsigned long flags
,
4561 unsigned long bandwidth
)
4563 VIR_DOMAIN_DEBUG(domain
, "dconnuri=%s, miguri=%s, dxml=%s, "
4564 "flags=0x%lx, dname=%s, bandwidth=%lu",
4565 NULLSTR(dconnuri
), NULLSTR(miguri
), NULLSTR(dxml
),
4566 flags
, NULLSTR(dname
), bandwidth
);
4568 virResetLastError();
4570 /* First checkout the source */
4571 virCheckDomainReturn(domain
, -1);
4572 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
4574 virCheckNonEmptyOptStringArgGoto(dname
, error
);
4576 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_MIGRATE_TUNNELLED
,
4577 VIR_MIGRATE_PARALLEL
,
4580 if (virDomainMigrateUnmanagedCheckCompat(domain
, flags
) < 0)
4583 if (flags
& VIR_MIGRATE_PEER2PEER
)
4584 virCheckNonNullArgGoto(dconnuri
, error
);
4588 if (virDomainMigrateUnmanaged(domain
, dxml
, flags
,
4589 dname
, dconnuri
, miguri
, bandwidth
) < 0)
4595 virDispatchError(domain
->conn
);
4601 * virDomainMigrateToURI3:
4602 * @domain: a domain object
4603 * @dconnuri: (optional) URI for target libvirtd if @flags includes VIR_MIGRATE_PEER2PEER
4604 * @params: (optional) migration parameters
4605 * @nparams: (optional) number of migration parameters in @params
4606 * @flags: bitwise-OR of virDomainMigrateFlags
4608 * Migrate the domain object from its current host to the destination host
4611 * See VIR_MIGRATE_PARAM_* and virDomainMigrateFlags for detailed description
4612 * of accepted migration parameters and flags.
4614 * The operation of this API hinges on the VIR_MIGRATE_PEER2PEER flag.
4616 * If the VIR_MIGRATE_PEER2PEER flag is set, the @dconnuri parameter must be a
4617 * valid libvirt connection URI, by which the source libvirt daemon can connect
4618 * to the destination libvirt.
4620 * If the VIR_MIGRATE_PEER2PEER flag is NOT set, then @dconnuri must be NULL
4621 * and VIR_MIGRATE_PARAM_URI migration parameter must be filled in with
4622 * hypervisor specific URI used to initiate the migration. The uri_transports
4623 * element of the hypervisor capabilities XML includes supported URI schemes.
4624 * This is called "direct" migration. Not all hypervisors support this mode of
4625 * migration, so if the VIR_MIGRATE_PEER2PEER flag is not set, then it may be
4626 * necessary to use the alternative virDomainMigrate3 API providing an explicit
4627 * virConnectPtr for the destination host.
4629 * There are many limitations on migration imposed by the underlying
4630 * technology - for example it may not be possible to migrate between
4631 * different processors even with the same architecture, or between
4632 * different types of hypervisor.
4634 * Returns 0 if the migration succeeded, -1 upon error.
4639 virDomainMigrateToURI3(virDomainPtr domain
,
4640 const char *dconnuri
,
4641 virTypedParameterPtr params
,
4642 unsigned int nparams
,
4645 VIR_DOMAIN_DEBUG(domain
, "dconnuri=%s, params=%p, nparms=%u flags=0x%x",
4646 NULLSTR(dconnuri
), params
, nparams
, flags
);
4647 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
4649 virResetLastError();
4651 /* First checkout the source */
4652 virCheckDomainReturn(domain
, -1);
4653 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
4655 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_MIGRATE_TUNNELLED
,
4656 VIR_MIGRATE_PARALLEL
,
4659 if (virDomainMigrateUnmanagedCheckCompat(domain
, flags
) < 0)
4662 if (flags
& VIR_MIGRATE_PEER2PEER
)
4663 virCheckNonNullArgGoto(dconnuri
, error
);
4667 if (virDomainMigrateUnmanagedParams(domain
, dconnuri
,
4668 params
, nparams
, flags
) < 0)
4674 virDispatchError(domain
->conn
);
4680 * Not for public use. This function is part of the internal
4681 * implementation of migration in the remote case.
4684 virDomainMigratePrepare(virConnectPtr dconn
,
4689 unsigned long flags
,
4691 unsigned long bandwidth
)
4693 VIR_DEBUG("dconn=%p, cookie=%p, cookielen=%p, uri_in=%s, uri_out=%p, "
4694 "flags=0x%lx, dname=%s, bandwidth=%lu", dconn
, cookie
, cookielen
,
4695 NULLSTR(uri_in
), uri_out
, flags
, NULLSTR(dname
), bandwidth
);
4697 virResetLastError();
4699 virCheckConnectReturn(dconn
, -1);
4700 virCheckReadOnlyGoto(dconn
->flags
, error
);
4701 virCheckNonEmptyOptStringArgGoto(dname
, error
);
4703 if (dconn
->driver
->domainMigratePrepare
) {
4705 ret
= dconn
->driver
->domainMigratePrepare(dconn
, cookie
, cookielen
,
4707 flags
, dname
, bandwidth
);
4713 virReportUnsupportedError();
4716 virDispatchError(dconn
);
4722 * Not for public use. This function is part of the internal
4723 * implementation of migration in the remote case.
4726 virDomainMigratePerform(virDomainPtr domain
,
4730 unsigned long flags
,
4732 unsigned long bandwidth
)
4736 VIR_DOMAIN_DEBUG(domain
, "cookie=%p, cookielen=%d, uri=%s, flags=0x%lx, "
4737 "dname=%s, bandwidth=%lu", cookie
, cookielen
, uri
, flags
,
4738 NULLSTR(dname
), bandwidth
);
4740 virResetLastError();
4742 virCheckDomainReturn(domain
, -1);
4743 conn
= domain
->conn
;
4745 virCheckReadOnlyGoto(conn
->flags
, error
);
4746 virCheckNonEmptyOptStringArgGoto(dname
, error
);
4748 if (conn
->driver
->domainMigratePerform
) {
4750 ret
= conn
->driver
->domainMigratePerform(domain
, cookie
, cookielen
,
4752 flags
, dname
, bandwidth
);
4758 virReportUnsupportedError();
4761 virDispatchError(domain
->conn
);
4767 * Not for public use. This function is part of the internal
4768 * implementation of migration in the remote case.
4771 virDomainMigrateFinish(virConnectPtr dconn
,
4776 unsigned long flags
)
4778 VIR_DEBUG("dconn=%p, dname=%s, cookie=%p, cookielen=%d, uri=%s, "
4779 "flags=0x%lx", dconn
, NULLSTR(dname
), cookie
, cookielen
,
4780 NULLSTR(uri
), flags
);
4782 virResetLastError();
4784 virCheckConnectReturn(dconn
, NULL
);
4785 virCheckReadOnlyGoto(dconn
->flags
, error
);
4786 virCheckNonEmptyOptStringArgGoto(dname
, error
);
4788 if (dconn
->driver
->domainMigrateFinish
) {
4790 ret
= dconn
->driver
->domainMigrateFinish(dconn
, dname
,
4798 virReportUnsupportedError();
4801 virDispatchError(dconn
);
4807 * Not for public use. This function is part of the internal
4808 * implementation of migration in the remote case.
4811 virDomainMigratePrepare2(virConnectPtr dconn
,
4816 unsigned long flags
,
4818 unsigned long bandwidth
,
4819 const char *dom_xml
)
4821 VIR_DEBUG("dconn=%p, cookie=%p, cookielen=%p, uri_in=%s, uri_out=%p,"
4822 "flags=0x%lx, dname=%s, bandwidth=%lu, dom_xml=%s", dconn
,
4823 cookie
, cookielen
, NULLSTR(uri_in
), uri_out
, flags
, NULLSTR(dname
),
4824 bandwidth
, NULLSTR(dom_xml
));
4826 virResetLastError();
4828 virCheckConnectReturn(dconn
, -1);
4829 virCheckReadOnlyGoto(dconn
->flags
, error
);
4830 virCheckNonEmptyOptStringArgGoto(dname
, error
);
4832 if (dconn
->driver
->domainMigratePrepare2
) {
4834 ret
= dconn
->driver
->domainMigratePrepare2(dconn
, cookie
, cookielen
,
4836 flags
, dname
, bandwidth
,
4843 virReportUnsupportedError();
4846 virDispatchError(dconn
);
4852 * Not for public use. This function is part of the internal
4853 * implementation of migration in the remote case.
4856 virDomainMigrateFinish2(virConnectPtr dconn
,
4861 unsigned long flags
,
4864 VIR_DEBUG("dconn=%p, dname=%s, cookie=%p, cookielen=%d, uri=%s, "
4865 "flags=0x%lx, retcode=%d", dconn
, NULLSTR(dname
), cookie
,
4866 cookielen
, NULLSTR(uri
), flags
, retcode
);
4868 virResetLastError();
4870 virCheckConnectReturn(dconn
, NULL
);
4871 virCheckReadOnlyGoto(dconn
->flags
, error
);
4872 virCheckNonEmptyOptStringArgGoto(dname
, error
);
4874 if (dconn
->driver
->domainMigrateFinish2
) {
4876 ret
= dconn
->driver
->domainMigrateFinish2(dconn
, dname
,
4880 if (!ret
&& !retcode
)
4885 virReportUnsupportedError();
4888 virDispatchError(dconn
);
4894 * Not for public use. This function is part of the internal
4895 * implementation of migration in the remote case.
4898 virDomainMigratePrepareTunnel(virConnectPtr conn
,
4900 unsigned long flags
,
4902 unsigned long bandwidth
,
4903 const char *dom_xml
)
4905 VIR_DEBUG("conn=%p, stream=%p, flags=0x%lx, dname=%s, "
4906 "bandwidth=%lu, dom_xml=%s", conn
, st
, flags
,
4907 NULLSTR(dname
), bandwidth
, NULLSTR(dom_xml
));
4909 virResetLastError();
4911 virCheckConnectReturn(conn
, -1);
4912 virCheckReadOnlyGoto(conn
->flags
, error
);
4913 virCheckNonEmptyOptStringArgGoto(dname
, error
);
4915 if (conn
!= st
->conn
) {
4916 virReportInvalidArg(conn
, "%s",
4917 _("conn must match stream connection"));
4921 if (conn
->driver
->domainMigratePrepareTunnel
) {
4922 int rv
= conn
->driver
->domainMigratePrepareTunnel(conn
, st
,
4924 bandwidth
, dom_xml
);
4930 virReportUnsupportedError();
4933 virDispatchError(conn
);
4939 * Not for public use. This function is part of the internal
4940 * implementation of migration in the remote case.
4943 virDomainMigrateBegin3(virDomainPtr domain
,
4947 unsigned long flags
,
4949 unsigned long bandwidth
)
4953 VIR_DOMAIN_DEBUG(domain
, "xmlin=%s cookieout=%p, cookieoutlen=%p, "
4954 "flags=0x%lx, dname=%s, bandwidth=%lu",
4955 NULLSTR(xmlin
), cookieout
, cookieoutlen
, flags
,
4956 NULLSTR(dname
), bandwidth
);
4958 virResetLastError();
4960 virCheckDomainReturn(domain
, NULL
);
4961 conn
= domain
->conn
;
4963 virCheckReadOnlyGoto(conn
->flags
, error
);
4964 virCheckNonEmptyOptStringArgGoto(dname
, error
);
4966 if (conn
->driver
->domainMigrateBegin3
) {
4968 xml
= conn
->driver
->domainMigrateBegin3(domain
, xmlin
,
4969 cookieout
, cookieoutlen
,
4970 flags
, dname
, bandwidth
);
4971 VIR_DEBUG("xml %s", NULLSTR(xml
));
4977 virReportUnsupportedError();
4980 virDispatchError(domain
->conn
);
4986 * Not for public use. This function is part of the internal
4987 * implementation of migration in the remote case.
4990 virDomainMigratePrepare3(virConnectPtr dconn
,
4991 const char *cookiein
,
4997 unsigned long flags
,
4999 unsigned long bandwidth
,
5000 const char *dom_xml
)
5002 VIR_DEBUG("dconn=%p, cookiein=%p, cookieinlen=%d, cookieout=%p, "
5003 "cookieoutlen=%p, uri_in=%s, uri_out=%p, flags=0x%lx, dname=%s, "
5004 "bandwidth=%lu, dom_xml=%s",
5005 dconn
, cookiein
, cookieinlen
, cookieout
, cookieoutlen
, NULLSTR(uri_in
),
5006 uri_out
, flags
, NULLSTR(dname
), bandwidth
, NULLSTR(dom_xml
));
5008 virResetLastError();
5010 virCheckConnectReturn(dconn
, -1);
5011 virCheckReadOnlyGoto(dconn
->flags
, error
);
5012 virCheckNonEmptyOptStringArgGoto(dname
, error
);
5014 if (dconn
->driver
->domainMigratePrepare3
) {
5016 ret
= dconn
->driver
->domainMigratePrepare3(dconn
,
5017 cookiein
, cookieinlen
,
5018 cookieout
, cookieoutlen
,
5020 flags
, dname
, bandwidth
,
5027 virReportUnsupportedError();
5030 virDispatchError(dconn
);
5036 * Not for public use. This function is part of the internal
5037 * implementation of migration in the remote case.
5040 virDomainMigratePrepareTunnel3(virConnectPtr conn
,
5042 const char *cookiein
,
5046 unsigned long flags
,
5048 unsigned long bandwidth
,
5049 const char *dom_xml
)
5051 VIR_DEBUG("conn=%p, stream=%p, cookiein=%p, cookieinlen=%d, cookieout=%p, "
5052 "cookieoutlen=%p, flags=0x%lx, dname=%s, bandwidth=%lu, "
5054 conn
, st
, cookiein
, cookieinlen
, cookieout
, cookieoutlen
, flags
,
5055 NULLSTR(dname
), bandwidth
, NULLSTR(dom_xml
));
5057 virResetLastError();
5059 virCheckConnectReturn(conn
, -1);
5060 virCheckReadOnlyGoto(conn
->flags
, error
);
5061 virCheckNonEmptyOptStringArgGoto(dname
, error
);
5063 if (conn
!= st
->conn
) {
5064 virReportInvalidArg(conn
, "%s",
5065 _("conn must match stream connection"));
5069 if (conn
->driver
->domainMigratePrepareTunnel3
) {
5070 int rv
= conn
->driver
->domainMigratePrepareTunnel3(conn
, st
,
5071 cookiein
, cookieinlen
,
5072 cookieout
, cookieoutlen
,
5074 bandwidth
, dom_xml
);
5080 virReportUnsupportedError();
5083 virDispatchError(conn
);
5089 * Not for public use. This function is part of the internal
5090 * implementation of migration in the remote case.
5093 virDomainMigratePerform3(virDomainPtr domain
,
5095 const char *cookiein
,
5099 const char *dconnuri
,
5101 unsigned long flags
,
5103 unsigned long bandwidth
)
5107 VIR_DOMAIN_DEBUG(domain
, "xmlin=%s cookiein=%p, cookieinlen=%d, "
5108 "cookieout=%p, cookieoutlen=%p, dconnuri=%s, "
5109 "uri=%s, flags=0x%lx, dname=%s, bandwidth=%lu",
5110 NULLSTR(xmlin
), cookiein
, cookieinlen
,
5111 cookieout
, cookieoutlen
, NULLSTR(dconnuri
),
5112 NULLSTR(uri
), flags
, NULLSTR(dname
), bandwidth
);
5114 virResetLastError();
5116 virCheckDomainReturn(domain
, -1);
5117 conn
= domain
->conn
;
5119 virCheckReadOnlyGoto(conn
->flags
, error
);
5120 virCheckNonEmptyOptStringArgGoto(dname
, error
);
5122 if (conn
->driver
->domainMigratePerform3
) {
5124 ret
= conn
->driver
->domainMigratePerform3(domain
, xmlin
,
5125 cookiein
, cookieinlen
,
5126 cookieout
, cookieoutlen
,
5128 flags
, dname
, bandwidth
);
5134 virReportUnsupportedError();
5137 virDispatchError(domain
->conn
);
5143 * Not for public use. This function is part of the internal
5144 * implementation of migration in the remote case.
5147 virDomainMigrateFinish3(virConnectPtr dconn
,
5149 const char *cookiein
,
5153 const char *dconnuri
,
5155 unsigned long flags
,
5158 VIR_DEBUG("dconn=%p, dname=%s, cookiein=%p, cookieinlen=%d, cookieout=%p,"
5159 "cookieoutlen=%p, dconnuri=%s, uri=%s, flags=0x%lx, retcode=%d",
5160 dconn
, NULLSTR(dname
), cookiein
, cookieinlen
, cookieout
,
5161 cookieoutlen
, NULLSTR(dconnuri
), NULLSTR(uri
), flags
, cancelled
);
5163 virResetLastError();
5165 virCheckConnectReturn(dconn
, NULL
);
5166 virCheckReadOnlyGoto(dconn
->flags
, error
);
5167 virCheckNonEmptyOptStringArgGoto(dname
, error
);
5169 if (dconn
->driver
->domainMigrateFinish3
) {
5171 ret
= dconn
->driver
->domainMigrateFinish3(dconn
, dname
,
5172 cookiein
, cookieinlen
,
5173 cookieout
, cookieoutlen
,
5174 dconnuri
, uri
, flags
,
5176 if (!ret
&& !cancelled
)
5181 virReportUnsupportedError();
5184 virDispatchError(dconn
);
5190 * Not for public use. This function is part of the internal
5191 * implementation of migration in the remote case.
5194 virDomainMigrateConfirm3(virDomainPtr domain
,
5195 const char *cookiein
,
5197 unsigned long flags
,
5202 VIR_DOMAIN_DEBUG(domain
,
5203 "cookiein=%p, cookieinlen=%d, flags=0x%lx, cancelled=%d",
5204 cookiein
, cookieinlen
, flags
, cancelled
);
5206 virResetLastError();
5208 virCheckDomainReturn(domain
, -1);
5209 conn
= domain
->conn
;
5211 virCheckReadOnlyGoto(conn
->flags
, error
);
5213 if (conn
->driver
->domainMigrateConfirm3
) {
5215 ret
= conn
->driver
->domainMigrateConfirm3(domain
,
5216 cookiein
, cookieinlen
,
5223 virReportUnsupportedError();
5226 virDispatchError(domain
->conn
);
5232 * Not for public use. This function is part of the internal
5233 * implementation of migration in the remote case.
5236 virDomainMigrateBegin3Params(virDomainPtr domain
,
5237 virTypedParameterPtr params
,
5244 const char *dname
= NULL
;
5246 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%d, "
5247 "cookieout=%p, cookieoutlen=%p, flags=0x%x",
5248 params
, nparams
, cookieout
, cookieoutlen
, flags
);
5249 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
5251 virResetLastError();
5253 virCheckDomainReturn(domain
, NULL
);
5254 conn
= domain
->conn
;
5256 virCheckReadOnlyGoto(conn
->flags
, error
);
5258 if (virTypedParamsGetString(params
, nparams
,
5259 VIR_MIGRATE_PARAM_DEST_NAME
, &dname
) < 0)
5262 virCheckNonEmptyOptStringArgGoto(dname
, error
);
5264 if (conn
->driver
->domainMigrateBegin3Params
) {
5266 xml
= conn
->driver
->domainMigrateBegin3Params(domain
, params
, nparams
,
5267 cookieout
, cookieoutlen
,
5269 VIR_DEBUG("xml %s", NULLSTR(xml
));
5275 virReportUnsupportedError();
5278 virDispatchError(domain
->conn
);
5284 * Not for public use. This function is part of the internal
5285 * implementation of migration in the remote case.
5288 virDomainMigratePrepare3Params(virConnectPtr dconn
,
5289 virTypedParameterPtr params
,
5291 const char *cookiein
,
5298 const char *dname
= NULL
;
5300 VIR_DEBUG("dconn=%p, params=%p, nparams=%d, cookiein=%p, cookieinlen=%d, "
5301 "cookieout=%p, cookieoutlen=%p, uri_out=%p, flags=0x%x",
5302 dconn
, params
, nparams
, cookiein
, cookieinlen
,
5303 cookieout
, cookieoutlen
, uri_out
, flags
);
5304 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
5306 virResetLastError();
5308 virCheckConnectReturn(dconn
, -1);
5309 virCheckReadOnlyGoto(dconn
->flags
, error
);
5311 if (virTypedParamsGetString(params
, nparams
,
5312 VIR_MIGRATE_PARAM_DEST_NAME
, &dname
) < 0)
5315 virCheckNonEmptyOptStringArgGoto(dname
, error
);
5317 if (dconn
->driver
->domainMigratePrepare3Params
) {
5319 ret
= dconn
->driver
->domainMigratePrepare3Params(dconn
, params
, nparams
,
5320 cookiein
, cookieinlen
,
5321 cookieout
, cookieoutlen
,
5328 virReportUnsupportedError();
5331 virDispatchError(dconn
);
5337 * Not for public use. This function is part of the internal
5338 * implementation of migration in the remote case.
5341 virDomainMigratePrepareTunnel3Params(virConnectPtr conn
,
5343 virTypedParameterPtr params
,
5345 const char *cookiein
,
5351 const char *dname
= NULL
;
5353 VIR_DEBUG("conn=%p, stream=%p, params=%p, nparams=%d, cookiein=%p, "
5354 "cookieinlen=%d, cookieout=%p, cookieoutlen=%p, flags=0x%x",
5355 conn
, st
, params
, nparams
, cookiein
, cookieinlen
,
5356 cookieout
, cookieoutlen
, flags
);
5357 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
5359 virResetLastError();
5361 virCheckConnectReturn(conn
, -1);
5362 virCheckReadOnlyGoto(conn
->flags
, error
);
5364 if (conn
!= st
->conn
) {
5365 virReportInvalidArg(conn
, "%s",
5366 _("conn must match stream connection"));
5370 if (virTypedParamsGetString(params
, nparams
,
5371 VIR_MIGRATE_PARAM_DEST_NAME
, &dname
) < 0)
5374 virCheckNonEmptyOptStringArgGoto(dname
, error
);
5376 if (conn
->driver
->domainMigratePrepareTunnel3Params
) {
5378 rv
= conn
->driver
->domainMigratePrepareTunnel3Params(
5379 conn
, st
, params
, nparams
, cookiein
, cookieinlen
,
5380 cookieout
, cookieoutlen
, flags
);
5386 virReportUnsupportedError();
5389 virDispatchError(conn
);
5395 * Not for public use. This function is part of the internal
5396 * implementation of migration in the remote case.
5399 virDomainMigratePerform3Params(virDomainPtr domain
,
5400 const char *dconnuri
,
5401 virTypedParameterPtr params
,
5403 const char *cookiein
,
5410 const char *dname
= NULL
;
5412 VIR_DOMAIN_DEBUG(domain
, "dconnuri=%s, params=%p, nparams=%d, cookiein=%p, "
5413 "cookieinlen=%d, cookieout=%p, cookieoutlen=%p, flags=0x%x",
5414 NULLSTR(dconnuri
), params
, nparams
, cookiein
,
5415 cookieinlen
, cookieout
, cookieoutlen
, flags
);
5416 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
5418 virResetLastError();
5420 virCheckDomainReturn(domain
, -1);
5421 conn
= domain
->conn
;
5423 virCheckReadOnlyGoto(conn
->flags
, error
);
5425 if (virTypedParamsGetString(params
, nparams
,
5426 VIR_MIGRATE_PARAM_DEST_NAME
, &dname
) < 0)
5429 virCheckNonEmptyOptStringArgGoto(dname
, error
);
5431 if (conn
->driver
->domainMigratePerform3Params
) {
5433 ret
= conn
->driver
->domainMigratePerform3Params(
5434 domain
, dconnuri
, params
, nparams
, cookiein
, cookieinlen
,
5435 cookieout
, cookieoutlen
, flags
);
5441 virReportUnsupportedError();
5444 virDispatchError(domain
->conn
);
5450 * Not for public use. This function is part of the internal
5451 * implementation of migration in the remote case.
5454 virDomainMigrateFinish3Params(virConnectPtr dconn
,
5455 virTypedParameterPtr params
,
5457 const char *cookiein
,
5464 const char *dname
= NULL
;
5466 VIR_DEBUG("dconn=%p, params=%p, nparams=%d, cookiein=%p, cookieinlen=%d, "
5467 "cookieout=%p, cookieoutlen=%p, flags=0x%x, cancelled=%d",
5468 dconn
, params
, nparams
, cookiein
, cookieinlen
, cookieout
,
5469 cookieoutlen
, flags
, cancelled
);
5470 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
5472 virResetLastError();
5474 virCheckConnectReturn(dconn
, NULL
);
5475 virCheckReadOnlyGoto(dconn
->flags
, error
);
5477 if (virTypedParamsGetString(params
, nparams
,
5478 VIR_MIGRATE_PARAM_DEST_NAME
, &dname
) < 0)
5481 virCheckNonEmptyOptStringArgGoto(dname
, error
);
5483 if (dconn
->driver
->domainMigrateFinish3Params
) {
5485 ret
= dconn
->driver
->domainMigrateFinish3Params(
5486 dconn
, params
, nparams
, cookiein
, cookieinlen
,
5487 cookieout
, cookieoutlen
, flags
, cancelled
);
5488 if (!ret
&& !cancelled
)
5493 virReportUnsupportedError();
5496 virDispatchError(dconn
);
5502 * Not for public use. This function is part of the internal
5503 * implementation of migration in the remote case.
5506 virDomainMigrateConfirm3Params(virDomainPtr domain
,
5507 virTypedParameterPtr params
,
5509 const char *cookiein
,
5515 const char *dname
= NULL
;
5517 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%d, cookiein=%p, "
5518 "cookieinlen=%d, flags=0x%x, cancelled=%d",
5519 params
, nparams
, cookiein
, cookieinlen
, flags
, cancelled
);
5520 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
5522 virResetLastError();
5524 virCheckDomainReturn(domain
, -1);
5525 conn
= domain
->conn
;
5527 virCheckReadOnlyGoto(conn
->flags
, error
);
5529 if (virTypedParamsGetString(params
, nparams
,
5530 VIR_MIGRATE_PARAM_DEST_NAME
, &dname
) < 0)
5533 virCheckNonEmptyOptStringArgGoto(dname
, error
);
5535 if (conn
->driver
->domainMigrateConfirm3Params
) {
5537 ret
= conn
->driver
->domainMigrateConfirm3Params(
5538 domain
, params
, nparams
,
5539 cookiein
, cookieinlen
, flags
, cancelled
);
5545 virReportUnsupportedError();
5548 virDispatchError(domain
->conn
);
5554 * virDomainGetSchedulerType:
5555 * @domain: pointer to domain object
5556 * @nparams: pointer to number of scheduler parameters, can be NULL
5559 * Get the scheduler type and the number of scheduler parameters.
5561 * Returns NULL in case of error. The caller must free the returned string.
5566 virDomainGetSchedulerType(virDomainPtr domain
, int *nparams
)
5571 VIR_DOMAIN_DEBUG(domain
, "nparams=%p", nparams
);
5573 virResetLastError();
5575 virCheckDomainReturn(domain
, NULL
);
5576 conn
= domain
->conn
;
5578 if (conn
->driver
->domainGetSchedulerType
) {
5579 schedtype
= conn
->driver
->domainGetSchedulerType(domain
, nparams
);
5585 virReportUnsupportedError();
5588 virDispatchError(domain
->conn
);
5594 * virDomainGetSchedulerParameters:
5595 * @domain: pointer to domain object
5596 * @params: pointer to scheduler parameter objects
5598 * @nparams: pointer to number of scheduler parameter objects
5599 * (this value should generally be as large as the returned value
5600 * nparams of virDomainGetSchedulerType()); input and output
5602 * Get all scheduler parameters. On input, @nparams gives the size of the
5603 * @params array; on output, @nparams gives how many slots were filled
5604 * with parameter information, which might be less but will not exceed
5605 * the input value. @nparams cannot be 0.
5607 * It is hypervisor specific whether this returns the live or
5608 * persistent state; for more control, use
5609 * virDomainGetSchedulerParametersFlags().
5611 * Returns -1 in case of error, 0 in case of success.
5616 virDomainGetSchedulerParameters(virDomainPtr domain
,
5617 virTypedParameterPtr params
, int *nparams
)
5621 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%p", params
, nparams
);
5623 virResetLastError();
5625 virCheckDomainReturn(domain
, -1);
5627 virCheckNonNullArgGoto(params
, error
);
5628 virCheckNonNullArgGoto(nparams
, error
);
5629 virCheckPositiveArgGoto(*nparams
, error
);
5631 conn
= domain
->conn
;
5633 if (conn
->driver
->domainGetSchedulerParameters
) {
5635 ret
= conn
->driver
->domainGetSchedulerParameters(domain
, params
, nparams
);
5641 virReportUnsupportedError();
5644 virDispatchError(domain
->conn
);
5650 * virDomainGetSchedulerParametersFlags:
5651 * @domain: pointer to domain object
5652 * @params: pointer to scheduler parameter object
5654 * @nparams: pointer to number of scheduler parameter
5655 * (this value should be same than the returned value
5656 * nparams of virDomainGetSchedulerType()); input and output
5657 * @flags: bitwise-OR of virDomainModificationImpact and virTypedParameterFlags
5659 * Get all scheduler parameters. On input, @nparams gives the size of the
5660 * @params array; on output, @nparams gives how many slots were filled
5661 * with parameter information, which might be less but will not exceed
5662 * the input value. @nparams cannot be 0.
5664 * The value of @flags can be exactly VIR_DOMAIN_AFFECT_CURRENT,
5665 * VIR_DOMAIN_AFFECT_LIVE, or VIR_DOMAIN_AFFECT_CONFIG.
5667 * Here is a sample code snippet:
5669 * char *ret = virDomainGetSchedulerType(dom, &nparams);
5670 * if (ret && nparams != 0) {
5671 * if ((params = malloc(sizeof(*params) * nparams)) == NULL)
5673 * memset(params, 0, sizeof(*params) * nparams);
5674 * if (virDomainGetSchedulerParametersFlags(dom, params, &nparams, 0))
5678 * Returns -1 in case of error, 0 in case of success.
5683 virDomainGetSchedulerParametersFlags(virDomainPtr domain
,
5684 virTypedParameterPtr params
, int *nparams
,
5690 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%p, flags=0x%x",
5691 params
, nparams
, flags
);
5693 virResetLastError();
5695 virCheckDomainReturn(domain
, -1);
5697 virCheckNonNullArgGoto(params
, error
);
5698 virCheckNonNullArgGoto(nparams
, error
);
5699 virCheckPositiveArgGoto(*nparams
, error
);
5701 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
5702 VIR_DRV_FEATURE_TYPED_PARAM_STRING
);
5706 flags
|= VIR_TYPED_PARAM_STRING_OKAY
;
5708 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_AFFECT_LIVE
,
5709 VIR_DOMAIN_AFFECT_CONFIG
,
5712 conn
= domain
->conn
;
5714 if (conn
->driver
->domainGetSchedulerParametersFlags
) {
5716 ret
= conn
->driver
->domainGetSchedulerParametersFlags(domain
, params
,
5723 virReportUnsupportedError();
5726 virDispatchError(domain
->conn
);
5732 * virDomainSetSchedulerParameters:
5733 * @domain: pointer to domain object
5734 * @params: pointer to scheduler parameter objects
5735 * @nparams: number of scheduler parameter objects
5736 * (this value can be the same or less than the returned value
5737 * nparams of virDomainGetSchedulerType)
5739 * Change all or a subset or the scheduler parameters. It is
5740 * hypervisor-specific whether this sets live, persistent, or both
5741 * settings; for more control, use
5742 * virDomainSetSchedulerParametersFlags.
5744 * Returns -1 in case of error, 0 in case of success.
5749 virDomainSetSchedulerParameters(virDomainPtr domain
,
5750 virTypedParameterPtr params
, int nparams
)
5754 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%d", params
, nparams
);
5755 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
5757 virResetLastError();
5759 virCheckDomainReturn(domain
, -1);
5760 conn
= domain
->conn
;
5762 virCheckReadOnlyGoto(conn
->flags
, error
);
5763 virCheckNonNullArgGoto(params
, error
);
5764 virCheckNonNegativeArgGoto(nparams
, error
);
5766 if (virTypedParameterValidateSet(conn
, params
, nparams
) < 0)
5769 if (conn
->driver
->domainSetSchedulerParameters
) {
5771 ret
= conn
->driver
->domainSetSchedulerParameters(domain
, params
, nparams
);
5777 virReportUnsupportedError();
5780 virDispatchError(domain
->conn
);
5786 * virDomainSetSchedulerParametersFlags:
5787 * @domain: pointer to domain object
5788 * @params: pointer to scheduler parameter objects
5789 * @nparams: number of scheduler parameter objects
5790 * (this value can be the same or less than the returned value
5791 * nparams of virDomainGetSchedulerType)
5792 * @flags: bitwise-OR of virDomainModificationImpact
5794 * Change a subset or all scheduler parameters. The value of @flags
5795 * should be either VIR_DOMAIN_AFFECT_CURRENT, or a bitwise-or of
5796 * values from VIR_DOMAIN_AFFECT_LIVE and
5797 * VIR_DOMAIN_AFFECT_CURRENT, although hypervisors vary in which
5798 * flags are supported.
5800 * Returns -1 in case of error, 0 in case of success.
5805 virDomainSetSchedulerParametersFlags(virDomainPtr domain
,
5806 virTypedParameterPtr params
,
5812 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%d, flags=0x%x",
5813 params
, nparams
, flags
);
5814 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
5816 virResetLastError();
5818 virCheckDomainReturn(domain
, -1);
5819 conn
= domain
->conn
;
5821 virCheckReadOnlyGoto(conn
->flags
, error
);
5822 virCheckNonNullArgGoto(params
, error
);
5823 virCheckNonNegativeArgGoto(nparams
, error
);
5825 if (virTypedParameterValidateSet(conn
, params
, nparams
) < 0)
5828 if (conn
->driver
->domainSetSchedulerParametersFlags
) {
5830 ret
= conn
->driver
->domainSetSchedulerParametersFlags(domain
,
5839 virReportUnsupportedError();
5842 virDispatchError(domain
->conn
);
5848 * virDomainBlockStats:
5849 * @dom: pointer to the domain object
5850 * @disk: path to the block device, or device shorthand
5851 * @stats: block device stats (returned)
5852 * @size: size of stats structure
5854 * This function returns block device (disk) stats for block
5855 * devices attached to the domain.
5857 * The @disk parameter is either the device target shorthand (the
5858 * <target dev='...'/> sub-element, such as "vda"), or (since 0.9.8)
5859 * an unambiguous source name of the block device (the <source
5860 * file='...'/> sub-element, such as "/path/to/image"). Valid names
5861 * can be found by calling virDomainGetXMLDesc() and inspecting
5862 * elements within //domain/devices/disk. Some drivers might also
5863 * accept the empty string for the @disk parameter, and then yield
5864 * summary stats for the entire domain.
5866 * Domains may have more than one block device. To get stats for
5867 * each you should make multiple calls to this function.
5869 * Individual fields within the stats structure may be returned
5870 * as -1, which indicates that the hypervisor does not support
5871 * that particular statistic.
5873 * Returns: 0 in case of success or -1 in case of failure.
5878 virDomainBlockStats(virDomainPtr dom
, const char *disk
,
5879 virDomainBlockStatsPtr stats
, size_t size
)
5882 virDomainBlockStatsStruct stats2
= { -1, -1, -1, -1, -1 };
5884 VIR_DOMAIN_DEBUG(dom
, "disk=%s, stats=%p, size=%zi", disk
, stats
, size
);
5886 virResetLastError();
5888 virCheckDomainReturn(dom
, -1);
5889 virCheckNonNullArgGoto(disk
, error
);
5890 virCheckNonNullArgGoto(stats
, error
);
5891 if (size
> sizeof(stats2
)) {
5892 virReportInvalidArg(size
,
5893 _("size must not exceed %1$zu"),
5899 if (conn
->driver
->domainBlockStats
) {
5900 if (conn
->driver
->domainBlockStats(dom
, disk
, &stats2
) == -1)
5903 memcpy(stats
, &stats2
, size
);
5907 virReportUnsupportedError();
5910 virDispatchError(dom
->conn
);
5916 * virDomainBlockStatsFlags:
5917 * @dom: pointer to domain object
5918 * @disk: path to the block device, or device shorthand
5919 * @params: pointer to block stats parameter object
5920 * (return value, allocated by the caller)
5921 * @nparams: pointer to number of block stats; input and output
5922 * @flags: bitwise-OR of virTypedParameterFlags
5924 * This function is to get block stats parameters for block
5925 * devices attached to the domain.
5927 * The @disk parameter is either the device target shorthand (the
5928 * <target dev='...'/> sub-element, such as "vda"), or (since 0.9.8)
5929 * an unambiguous source name of the block device (the <source
5930 * file='...'/> sub-element, such as "/path/to/image"). Valid names
5931 * can be found by calling virDomainGetXMLDesc() and inspecting
5932 * elements within //domain/devices/disk. Some drivers might also
5933 * accept the empty string for the @disk parameter, and then yield
5934 * summary stats for the entire domain.
5936 * Domains may have more than one block device. To get stats for
5937 * each you should make multiple calls to this function.
5939 * On input, @nparams gives the size of the @params array; on output,
5940 * @nparams gives how many slots were filled with parameter
5941 * information, which might be less but will not exceed the input
5944 * As a special case, calling with @params as NULL and @nparams as 0 on
5945 * input will cause @nparams on output to contain the number of parameters
5946 * supported by the hypervisor. (Note that block devices of different types
5947 * might support different parameters, so it might be necessary to compute
5948 * @nparams for each block device). The caller should then allocate @params
5949 * array, i.e. (sizeof(@virTypedParameter) * @nparams) bytes and call the API
5950 * again. See virDomainGetMemoryParameters() for more details.
5952 * Returns -1 in case of error, 0 in case of success.
5957 virDomainBlockStatsFlags(virDomainPtr dom
,
5959 virTypedParameterPtr params
,
5966 VIR_DOMAIN_DEBUG(dom
, "disk=%s, params=%p, nparams=%d, flags=0x%x",
5967 disk
, params
, nparams
? *nparams
: -1, flags
);
5969 virResetLastError();
5971 virCheckDomainReturn(dom
, -1);
5972 virCheckNonNullArgGoto(disk
, error
);
5973 virCheckNonNullArgGoto(nparams
, error
);
5974 virCheckNonNegativeArgGoto(*nparams
, error
);
5976 virCheckNonNullArgGoto(params
, error
);
5978 rc
= VIR_DRV_SUPPORTS_FEATURE(dom
->conn
->driver
, dom
->conn
,
5979 VIR_DRV_FEATURE_TYPED_PARAM_STRING
);
5983 flags
|= VIR_TYPED_PARAM_STRING_OKAY
;
5986 if (conn
->driver
->domainBlockStatsFlags
) {
5988 ret
= conn
->driver
->domainBlockStatsFlags(dom
, disk
, params
, nparams
, flags
);
5993 virReportUnsupportedError();
5996 virDispatchError(dom
->conn
);
6002 * virDomainInterfaceStats:
6003 * @dom: pointer to the domain object
6004 * @device: the interface name or MAC address
6005 * @stats: network interface stats (returned)
6006 * @size: size of stats structure
6008 * This function returns network interface stats for interfaces
6009 * attached to the domain.
6011 * The @device parameter is the network interface either by name or MAC
6014 * Domains may have more than one network interface. To get stats for
6015 * each you should make multiple calls to this function.
6017 * Individual fields within the stats structure may be returned
6018 * as -1, which indicates that the hypervisor does not support
6019 * that particular statistic.
6021 * The returned stats are from domain's point of view.
6023 * Please note, for an unmanaged ethernet type, returned stats
6024 * might have RX/TX swapped.
6026 * Returns: 0 in case of success or -1 in case of failure.
6031 virDomainInterfaceStats(virDomainPtr dom
, const char *device
,
6032 virDomainInterfaceStatsPtr stats
, size_t size
)
6035 virDomainInterfaceStatsStruct stats2
= { -1, -1, -1, -1,
6038 VIR_DOMAIN_DEBUG(dom
, "device=%s, stats=%p, size=%zi",
6039 device
, stats
, size
);
6041 virResetLastError();
6043 virCheckDomainReturn(dom
, -1);
6044 virCheckNonNullArgGoto(device
, error
);
6045 virCheckNonNullArgGoto(stats
, error
);
6046 if (size
> sizeof(stats2
)) {
6047 virReportInvalidArg(size
,
6048 _("size must not exceed %1$zu"),
6055 if (conn
->driver
->domainInterfaceStats
) {
6056 if (conn
->driver
->domainInterfaceStats(dom
, device
, &stats2
) == -1)
6059 memcpy(stats
, &stats2
, size
);
6063 virReportUnsupportedError();
6066 virDispatchError(dom
->conn
);
6072 * virDomainSetInterfaceParameters:
6073 * @domain: pointer to domain object
6074 * @device: the interface name or mac address
6075 * @params: pointer to interface parameter objects
6076 * @nparams: number of interface parameter (this value can be the same or
6077 * less than the number of parameters supported)
6078 * @flags: bitwise-OR of virDomainModificationImpact
6080 * Change a subset or all parameters of interface; currently this
6081 * includes bandwidth parameters. The value of @flags should be
6082 * either VIR_DOMAIN_AFFECT_CURRENT, or a bitwise-or of values
6083 * VIR_DOMAIN_AFFECT_LIVE and VIR_DOMAIN_AFFECT_CONFIG, although
6084 * hypervisors vary in which flags are supported.
6086 * This function may require privileged access to the hypervisor.
6088 * Returns -1 in case of error, 0 in case of success.
6093 virDomainSetInterfaceParameters(virDomainPtr domain
,
6095 virTypedParameterPtr params
,
6096 int nparams
, unsigned int flags
)
6100 VIR_DOMAIN_DEBUG(domain
, "device=%s, params=%p, nparams=%d, flags=0x%x",
6101 device
, params
, nparams
, flags
);
6102 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
6104 virResetLastError();
6106 virCheckDomainReturn(domain
, -1);
6107 conn
= domain
->conn
;
6109 virCheckReadOnlyGoto(conn
->flags
, error
);
6110 virCheckNonNullArgGoto(params
, error
);
6111 virCheckPositiveArgGoto(nparams
, error
);
6113 if (virTypedParameterValidateSet(conn
, params
, nparams
) < 0)
6116 if (conn
->driver
->domainSetInterfaceParameters
) {
6118 ret
= conn
->driver
->domainSetInterfaceParameters(domain
, device
,
6126 virReportUnsupportedError();
6129 virDispatchError(domain
->conn
);
6135 * virDomainGetInterfaceParameters:
6136 * @domain: pointer to domain object
6137 * @device: the interface name or mac address
6138 * @params: pointer to interface parameter objects
6139 * (return value, allocated by the caller)
6140 * @nparams: pointer to number of interface parameter; input and output
6141 * @flags: bitwise-OR of virDomainModificationImpact and virTypedParameterFlags
6143 * Get all interface parameters. On input, @nparams gives the size of
6144 * the @params array; on output, @nparams gives how many slots were
6145 * filled with parameter information, which might be less but will not
6146 * exceed the input value.
6148 * As a special case, calling with @params as NULL and @nparams as 0 on
6149 * input will cause @nparams on output to contain the number of parameters
6150 * supported by the hypervisor. The caller should then allocate @params
6151 * array, i.e. (sizeof(@virTypedParameter) * @nparams) bytes and call the
6152 * API again. See virDomainGetMemoryParameters() for an equivalent usage
6155 * This function may require privileged access to the hypervisor. This function
6156 * expects the caller to allocate the @params.
6158 * Returns -1 in case of error, 0 in case of success.
6163 virDomainGetInterfaceParameters(virDomainPtr domain
,
6165 virTypedParameterPtr params
,
6166 int *nparams
, unsigned int flags
)
6171 VIR_DOMAIN_DEBUG(domain
, "device=%s, params=%p, nparams=%d, flags=0x%x",
6172 device
, params
, (nparams
) ? *nparams
: -1, flags
);
6174 virResetLastError();
6176 virCheckDomainReturn(domain
, -1);
6177 virCheckNonNullArgGoto(nparams
, error
);
6178 virCheckNonNegativeArgGoto(*nparams
, error
);
6180 virCheckNonNullArgGoto(params
, error
);
6182 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
6183 VIR_DRV_FEATURE_TYPED_PARAM_STRING
);
6187 flags
|= VIR_TYPED_PARAM_STRING_OKAY
;
6189 conn
= domain
->conn
;
6191 if (conn
->driver
->domainGetInterfaceParameters
) {
6193 ret
= conn
->driver
->domainGetInterfaceParameters(domain
, device
,
6200 virReportUnsupportedError();
6203 virDispatchError(domain
->conn
);
6209 * virDomainMemoryStats:
6210 * @dom: pointer to the domain object
6211 * @stats: nr_stats-sized array of stat structures (returned)
6212 * @nr_stats: number of memory statistics requested
6213 * @flags: extra flags; not used yet, so callers should always pass 0
6215 * This function provides memory statistics for the domain.
6217 * Up to 'nr_stats' elements of 'stats' will be populated with memory statistics
6218 * from the domain. Only statistics supported by the domain, the driver, and
6219 * this version of libvirt will be returned.
6221 * Memory Statistics:
6223 * VIR_DOMAIN_MEMORY_STAT_SWAP_IN:
6224 * The total amount of data read from swap space (in kb).
6225 * VIR_DOMAIN_MEMORY_STAT_SWAP_OUT:
6226 * The total amount of memory written out to swap space (in kb).
6227 * VIR_DOMAIN_MEMORY_STAT_MAJOR_FAULT:
6228 * The number of page faults that required disk IO to service.
6229 * VIR_DOMAIN_MEMORY_STAT_MINOR_FAULT:
6230 * The number of page faults serviced without disk IO.
6231 * VIR_DOMAIN_MEMORY_STAT_UNUSED:
6232 * The amount of memory which is not being used for any purpose (in kb).
6233 * VIR_DOMAIN_MEMORY_STAT_AVAILABLE:
6234 * The total amount of memory available to the domain's OS (in kb).
6235 * VIR_DOMAIN_MEMORY_STAT_USABLE:
6236 * How much the balloon can be inflated without pushing the guest system
6237 * to swap, corresponds to 'Available' in /proc/meminfo
6238 * VIR_DOMAIN_MEMORY_STAT_ACTUAL_BALLOON:
6239 * Current balloon value (in kb).
6240 * VIR_DOMAIN_MEMORY_STAT_LAST_UPDATE
6241 * Timestamp of the last statistic
6242 * VIR_DOMAIN_MEMORY_STAT_DISK_CACHES
6243 * Memory that can be reclaimed without additional I/O, typically disk
6245 * VIR_DOMAIN_MEMORY_STAT_HUGETLB_PGALLOC
6246 * The number of successful huge page allocations from inside the domain
6247 * VIR_DOMAIN_MEMORY_STAT_HUGETLB_PGFAIL
6248 * The number of failed huge page allocations from inside the domain
6250 * Returns: The number of stats provided or -1 in case of failure.
6255 virDomainMemoryStats(virDomainPtr dom
, virDomainMemoryStatPtr stats
,
6256 unsigned int nr_stats
, unsigned int flags
)
6260 VIR_DOMAIN_DEBUG(dom
, "stats=%p, nr_stats=%u, flags=0x%x",
6261 stats
, nr_stats
, flags
);
6263 virResetLastError();
6265 virCheckDomainReturn(dom
, -1);
6267 if (!stats
|| nr_stats
== 0)
6270 if (nr_stats
> VIR_DOMAIN_MEMORY_STAT_NR
)
6271 nr_stats
= VIR_DOMAIN_MEMORY_STAT_NR
;
6274 if (conn
->driver
->domainMemoryStats
) {
6275 int ret
= conn
->driver
->domainMemoryStats(dom
, stats
, nr_stats
, flags
);
6281 virReportUnsupportedError();
6284 virDispatchError(dom
->conn
);
6290 * virDomainBlockPeek:
6291 * @dom: pointer to the domain object
6292 * @disk: path to the block device, or device shorthand
6293 * @offset: offset within block device
6294 * @size: size to read
6295 * @buffer: return buffer (must be at least size bytes)
6296 * @flags: extra flags; not used yet, so callers should always pass 0
6298 * This function allows you to read the contents of a domain's
6301 * Typical uses for this are to determine if the domain has
6302 * written a Master Boot Record (indicating that the domain
6303 * has completed installation), or to try to work out the state
6304 * of the domain's filesystems.
6306 * (Note that in the local case you might try to open the
6307 * block device or file directly, but that won't work in the
6308 * remote case, nor if you don't have sufficient permission.
6309 * Hence the need for this call).
6311 * The @disk parameter is either an unambiguous source name of the
6312 * block device (the <source file='...'/> sub-element, such as
6313 * "/path/to/image"), or (since 0.9.5) the device target shorthand
6314 * (the <target dev='...'/> sub-element, such as "vda"). Valid names
6315 * can be found by calling virDomainGetXMLDesc() and inspecting
6316 * elements within //domain/devices/disk.
6318 * 'offset' and 'size' represent an area which must lie entirely
6319 * within the device or file. 'size' may be 0 to test if the
6320 * call would succeed.
6322 * 'buffer' is the return buffer and must be at least 'size' bytes.
6324 * NB. The remote driver imposes a 64K byte limit on 'size'.
6325 * For your program to be able to work reliably over a remote
6326 * connection you should split large requests to <= 65536 bytes.
6327 * However, with 0.9.13 this RPC limit has been raised to 1M byte.
6328 * Starting with version 1.0.6 the RPC limit has been raised again.
6329 * Now large requests up to 16M byte are supported.
6331 * Returns: 0 in case of success or -1 in case of failure.
6336 virDomainBlockPeek(virDomainPtr dom
,
6338 unsigned long long offset
,
6345 VIR_DOMAIN_DEBUG(dom
, "disk=%s, offset=%lld, size=%zi, buffer=%p, flags=0x%x",
6346 disk
, offset
, size
, buffer
, flags
);
6348 virResetLastError();
6350 virCheckDomainReturn(dom
, -1);
6353 virCheckReadOnlyGoto(conn
->flags
, error
);
6354 virCheckNonEmptyStringArgGoto(disk
, error
);
6356 /* Allow size == 0 as an access test. */
6358 virCheckNonNullArgGoto(buffer
, error
);
6360 if (conn
->driver
->domainBlockPeek
) {
6362 ret
= conn
->driver
->domainBlockPeek(dom
, disk
, offset
, size
,
6369 virReportUnsupportedError();
6372 virDispatchError(dom
->conn
);
6378 * virDomainBlockResize:
6379 * @dom: pointer to the domain object
6380 * @disk: path to the block image, or shorthand
6381 * @size: new size of the block image, see below for unit
6382 * @flags: bitwise-OR of virDomainBlockResizeFlags
6384 * Resize a block device of domain while the domain is running. If
6385 * @flags is 0, then @size is in kibibytes (blocks of 1024 bytes);
6386 * since 0.9.11, if @flags includes VIR_DOMAIN_BLOCK_RESIZE_BYTES,
6387 * @size is in bytes instead. @size is taken directly as the new
6388 * size. Depending on the file format, the hypervisor may round up
6389 * to the next alignment boundary.
6391 * If @flag contains VIR_DOMAIN_BLOCK_RESIZE_CAPACITY (since 10.0.0) the
6392 * hypervisor will resize the guest block device to fully fill the source.
6393 * @size must be either set to zero, or to the exact size of the block
6394 * device source. This is possible only for image formats with no metadata
6395 * ('raw') and for source devices with limited capacity such as block devices.
6397 * The @disk parameter is either an unambiguous source name of the
6398 * block device (the <source file='...'/> sub-element, such as
6399 * "/path/to/image"), or (since 0.9.5) the device target shorthand
6400 * (the <target dev='...'/> sub-element, such as "vda"). Valid names
6401 * can be found by calling virDomainGetXMLDesc() and inspecting
6402 * elements within //domain/devices/disk.
6404 * Note that this call may fail if the underlying virtualization hypervisor
6405 * does not support it; this call requires privileged access to the
6408 * Returns: 0 in case of success or -1 in case of failure.
6413 virDomainBlockResize(virDomainPtr dom
,
6415 unsigned long long size
,
6420 VIR_DOMAIN_DEBUG(dom
, "disk=%s, size=%llu, flags=0x%x", disk
, size
, flags
);
6422 virResetLastError();
6424 virCheckDomainReturn(dom
, -1);
6427 virCheckReadOnlyGoto(conn
->flags
, error
);
6428 virCheckNonNullArgGoto(disk
, error
);
6430 if (conn
->driver
->domainBlockResize
) {
6432 ret
= conn
->driver
->domainBlockResize(dom
, disk
, size
, flags
);
6438 virReportUnsupportedError();
6441 virDispatchError(dom
->conn
);
6447 * virDomainMemoryPeek:
6448 * @dom: pointer to the domain object
6449 * @start: start of memory to peek
6450 * @size: size of memory to peek
6451 * @buffer: return buffer (must be at least size bytes)
6452 * @flags: bitwise-OR of virDomainMemoryFlags
6454 * This function allows you to read the contents of a domain's
6457 * The memory which is read is controlled by the 'start', 'size'
6458 * and 'flags' parameters.
6460 * If 'flags' is VIR_MEMORY_VIRTUAL then the 'start' and 'size'
6461 * parameters are interpreted as virtual memory addresses for
6462 * whichever task happens to be running on the domain at the
6463 * moment. Although this sounds haphazard it is in fact what
6464 * you want in order to read Linux kernel state, because it
6465 * ensures that pointers in the kernel image can be interpreted
6468 * 'buffer' is the return buffer and must be at least 'size' bytes.
6469 * 'size' may be 0 to test if the call would succeed.
6471 * NB. The remote driver imposes a 64K byte limit on 'size'.
6472 * For your program to be able to work reliably over a remote
6473 * connection you should split large requests to <= 65536 bytes.
6474 * However, with 0.9.13 this RPC limit has been raised to 1M byte.
6475 * Starting with version 1.0.6 the RPC limit has been raised again.
6476 * Now large requests up to 16M byte are supported.
6478 * Returns: 0 in case of success or -1 in case of failure.
6483 virDomainMemoryPeek(virDomainPtr dom
,
6484 unsigned long long start
,
6491 VIR_DOMAIN_DEBUG(dom
, "start=%lld, size=%zi, buffer=%p, flags=0x%x",
6492 start
, size
, buffer
, flags
);
6494 virResetLastError();
6496 virCheckDomainReturn(dom
, -1);
6499 virCheckReadOnlyGoto(conn
->flags
, error
);
6501 /* Note on access to physical memory: A VIR_MEMORY_PHYSICAL flag is
6502 * a possibility. However it isn't really useful unless the caller
6503 * can also access registers, particularly CR3 on x86 in order to
6504 * get the Page Table Directory. Since registers are different on
6505 * every architecture, that would imply another call to get the
6506 * machine registers.
6508 * The QEMU driver handles VIR_MEMORY_VIRTUAL, mapping it
6509 * to the qemu 'memsave' command which does the virtual to physical
6510 * mapping inside qemu.
6512 * The QEMU driver also handles VIR_MEMORY_PHYSICAL, mapping it
6513 * to the qemu 'pmemsave' command.
6515 * At time of writing there is no Xen driver. However the Xen
6516 * hypervisor only lets you map physical pages from other domains,
6517 * and so the Xen driver would have to do the virtual to physical
6518 * mapping by chasing 2, 3 or 4-level page tables from the PTD.
6519 * There is example code in libxc (xc_translate_foreign_address)
6520 * which does this, although we cannot copy this code directly
6521 * because of incompatible licensing.
6524 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_MEMORY_VIRTUAL
, VIR_MEMORY_PHYSICAL
, error
);
6526 /* Allow size == 0 as an access test. */
6528 virCheckNonNullArgGoto(buffer
, error
);
6530 if (conn
->driver
->domainMemoryPeek
) {
6532 ret
= conn
->driver
->domainMemoryPeek(dom
, start
, size
,
6539 virReportUnsupportedError();
6542 virDispatchError(dom
->conn
);
6548 * virDomainGetBlockInfo:
6549 * @domain: a domain object
6550 * @disk: path to the block device, or device shorthand
6551 * @info: pointer to a virDomainBlockInfo structure allocated by the user
6552 * @flags: extra flags; not used yet, so callers should always pass 0
6554 * Extract information about a domain's block device.
6556 * The @disk parameter is either an unambiguous source name of the
6557 * block device (the <source file='...'/> sub-element, such as
6558 * "/path/to/image"), or (since 0.9.5) the device target shorthand
6559 * (the <target dev='...'/> sub-element, such as "vda"). Valid names
6560 * can be found by calling virDomainGetXMLDesc() and inspecting
6561 * elements within //domain/devices/disk.
6563 * For QEMU domains, the allocation and physical virDomainBlockInfo
6564 * values returned will generally be the same, except when using a
6565 * non raw, block backing device, such as qcow2 for an active domain.
6566 * When the persistent domain is not active, QEMU will return the
6567 * default which is the same value for allocation and physical.
6569 * Active QEMU domains can return an allocation value which is more
6570 * representative of the currently used blocks by the device compared
6571 * to the physical size of the device. Applications can use/monitor
6572 * the allocation value with the understanding that if the domain
6573 * becomes inactive during an attempt to get the value, the default
6574 * values will be returned. Thus, the application should check
6575 * after the call for the domain being inactive if the values are
6576 * the same. Optionally, the application could be watching for a
6577 * shutdown event and then ignore any values received afterwards.
6578 * This can be an issue when a domain is being migrated and the
6579 * exact timing of the domain being made inactive and check of
6580 * the allocation value results the default being returned. For
6581 * a transient domain in the similar situation, this call will return
6582 * -1 and an error message indicating the "domain is not running".
6584 * The following is some pseudo code illustrating the call sequence:
6588 * virDomainBlockInfo info;
6591 * // Either get a list of all domains or a specific domain
6592 * // via a virDomainLookupBy*() call.
6594 * // It's also required to fill in the device pointer, but that's
6595 * // specific to the implementation. For the purposes of this example
6596 * // a qcow2 backed device name string would need to be provided.
6598 * // If the following call is made on a persistent domain with a
6599 * // qcow2 block backed block device, then it's possible the returned
6600 * // allocation equals the physical value. In that case, the domain
6601 * // that may have been active prior to calling has become inactive,
6602 * // such as is the case during a domain migration. Thus once we
6603 * // get data returned, check for active domain when the values are
6605 * if (virDomainGetBlockInfo(dom, device, &info, 0) < 0)
6607 * if (info.allocation == info.physical) {
6608 * // If the domain is no longer active,
6609 * // then the defaults are being returned.
6610 * if (!virDomainIsActive())
6611 * goto ignore_return;
6613 * // Do something with the allocation and physical values
6616 * Returns 0 in case of success and -1 in case of failure.
6621 virDomainGetBlockInfo(virDomainPtr domain
, const char *disk
,
6622 virDomainBlockInfoPtr info
, unsigned int flags
)
6626 VIR_DOMAIN_DEBUG(domain
, "info=%p, flags=0x%x", info
, flags
);
6628 virResetLastError();
6631 memset(info
, 0, sizeof(*info
));
6633 virCheckDomainReturn(domain
, -1);
6634 virCheckNonEmptyStringArgGoto(disk
, error
);
6635 virCheckNonNullArgGoto(info
, error
);
6637 conn
= domain
->conn
;
6639 if (conn
->driver
->domainGetBlockInfo
) {
6641 ret
= conn
->driver
->domainGetBlockInfo(domain
, disk
, info
, flags
);
6647 virReportUnsupportedError();
6650 virDispatchError(domain
->conn
);
6656 * virDomainDefineXML:
6657 * @conn: pointer to the hypervisor connection
6658 * @xml: the XML description for the domain, preferably in UTF-8
6660 * Define a domain, but does not start it.
6661 * This definition is persistent, until explicitly undefined with
6662 * virDomainUndefine(). A previous definition for this domain with the same
6663 * UUID and name would be overridden if it already exists.
6665 * virDomainFree should be used to free the resources after the
6666 * domain object is no longer needed.
6668 * Returns NULL in case of error, a pointer to the domain otherwise
6673 virDomainDefineXML(virConnectPtr conn
, const char *xml
)
6675 VIR_DEBUG("conn=%p, xml=%s", conn
, NULLSTR(xml
));
6677 virResetLastError();
6679 virCheckConnectReturn(conn
, NULL
);
6680 virCheckReadOnlyGoto(conn
->flags
, error
);
6681 virCheckNonNullArgGoto(xml
, error
);
6683 if (conn
->driver
->domainDefineXML
) {
6685 ret
= conn
->driver
->domainDefineXML(conn
, xml
);
6691 virReportUnsupportedError();
6694 virDispatchError(conn
);
6700 * virDomainDefineXMLFlags:
6701 * @conn: pointer to the hypervisor connection
6702 * @xml: the XML description for the domain, preferably in UTF-8
6703 * @flags: bitwise OR of the virDomainDefineFlags constants
6705 * Defines a domain, but does not start it.
6706 * This definition is persistent, until explicitly undefined with
6707 * virDomainUndefine(). A previous definition for this domain with the same
6708 * UUID and name would be overridden if it already exists.
6710 * virDomainFree should be used to free the resources after the
6711 * domain object is no longer needed.
6713 * Returns NULL in case of error, a pointer to the domain otherwise
6718 virDomainDefineXMLFlags(virConnectPtr conn
, const char *xml
, unsigned int flags
)
6720 VIR_DEBUG("conn=%p, xml=%s flags=0x%x", conn
, NULLSTR(xml
), flags
);
6722 virResetLastError();
6724 virCheckConnectReturn(conn
, NULL
);
6725 virCheckReadOnlyGoto(conn
->flags
, error
);
6726 virCheckNonNullArgGoto(xml
, error
);
6728 if (conn
->driver
->domainDefineXMLFlags
) {
6730 ret
= conn
->driver
->domainDefineXMLFlags(conn
, xml
, flags
);
6736 virReportUnsupportedError();
6739 virDispatchError(conn
);
6745 * virDomainUndefine:
6746 * @domain: pointer to a defined domain
6748 * Undefine a domain. If the domain is running, it's converted to
6749 * transient domain, without stopping it. If the domain is inactive,
6750 * the domain configuration is removed.
6752 * If the domain has a managed save image (see
6753 * virDomainHasManagedSaveImage()), or if it is inactive and has any
6754 * snapshot metadata (see virDomainSnapshotNum()) or checkpoint
6755 * metadata (see virDomainListAllCheckpoints()), then the undefine
6756 * will fail. See virDomainUndefineFlags() for more control.
6758 * Returns 0 in case of success, -1 in case of error
6763 virDomainUndefine(virDomainPtr domain
)
6767 VIR_DOMAIN_DEBUG(domain
);
6769 virResetLastError();
6771 virCheckDomainReturn(domain
, -1);
6772 conn
= domain
->conn
;
6774 virCheckReadOnlyGoto(conn
->flags
, error
);
6776 if (conn
->driver
->domainUndefine
) {
6778 ret
= conn
->driver
->domainUndefine(domain
);
6784 virReportUnsupportedError();
6787 virDispatchError(domain
->conn
);
6793 * virDomainUndefineFlags:
6794 * @domain: pointer to a defined domain
6795 * @flags: bitwise-OR of supported virDomainUndefineFlagsValues
6797 * Undefine a domain. If the domain is running, it's converted to
6798 * transient domain, without stopping it. If the domain is inactive,
6799 * the domain configuration is removed.
6801 * If the domain has a managed save image (see virDomainHasManagedSaveImage()),
6802 * then including VIR_DOMAIN_UNDEFINE_MANAGED_SAVE in @flags will also remove
6803 * that file, and omitting the flag will cause the undefine process to fail.
6805 * If the domain is inactive and has any snapshot metadata (see
6806 * virDomainSnapshotNum()), then including
6807 * VIR_DOMAIN_UNDEFINE_SNAPSHOTS_METADATA in @flags will also remove
6808 * that metadata. Omitting the flag will cause the undefine of an
6809 * inactive domain with snapshots to fail. Active domains will retain
6810 * snapshot metadata until the (now-transient) domain halts,
6811 * regardless of whether this flag is present. On hypervisors that
6812 * support snapshots, but where snapshots do not use libvirt metadata,
6813 * this flag has no effect.
6815 * If the domain is inactive and has any checkpoint metadata (see
6816 * virDomainListAllCheckpoints()), then including
6817 * VIR_DOMAIN_UNDEFINE_CHECKPOINTS_METADATA in @flags will also remove
6818 * that metadata. Omitting the flag will cause the undefine of an
6819 * inactive domain with checkpoints to fail. Active domains will
6820 * retain checkpoint metadata until the (now-transient) domain halts,
6821 * regardless of whether this flag is present. On hypervisors that
6822 * support checkpoints, but where checkpoints do not use libvirt
6823 * metadata, this flag has no effect.
6825 * If the domain has any nvram specified, the undefine process will fail
6826 * unless VIR_DOMAIN_UNDEFINE_KEEP_NVRAM is specified, or if
6827 * VIR_DOMAIN_UNDEFINE_NVRAM is specified to remove the nvram file.
6829 * Returns 0 in case of success, -1 in case of error
6834 virDomainUndefineFlags(virDomainPtr domain
,
6839 VIR_DOMAIN_DEBUG(domain
, "flags=0x%x", flags
);
6841 virResetLastError();
6843 virCheckDomainReturn(domain
, -1);
6844 conn
= domain
->conn
;
6846 virCheckReadOnlyGoto(conn
->flags
, error
);
6848 if (conn
->driver
->domainUndefineFlags
) {
6850 ret
= conn
->driver
->domainUndefineFlags(domain
, flags
);
6856 virReportUnsupportedError();
6859 virDispatchError(domain
->conn
);
6865 * virConnectNumOfDefinedDomains:
6866 * @conn: pointer to the hypervisor connection
6868 * Provides the number of defined but inactive domains.
6870 * Returns the number of domain found or -1 in case of error
6875 virConnectNumOfDefinedDomains(virConnectPtr conn
)
6877 VIR_DEBUG("conn=%p", conn
);
6879 virResetLastError();
6881 virCheckConnectReturn(conn
, -1);
6883 if (conn
->driver
->connectNumOfDefinedDomains
) {
6885 ret
= conn
->driver
->connectNumOfDefinedDomains(conn
);
6891 virReportUnsupportedError();
6894 virDispatchError(conn
);
6900 * virConnectListDefinedDomains:
6901 * @conn: pointer to the hypervisor connection
6902 * @names: pointer to an array to store the names
6903 * @maxnames: size of the array
6905 * list the defined but inactive domains, stores the pointers to the names
6908 * The use of this function is discouraged. Instead, use
6909 * virConnectListAllDomains().
6911 * Returns the number of names provided in the array or -1 in case of error.
6912 * Note that this command is inherently racy; a domain can be defined between
6913 * a call to virConnectNumOfDefinedDomains() and this call; you are only
6914 * guaranteed that all currently defined domains were listed if the return
6915 * is less than @maxids. The client must call free() on each returned name.
6920 virConnectListDefinedDomains(virConnectPtr conn
, char **const names
,
6923 VIR_DEBUG("conn=%p, names=%p, maxnames=%d", conn
, names
, maxnames
);
6925 virResetLastError();
6927 virCheckConnectReturn(conn
, -1);
6928 virCheckNonNullArrayArgGoto(names
, maxnames
, error
);
6929 virCheckNonNegativeArgGoto(maxnames
, error
);
6931 if (conn
->driver
->connectListDefinedDomains
) {
6933 ret
= conn
->driver
->connectListDefinedDomains(conn
, names
, maxnames
);
6939 virReportUnsupportedError();
6942 virDispatchError(conn
);
6948 * virConnectListAllDomains:
6949 * @conn: Pointer to the hypervisor connection.
6950 * @domains: Pointer to a variable to store the array containing domain objects
6951 * or NULL if the list is not required (just returns number of guests).
6952 * @flags: bitwise-OR of virConnectListAllDomainsFlags
6954 * Collect a possibly-filtered list of all domains, and return an allocated
6955 * array of information for each. This API solves the race inherent in
6956 * virConnectListDomains() and virConnectListDefinedDomains().
6958 * Normally, all domains are returned; however, @flags can be used to
6959 * filter the results for a smaller list of targeted domains. The valid
6960 * flags are divided into groups, where each group contains bits that
6961 * describe mutually exclusive attributes of a domain, and where all bits
6962 * within a group describe all possible domains. Some hypervisors might
6963 * reject explicit bits from a group where the hypervisor cannot make a
6964 * distinction (for example, not all hypervisors can tell whether domains
6965 * have snapshots). For a group supported by a given hypervisor, the
6966 * behavior when no bits of a group are set is identical to the behavior
6967 * when all bits in that group are set. When setting bits from more than
6968 * one group, it is possible to select an impossible combination (such
6969 * as an inactive transient domain), in that case a hypervisor may return
6970 * either 0 or an error.
6972 * The first group of @flags is VIR_CONNECT_LIST_DOMAINS_ACTIVE (online
6973 * domains) and VIR_CONNECT_LIST_DOMAINS_INACTIVE (offline domains).
6975 * The next group of @flags is VIR_CONNECT_LIST_DOMAINS_PERSISTENT (defined
6976 * domains) and VIR_CONNECT_LIST_DOMAINS_TRANSIENT (running but not defined).
6978 * The next group of @flags covers various domain states:
6979 * VIR_CONNECT_LIST_DOMAINS_RUNNING, VIR_CONNECT_LIST_DOMAINS_PAUSED,
6980 * VIR_CONNECT_LIST_DOMAINS_SHUTOFF, and a catch-all for all other states
6981 * (such as crashed, this catch-all covers the possibility of adding new
6984 * The remaining groups cover boolean attributes commonly asked about
6985 * domains; they include VIR_CONNECT_LIST_DOMAINS_MANAGEDSAVE and
6986 * VIR_CONNECT_LIST_DOMAINS_NO_MANAGEDSAVE, for filtering based on whether
6987 * a managed save image exists; VIR_CONNECT_LIST_DOMAINS_AUTOSTART and
6988 * VIR_CONNECT_LIST_DOMAINS_NO_AUTOSTART, for filtering based on autostart;
6989 * VIR_CONNECT_LIST_DOMAINS_HAS_SNAPSHOT and
6990 * VIR_CONNECT_LIST_DOMAINS_NO_SNAPSHOT, for filtering based on whether
6991 * a domain has snapshots; VIR_CONNECT_LIST_DOMAINS_HAS_CHECKPOINT and
6992 * VIR_CONNECT_LIST_DOMAINS_NO_CHECKPOINT, for filtering based on whether
6993 * a domain has checkpoints.
6997 * virDomainPtr *domains;
7000 * unsigned int flags = VIR_CONNECT_LIST_DOMAINS_RUNNING |
7001 * VIR_CONNECT_LIST_DOMAINS_PERSISTENT;
7002 * ret = virConnectListAllDomains(conn, &domains, flags);
7005 * for (i = 0; i < ret; i++) {
7006 * do_something_with_domain(domains[i]);
7007 * //here or in a separate loop if needed
7008 * virDomainFree(domains[i]);
7012 * Returns the number of domains found or -1 and sets domains to NULL in case of
7013 * error. On success, the array stored into @domains is guaranteed to have an
7014 * extra allocated element set to NULL but not included in the return count, to
7015 * make iteration easier. The caller is responsible for calling virDomainFree()
7016 * on each array element, then calling free() on @domains.
7021 virConnectListAllDomains(virConnectPtr conn
,
7022 virDomainPtr
**domains
,
7025 VIR_DEBUG("conn=%p, domains=%p, flags=0x%x", conn
, domains
, flags
);
7027 virResetLastError();
7032 virCheckConnectReturn(conn
, -1);
7034 if (conn
->driver
->connectListAllDomains
) {
7036 ret
= conn
->driver
->connectListAllDomains(conn
, domains
, flags
);
7042 virReportUnsupportedError();
7045 virDispatchError(conn
);
7052 * @domain: pointer to a defined domain
7054 * Launch a defined domain. If the call succeeds the domain moves from the
7055 * defined to the running domains pools. The domain will be paused only
7056 * if restoring from managed state created from a paused domain. For more
7057 * control, see virDomainCreateWithFlags().
7059 * Returns 0 in case of success, -1 in case of error
7064 virDomainCreate(virDomainPtr domain
)
7068 VIR_DOMAIN_DEBUG(domain
);
7070 virResetLastError();
7072 virCheckDomainReturn(domain
, -1);
7073 conn
= domain
->conn
;
7075 virCheckReadOnlyGoto(conn
->flags
, error
);
7077 if (conn
->driver
->domainCreate
) {
7079 ret
= conn
->driver
->domainCreate(domain
);
7085 virReportUnsupportedError();
7088 virDispatchError(domain
->conn
);
7094 * virDomainCreateWithFlags:
7095 * @domain: pointer to a defined domain
7096 * @flags: bitwise-OR of supported virDomainCreateFlags
7098 * Launch a defined domain. If the call succeeds the domain moves from the
7099 * defined to the running domains pools.
7101 * If the VIR_DOMAIN_START_PAUSED flag is set, or if the guest domain
7102 * has a managed save image that requested paused state (see
7103 * virDomainManagedSave()) the guest domain will be started, but its
7104 * CPUs will remain paused. The CPUs can later be manually started
7105 * using virDomainResume(). In all other cases, the guest domain will
7108 * If the VIR_DOMAIN_START_AUTODESTROY flag is set, the guest
7109 * domain will be automatically destroyed when the virConnectPtr
7110 * object is finally released. This will also happen if the
7111 * client application crashes / loses its connection to the
7112 * libvirtd daemon. Any domains marked for auto destroy will
7113 * block attempts at migration. Hypervisors may also block save-to-file,
7116 * If the VIR_DOMAIN_START_BYPASS_CACHE flag is set, and there is a
7117 * managed save file for this domain (created by virDomainManagedSave()),
7118 * then libvirt will attempt to bypass the file system cache while restoring
7119 * the file, or fail if it cannot do so for the given system; this can allow
7120 * less pressure on file system cache, but also risks slowing loads from NFS.
7122 * If the VIR_DOMAIN_START_FORCE_BOOT flag is set, then any managed save
7123 * file for this domain is discarded, and the domain boots from scratch.
7125 * If @flags includes VIR_DOMAIN_START_RESET_NVRAM, then libvirt will
7126 * discard any existing NVRAM file and re-initialize NVRAM from the
7127 * pristine template.
7129 * Returns 0 in case of success, -1 in case of error
7134 virDomainCreateWithFlags(virDomainPtr domain
, unsigned int flags
)
7138 VIR_DOMAIN_DEBUG(domain
, "flags=0x%x", flags
);
7140 virResetLastError();
7142 virCheckDomainReturn(domain
, -1);
7143 conn
= domain
->conn
;
7145 virCheckReadOnlyGoto(conn
->flags
, error
);
7147 if (conn
->driver
->domainCreateWithFlags
) {
7149 ret
= conn
->driver
->domainCreateWithFlags(domain
, flags
);
7155 virReportUnsupportedError();
7158 virDispatchError(domain
->conn
);
7164 * virDomainCreateWithFiles:
7165 * @domain: pointer to a defined domain
7166 * @nfiles: number of file descriptors passed
7167 * @files: list of file descriptors passed
7168 * @flags: bitwise-OR of supported virDomainCreateFlags
7170 * Launch a defined domain. If the call succeeds the domain moves from the
7171 * defined to the running domains pools.
7173 * @files provides an array of file descriptors which will be
7174 * made available to the 'init' process of the guest. The file
7175 * handles exposed to the guest will be renumbered to start
7176 * from 3 (ie immediately following stderr). This is only
7177 * supported for guests which use container based virtualization
7180 * If the VIR_DOMAIN_START_PAUSED flag is set, or if the guest domain
7181 * has a managed save image that requested paused state (see
7182 * virDomainManagedSave()) the guest domain will be started, but its
7183 * CPUs will remain paused. The CPUs can later be manually started
7184 * using virDomainResume(). In all other cases, the guest domain will
7187 * If the VIR_DOMAIN_START_AUTODESTROY flag is set, the guest
7188 * domain will be automatically destroyed when the virConnectPtr
7189 * object is finally released. This will also happen if the
7190 * client application crashes / loses its connection to the
7191 * libvirtd daemon. Any domains marked for auto destroy will
7192 * block attempts at migration, save-to-file, or snapshots.
7194 * If the VIR_DOMAIN_START_BYPASS_CACHE flag is set, and there is a
7195 * managed save file for this domain (created by virDomainManagedSave()),
7196 * then libvirt will attempt to bypass the file system cache while restoring
7197 * the file, or fail if it cannot do so for the given system; this can allow
7198 * less pressure on file system cache, but also risks slowing loads from NFS.
7200 * If the VIR_DOMAIN_START_FORCE_BOOT flag is set, then any managed save
7201 * file for this domain is discarded, and the domain boots from scratch.
7203 * If @flags includes VIR_DOMAIN_START_RESET_NVRAM, then libvirt will
7204 * discard any existing NVRAM file and re-initialize NVRAM from the
7205 * pristine template.
7207 * Returns 0 in case of success, -1 in case of error
7212 virDomainCreateWithFiles(virDomainPtr domain
, unsigned int nfiles
,
7213 int *files
, unsigned int flags
)
7217 VIR_DOMAIN_DEBUG(domain
, "nfiles=%u, files=%p, flags=0x%x",
7218 nfiles
, files
, flags
);
7220 virResetLastError();
7222 virCheckDomainReturn(domain
, -1);
7223 conn
= domain
->conn
;
7225 virCheckReadOnlyGoto(conn
->flags
, error
);
7230 if ((rc
= VIR_DRV_SUPPORTS_FEATURE(conn
->driver
, conn
,
7231 VIR_DRV_FEATURE_FD_PASSING
)) <= 0) {
7233 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
7234 _("fd passing is not supported by this connection"));
7239 if (conn
->driver
->domainCreateWithFiles
) {
7241 ret
= conn
->driver
->domainCreateWithFiles(domain
,
7249 virReportUnsupportedError();
7252 virDispatchError(domain
->conn
);
7258 * virDomainGetAutostart:
7259 * @domain: a domain object
7260 * @autostart: the value returned
7262 * Provides a boolean value indicating whether the domain
7263 * configured to be automatically started when the host
7266 * Returns -1 in case of error, 0 in case of success
7271 virDomainGetAutostart(virDomainPtr domain
,
7276 VIR_DOMAIN_DEBUG(domain
, "autostart=%p", autostart
);
7278 virResetLastError();
7280 virCheckDomainReturn(domain
, -1);
7281 virCheckNonNullArgGoto(autostart
, error
);
7283 conn
= domain
->conn
;
7285 if (conn
->driver
->domainGetAutostart
) {
7287 ret
= conn
->driver
->domainGetAutostart(domain
, autostart
);
7293 virReportUnsupportedError();
7296 virDispatchError(domain
->conn
);
7302 * virDomainSetAutostart:
7303 * @domain: a domain object
7304 * @autostart: whether the domain should be automatically started 0 or 1
7306 * Configure the domain to be automatically started
7307 * when the host machine boots.
7309 * Returns -1 in case of error, 0 in case of success
7314 virDomainSetAutostart(virDomainPtr domain
,
7319 VIR_DOMAIN_DEBUG(domain
, "autostart=%d", autostart
);
7321 virResetLastError();
7323 virCheckDomainReturn(domain
, -1);
7324 conn
= domain
->conn
;
7326 virCheckReadOnlyGoto(conn
->flags
, error
);
7328 if (conn
->driver
->domainSetAutostart
) {
7330 ret
= conn
->driver
->domainSetAutostart(domain
, autostart
);
7336 virReportUnsupportedError();
7339 virDispatchError(domain
->conn
);
7345 * virDomainInjectNMI:
7346 * @domain: pointer to domain object, or NULL for Domain0
7347 * @flags: extra flags; not used yet, so callers should always pass 0
7349 * Send NMI to the guest
7351 * Returns 0 in case of success, -1 in case of failure.
7356 virDomainInjectNMI(virDomainPtr domain
, unsigned int flags
)
7359 VIR_DOMAIN_DEBUG(domain
, "flags=0x%x", flags
);
7361 virResetLastError();
7363 virCheckDomainReturn(domain
, -1);
7364 conn
= domain
->conn
;
7366 virCheckReadOnlyGoto(conn
->flags
, error
);
7368 if (conn
->driver
->domainInjectNMI
) {
7370 ret
= conn
->driver
->domainInjectNMI(domain
, flags
);
7376 virReportUnsupportedError();
7379 virDispatchError(domain
->conn
);
7386 * @domain: pointer to domain object, or NULL for Domain0
7387 * @codeset: the code set of keycodes, from virKeycodeSet
7388 * @holdtime: the duration (in milliseconds) that the keys will be held
7389 * @keycodes: array of keycodes
7390 * @nkeycodes: number of keycodes, up to VIR_DOMAIN_SEND_KEY_MAX_KEYS
7391 * @flags: extra flags; not used yet, so callers should always pass 0
7393 * Send key(s) to the guest.
7395 * Returns 0 in case of success, -1 in case of failure.
7400 virDomainSendKey(virDomainPtr domain
,
7401 unsigned int codeset
,
7402 unsigned int holdtime
,
7403 unsigned int *keycodes
,
7408 VIR_DOMAIN_DEBUG(domain
, "codeset=%u, holdtime=%u, nkeycodes=%u, flags=0x%x",
7409 codeset
, holdtime
, nkeycodes
, flags
);
7411 virResetLastError();
7413 virCheckDomainReturn(domain
, -1);
7414 conn
= domain
->conn
;
7416 virCheckReadOnlyGoto(conn
->flags
, error
);
7417 virCheckNonNullArgGoto(keycodes
, error
);
7418 virCheckPositiveArgGoto(nkeycodes
, error
);
7420 if (codeset
>= VIR_KEYCODE_SET_LAST
) {
7421 virReportInvalidArg(codeset
,
7422 _("Unsupported codeset '%1$d'"),
7427 if (nkeycodes
> VIR_DOMAIN_SEND_KEY_MAX_KEYS
) {
7428 virReportInvalidArg(nkeycodes
,
7429 _("nkeycodes must be <= %1$d"),
7430 VIR_DOMAIN_SEND_KEY_MAX_KEYS
);
7434 if (conn
->driver
->domainSendKey
) {
7436 ret
= conn
->driver
->domainSendKey(domain
, codeset
, holdtime
,
7437 keycodes
, nkeycodes
, flags
);
7443 virReportUnsupportedError();
7446 virDispatchError(domain
->conn
);
7452 * virDomainSendProcessSignal:
7453 * @domain: pointer to domain object
7454 * @pid_value: a positive integer process ID, or negative integer process group ID
7455 * @signum: a signal from the virDomainProcessSignal enum
7456 * @flags: currently unused, pass 0
7458 * Send a signal to the designated process in the guest
7460 * The signal numbers must be taken from the virDomainProcessSignal
7461 * enum. These will be translated to the corresponding signal
7462 * number for the guest OS, by the guest agent delivering the
7463 * signal. If there is no mapping from virDomainProcessSignal to
7464 * the native OS signals, this API will report an error.
7466 * If @pid_value is an integer greater than zero, it is
7467 * treated as a process ID. If @pid_value is an integer
7468 * less than zero, it is treated as a process group ID.
7469 * All the @pid_value numbers are from the container/guest
7470 * namespace. The value zero is not valid.
7472 * Not all hypervisors will support sending signals to
7473 * arbitrary processes or process groups. If this API is
7474 * implemented the minimum requirement is to be able to
7475 * use @pid_value == 1 (i.e. kill init). No other value is
7476 * required to be supported.
7478 * If the @signum is VIR_DOMAIN_PROCESS_SIGNAL_NOP then this
7479 * API will simply report whether the process is running in
7480 * the container/guest.
7482 * Returns 0 in case of success, -1 in case of failure.
7487 virDomainSendProcessSignal(virDomainPtr domain
,
7488 long long pid_value
,
7489 unsigned int signum
,
7493 VIR_DOMAIN_DEBUG(domain
, "pid=%lld, signum=%u flags=0x%x",
7494 pid_value
, signum
, flags
);
7496 virResetLastError();
7498 virCheckDomainReturn(domain
, -1);
7499 conn
= domain
->conn
;
7501 virCheckNonZeroArgGoto(pid_value
, error
);
7502 virCheckReadOnlyGoto(conn
->flags
, error
);
7504 if (conn
->driver
->domainSendProcessSignal
) {
7506 ret
= conn
->driver
->domainSendProcessSignal(domain
,
7515 virReportUnsupportedError();
7518 virDispatchError(domain
->conn
);
7524 * virDomainSetVcpus:
7525 * @domain: pointer to domain object, or NULL for Domain0
7526 * @nvcpus: the new number of virtual CPUs for this domain
7528 * Dynamically change the number of virtual CPUs used by the domain.
7529 * Note that this call may fail if the underlying virtualization hypervisor
7530 * does not support it or if growing the number is arbitrarily limited.
7531 * This function may require privileged access to the hypervisor.
7533 * Note that if this call is executed before the guest has finished booting,
7534 * the guest may fail to process the change.
7536 * This command only changes the runtime configuration of the domain,
7537 * so can only be called on an active domain. It is hypervisor-dependent
7538 * whether it also affects persistent configuration; for more control,
7539 * use virDomainSetVcpusFlags().
7541 * Returns 0 in case of success, -1 in case of failure.
7546 virDomainSetVcpus(virDomainPtr domain
, unsigned int nvcpus
)
7550 VIR_DOMAIN_DEBUG(domain
, "nvcpus=%u", nvcpus
);
7552 virResetLastError();
7554 virCheckDomainReturn(domain
, -1);
7555 conn
= domain
->conn
;
7557 virCheckReadOnlyGoto(conn
->flags
, error
);
7558 virCheckNonZeroArgGoto(nvcpus
, error
);
7560 if (conn
->driver
->domainSetVcpus
) {
7562 ret
= conn
->driver
->domainSetVcpus(domain
, nvcpus
);
7568 virReportUnsupportedError();
7571 virDispatchError(domain
->conn
);
7577 * virDomainSetVcpusFlags:
7578 * @domain: pointer to domain object, or NULL for Domain0
7579 * @nvcpus: the new number of virtual CPUs for this domain, must be at least 1
7580 * @flags: bitwise-OR of virDomainVcpuFlags
7582 * Dynamically change the number of virtual CPUs used by the domain.
7583 * Note that this call may fail if the underlying virtualization hypervisor
7584 * does not support it or if growing the number is arbitrarily limited.
7585 * This function may require privileged access to the hypervisor.
7587 * @flags may include VIR_DOMAIN_AFFECT_LIVE to affect a running
7588 * domain (which may fail if domain is not active), or
7589 * VIR_DOMAIN_AFFECT_CONFIG to affect the next boot via the XML
7590 * description of the domain. Both flags may be set.
7591 * If neither flag is specified (that is, @flags is VIR_DOMAIN_AFFECT_CURRENT),
7592 * then an inactive domain modifies persistent setup, while an active domain
7593 * is hypervisor-dependent on whether just live or both live and persistent
7596 * Note that if this call is executed before the guest has finished booting,
7597 * the guest may fail to process the change.
7599 * If @flags includes VIR_DOMAIN_VCPU_MAXIMUM, then
7600 * VIR_DOMAIN_AFFECT_LIVE must be clear, and only the maximum virtual
7601 * CPU limit is altered; generally, this value must be less than or
7602 * equal to virConnectGetMaxVcpus(). Otherwise, this call affects the
7603 * current virtual CPU limit, which must be less than or equal to the
7604 * maximum limit. Note that hypervisors may not allow changing the maximum
7605 * vcpu count if processor topology is specified.
7607 * If @flags includes VIR_DOMAIN_VCPU_GUEST, then the state of processors is
7608 * modified inside the guest instead of the hypervisor. This flag can only
7609 * be used with live guests and is incompatible with VIR_DOMAIN_VCPU_MAXIMUM.
7610 * The usage of this flag may require a guest agent configured.
7612 * Not all hypervisors can support all flag combinations.
7614 * Returns 0 in case of success, -1 in case of failure.
7619 virDomainSetVcpusFlags(virDomainPtr domain
, unsigned int nvcpus
,
7624 VIR_DOMAIN_DEBUG(domain
, "nvcpus=%u, flags=0x%x", nvcpus
, flags
);
7626 virResetLastError();
7628 virCheckDomainReturn(domain
, -1);
7629 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
7631 VIR_REQUIRE_FLAG_GOTO(VIR_DOMAIN_VCPU_MAXIMUM
,
7632 VIR_DOMAIN_AFFECT_CONFIG
,
7635 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_VCPU_GUEST
,
7636 VIR_DOMAIN_AFFECT_CONFIG
,
7639 virCheckNonZeroArgGoto(nvcpus
, error
);
7641 conn
= domain
->conn
;
7643 if (conn
->driver
->domainSetVcpusFlags
) {
7645 ret
= conn
->driver
->domainSetVcpusFlags(domain
, nvcpus
, flags
);
7651 virReportUnsupportedError();
7654 virDispatchError(domain
->conn
);
7660 * virDomainGetVcpusFlags:
7661 * @domain: pointer to domain object, or NULL for Domain0
7662 * @flags: bitwise-OR of virDomainVcpuFlags
7664 * Query the number of virtual CPUs used by the domain. Note that
7665 * this call may fail if the underlying virtualization hypervisor does
7666 * not support it. This function may require privileged access to the
7669 * If @flags includes VIR_DOMAIN_AFFECT_LIVE, this will query a
7670 * running domain (which will fail if domain is not active); if
7671 * it includes VIR_DOMAIN_AFFECT_CONFIG, this will query the XML
7672 * description of the domain. It is an error to set both flags.
7673 * If neither flag is set (that is, VIR_DOMAIN_AFFECT_CURRENT),
7674 * then the configuration queried depends on whether the domain
7675 * is currently running.
7677 * If @flags includes VIR_DOMAIN_VCPU_MAXIMUM, then the maximum
7678 * virtual CPU limit is queried. Otherwise, this call queries the
7679 * current virtual CPU count.
7681 * If @flags includes VIR_DOMAIN_VCPU_GUEST, then the state of the processors
7682 * is queried in the guest instead of the hypervisor. This flag is only usable
7683 * on live domains. Guest agent may be needed for this flag to be available.
7685 * Returns the number of vCPUs in case of success, -1 in case of failure.
7690 virDomainGetVcpusFlags(virDomainPtr domain
, unsigned int flags
)
7694 VIR_DOMAIN_DEBUG(domain
, "flags=0x%x", flags
);
7696 virResetLastError();
7698 virCheckDomainReturn(domain
, -1);
7699 conn
= domain
->conn
;
7701 if (flags
& VIR_DOMAIN_VCPU_GUEST
)
7702 virCheckReadOnlyGoto(conn
->flags
, error
);
7704 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_AFFECT_LIVE
,
7705 VIR_DOMAIN_AFFECT_CONFIG
,
7708 if (conn
->driver
->domainGetVcpusFlags
) {
7710 ret
= conn
->driver
->domainGetVcpusFlags(domain
, flags
);
7716 virReportUnsupportedError();
7719 virDispatchError(domain
->conn
);
7726 * @domain: pointer to domain object, or NULL for Domain0
7727 * @vcpu: virtual CPU number
7728 * @cpumap: pointer to a bit map of real CPUs (in 8-bit bytes) (IN)
7729 * Each bit set to 1 means that corresponding CPU is usable.
7730 * Bytes are stored in little-endian order: CPU0-7, 8-15...
7731 * In each byte, lowest CPU number is least significant bit.
7732 * @maplen: number of bytes in cpumap, from 1 up to size of CPU map in
7733 * underlying virtualization system (Xen...).
7734 * If maplen < size, missing bytes are set to zero.
7735 * If maplen > size, failure code is returned.
7737 * Dynamically change the real CPUs which can be allocated to a virtual CPU.
7738 * This function may require privileged access to the hypervisor.
7740 * This command only changes the runtime configuration of the domain,
7741 * so can only be called on an active domain.
7743 * Returns 0 in case of success, -1 in case of failure.
7748 virDomainPinVcpu(virDomainPtr domain
, unsigned int vcpu
,
7749 unsigned char *cpumap
, int maplen
)
7753 VIR_DOMAIN_DEBUG(domain
, "vcpu=%u, cpumap=%p, maplen=%d",
7754 vcpu
, cpumap
, maplen
);
7756 virResetLastError();
7758 virCheckDomainReturn(domain
, -1);
7759 conn
= domain
->conn
;
7761 virCheckReadOnlyGoto(conn
->flags
, error
);
7762 virCheckNonNullArgGoto(cpumap
, error
);
7763 virCheckPositiveArgGoto(maplen
, error
);
7765 if (conn
->driver
->domainPinVcpu
) {
7767 ret
= conn
->driver
->domainPinVcpu(domain
, vcpu
, cpumap
, maplen
);
7773 virReportUnsupportedError();
7776 virDispatchError(domain
->conn
);
7782 * virDomainPinVcpuFlags:
7783 * @domain: pointer to domain object, or NULL for Domain0
7784 * @vcpu: virtual CPU number
7785 * @cpumap: pointer to a bit map of real CPUs (in 8-bit bytes) (IN)
7786 * Each bit set to 1 means that corresponding CPU is usable.
7787 * Bytes are stored in little-endian order: CPU0-7, 8-15...
7788 * In each byte, lowest CPU number is least significant bit.
7789 * @maplen: number of bytes in cpumap, from 1 up to size of CPU map in
7790 * underlying virtualization system (Xen...).
7791 * If maplen < size, missing bytes are set to zero.
7792 * If maplen > size, failure code is returned.
7793 * @flags: bitwise-OR of virDomainModificationImpact
7795 * Dynamically change the real CPUs which can be allocated to a virtual CPU.
7796 * This function may require privileged access to the hypervisor.
7798 * @flags may include VIR_DOMAIN_AFFECT_LIVE or VIR_DOMAIN_AFFECT_CONFIG.
7799 * Both flags may be set.
7800 * If VIR_DOMAIN_AFFECT_LIVE is set, the change affects a running domain
7801 * and may fail if domain is not alive.
7802 * If VIR_DOMAIN_AFFECT_CONFIG is set, the change affects persistent state,
7803 * and will fail for transient domains. If neither flag is specified (that is,
7804 * @flags is VIR_DOMAIN_AFFECT_CURRENT), then an inactive domain modifies
7805 * persistent setup, while an active domain is hypervisor-dependent on whether
7806 * just live or both live and persistent state is changed.
7807 * Not all hypervisors can support all flag combinations.
7809 * See also virDomainGetVcpuPinInfo for querying this information.
7811 * Returns 0 in case of success, -1 in case of failure.
7816 virDomainPinVcpuFlags(virDomainPtr domain
, unsigned int vcpu
,
7817 unsigned char *cpumap
, int maplen
, unsigned int flags
)
7821 VIR_DOMAIN_DEBUG(domain
, "vcpu=%u, cpumap=%p, maplen=%d, flags=0x%x",
7822 vcpu
, cpumap
, maplen
, flags
);
7824 virResetLastError();
7826 virCheckDomainReturn(domain
, -1);
7827 conn
= domain
->conn
;
7829 virCheckReadOnlyGoto(conn
->flags
, error
);
7830 virCheckNonNullArgGoto(cpumap
, error
);
7831 virCheckPositiveArgGoto(maplen
, error
);
7833 if (conn
->driver
->domainPinVcpuFlags
) {
7835 ret
= conn
->driver
->domainPinVcpuFlags(domain
, vcpu
, cpumap
, maplen
, flags
);
7841 virReportUnsupportedError();
7844 virDispatchError(domain
->conn
);
7850 * virDomainGetVcpuPinInfo:
7851 * @domain: pointer to domain object, or NULL for Domain0
7852 * @ncpumaps: the number of cpumap (listed first to match virDomainGetVcpus)
7853 * @cpumaps: pointer to a bit map of real CPUs for all vcpus of this
7854 * domain (in 8-bit bytes) (OUT)
7855 * It's assumed there is <ncpumaps> cpumap in cpumaps array.
7856 * The memory allocated to cpumaps must be (ncpumaps * maplen) bytes
7857 * (ie: calloc(ncpumaps, maplen)).
7858 * One cpumap inside cpumaps has the format described in
7859 * virDomainPinVcpu() API.
7861 * @maplen: the number of bytes in one cpumap, from 1 up to size of CPU map.
7863 * @flags: bitwise-OR of virDomainModificationImpact
7864 * Must not be VIR_DOMAIN_AFFECT_LIVE and
7865 * VIR_DOMAIN_AFFECT_CONFIG concurrently.
7867 * Query the CPU affinity setting of all virtual CPUs of domain, store it
7870 * Returns the number of virtual CPUs in case of success,
7871 * -1 in case of failure.
7876 virDomainGetVcpuPinInfo(virDomainPtr domain
, int ncpumaps
,
7877 unsigned char *cpumaps
, int maplen
, unsigned int flags
)
7881 VIR_DOMAIN_DEBUG(domain
, "ncpumaps=%d, cpumaps=%p, maplen=%d, flags=0x%x",
7882 ncpumaps
, cpumaps
, maplen
, flags
);
7884 virResetLastError();
7886 virCheckDomainReturn(domain
, -1);
7887 conn
= domain
->conn
;
7889 virCheckNonNullArrayArgGoto(cpumaps
, ncpumaps
, error
);
7890 virCheckPositiveArgGoto(ncpumaps
, error
);
7891 virCheckPositiveArgGoto(maplen
, error
);
7893 if (VIR_INT_MULTIPLY_OVERFLOW(ncpumaps
, maplen
)) {
7894 virReportError(VIR_ERR_OVERFLOW
, _("input too large: %1$d * %2$d"),
7899 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_AFFECT_LIVE
,
7900 VIR_DOMAIN_AFFECT_CONFIG
,
7903 if (conn
->driver
->domainGetVcpuPinInfo
) {
7905 ret
= conn
->driver
->domainGetVcpuPinInfo(domain
, ncpumaps
,
7906 cpumaps
, maplen
, flags
);
7912 virReportUnsupportedError();
7915 virDispatchError(domain
->conn
);
7921 * virDomainPinEmulator:
7922 * @domain: pointer to domain object, or NULL for Domain0
7923 * @cpumap: pointer to a bit map of real CPUs (in 8-bit bytes) (IN)
7924 * Each bit set to 1 means that corresponding CPU is usable.
7925 * Bytes are stored in little-endian order: CPU0-7, 8-15...
7926 * In each byte, lowest CPU number is least significant bit.
7927 * @maplen: number of bytes in cpumap, from 1 up to size of CPU map in
7928 * underlying virtualization system (Xen...).
7929 * If maplen < size, missing bytes are set to zero.
7930 * If maplen > size, failure code is returned.
7931 * @flags: bitwise-OR of virDomainModificationImpact
7933 * Dynamically change the real CPUs which can be allocated to all emulator
7934 * threads. This function may require privileged access to the hypervisor.
7936 * @flags may include VIR_DOMAIN_AFFECT_LIVE or VIR_DOMAIN_AFFECT_CONFIG.
7937 * Both flags may be set.
7938 * If VIR_DOMAIN_AFFECT_LIVE is set, the change affects a running domain
7939 * and may fail if domain is not alive.
7940 * If VIR_DOMAIN_AFFECT_CONFIG is set, the change affects persistent state,
7941 * and will fail for transient domains. If neither flag is specified (that is,
7942 * @flags is VIR_DOMAIN_AFFECT_CURRENT), then an inactive domain modifies
7943 * persistent setup, while an active domain is hypervisor-dependent on whether
7944 * just live or both live and persistent state is changed.
7945 * Not all hypervisors can support all flag combinations.
7947 * See also virDomainGetEmulatorPinInfo for querying this information.
7949 * Returns 0 in case of success, -1 in case of failure.
7954 virDomainPinEmulator(virDomainPtr domain
, unsigned char *cpumap
,
7955 int maplen
, unsigned int flags
)
7959 VIR_DOMAIN_DEBUG(domain
, "cpumap=%p, maplen=%d, flags=0x%x",
7960 cpumap
, maplen
, flags
);
7962 virResetLastError();
7964 virCheckDomainReturn(domain
, -1);
7965 conn
= domain
->conn
;
7967 virCheckReadOnlyGoto(conn
->flags
, error
);
7969 virCheckNonNullArgGoto(cpumap
, error
);
7970 virCheckPositiveArgGoto(maplen
, error
);
7972 if (conn
->driver
->domainPinEmulator
) {
7974 ret
= conn
->driver
->domainPinEmulator(domain
, cpumap
, maplen
, flags
);
7980 virReportUnsupportedError();
7983 virDispatchError(domain
->conn
);
7989 * virDomainGetEmulatorPinInfo:
7990 * @domain: pointer to domain object, or NULL for Domain0
7991 * @cpumap: pointer to a bit map of real CPUs for all emulator threads of
7992 * this domain (in 8-bit bytes) (OUT)
7993 * There is only one cpumap for all emulator threads.
7995 * @maplen: the number of bytes in one cpumap, from 1 up to size of CPU map.
7997 * @flags: bitwise-OR of virDomainModificationImpact
7998 * Must not be VIR_DOMAIN_AFFECT_LIVE and
7999 * VIR_DOMAIN_AFFECT_CONFIG concurrently.
8001 * Query the CPU affinity setting of all emulator threads of domain, store
8004 * Returns 1 in case of success,
8005 * 0 in case of no emulator threads are pined to pcpus,
8006 * -1 in case of failure.
8011 virDomainGetEmulatorPinInfo(virDomainPtr domain
, unsigned char *cpumap
,
8012 int maplen
, unsigned int flags
)
8016 VIR_DOMAIN_DEBUG(domain
, "cpumap=%p, maplen=%d, flags=0x%x",
8017 cpumap
, maplen
, flags
);
8019 virResetLastError();
8021 virCheckDomainReturn(domain
, -1);
8023 virCheckNonNullArgGoto(cpumap
, error
);
8024 virCheckPositiveArgGoto(maplen
, error
);
8026 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_AFFECT_LIVE
,
8027 VIR_DOMAIN_AFFECT_CONFIG
,
8030 conn
= domain
->conn
;
8032 if (conn
->driver
->domainGetEmulatorPinInfo
) {
8034 ret
= conn
->driver
->domainGetEmulatorPinInfo(domain
, cpumap
,
8041 virReportUnsupportedError();
8044 virDispatchError(domain
->conn
);
8050 * virDomainGetVcpus:
8051 * @domain: pointer to domain object, or NULL for Domain0
8052 * @info: pointer to an array of virVcpuInfo structures (OUT)
8053 * @maxinfo: number of structures in info array
8054 * @cpumaps: pointer to a bit map of real CPUs for all vcpus of this
8055 * domain (in 8-bit bytes) (OUT)
8056 * If cpumaps is NULL, then no cpumap information is returned by the API.
8057 * It's assumed there is <maxinfo> cpumap in cpumaps array.
8058 * The memory allocated to cpumaps must be (maxinfo * maplen) bytes
8059 * (ie: calloc(maxinfo, maplen)).
8060 * One cpumap inside cpumaps has the format described in
8061 * virDomainPinVcpu() API.
8062 * @maplen: number of bytes in one cpumap, from 1 up to size of CPU map in
8063 * underlying virtualization system (Xen...).
8064 * Must be zero when cpumaps is NULL and positive when it is non-NULL.
8066 * Extract information about virtual CPUs of domain, store it in info array
8067 * and also in cpumaps if this pointer isn't NULL. This call may fail
8068 * on an inactive domain.
8070 * See also virDomainGetVcpuPinInfo for querying just cpumaps, including on
8071 * an inactive domain.
8073 * Returns the number of info filled in case of success, -1 in case of failure.
8078 virDomainGetVcpus(virDomainPtr domain
, virVcpuInfoPtr info
, int maxinfo
,
8079 unsigned char *cpumaps
, int maplen
)
8083 VIR_DOMAIN_DEBUG(domain
, "info=%p, maxinfo=%d, cpumaps=%p, maplen=%d",
8084 info
, maxinfo
, cpumaps
, maplen
);
8086 virResetLastError();
8088 virCheckDomainReturn(domain
, -1);
8089 virCheckNonNullArgGoto(info
, error
);
8090 virCheckPositiveArgGoto(maxinfo
, error
);
8092 /* Ensure that domainGetVcpus (aka remoteDomainGetVcpus) does not
8093 try to memcpy anything into a NULL pointer. */
8095 virCheckPositiveArgGoto(maplen
, error
);
8097 virCheckZeroArgGoto(maplen
, error
);
8099 if (cpumaps
&& VIR_INT_MULTIPLY_OVERFLOW(maxinfo
, maplen
)) {
8100 virReportError(VIR_ERR_OVERFLOW
, _("input too large: %1$d * %2$d"),
8105 conn
= domain
->conn
;
8107 if (conn
->driver
->domainGetVcpus
) {
8109 ret
= conn
->driver
->domainGetVcpus(domain
, info
, maxinfo
,
8116 virReportUnsupportedError();
8119 virDispatchError(domain
->conn
);
8125 * virDomainGetMaxVcpus:
8126 * @domain: pointer to domain object
8128 * Provides the maximum number of virtual CPUs supported for
8129 * the guest VM. If the guest is inactive, this is basically
8130 * the same as virConnectGetMaxVcpus(). If the guest is running
8131 * this will reflect the maximum number of virtual CPUs the
8132 * guest was booted with. For more details, see virDomainGetVcpusFlags().
8134 * Returns the maximum of virtual CPU or -1 in case of error.
8139 virDomainGetMaxVcpus(virDomainPtr domain
)
8143 VIR_DOMAIN_DEBUG(domain
);
8145 virResetLastError();
8147 virCheckDomainReturn(domain
, -1);
8148 conn
= domain
->conn
;
8150 if (conn
->driver
->domainGetMaxVcpus
) {
8152 ret
= conn
->driver
->domainGetMaxVcpus(domain
);
8158 virReportUnsupportedError();
8161 virDispatchError(domain
->conn
);
8167 * virDomainGetIOThreadInfo:
8168 * @dom: a domain object
8169 * @info: pointer to an array of virDomainIOThreadInfo structures (OUT)
8170 * @flags: bitwise-OR of virDomainModificationImpact
8171 * Must not be VIR_DOMAIN_AFFECT_LIVE and
8172 * VIR_DOMAIN_AFFECT_CONFIG concurrently.
8174 * Fetch IOThreads of an active domain including the cpumap information to
8175 * determine on which CPU the IOThread has affinity to run.
8177 * Returns the number of IOThreads or -1 in case of error.
8178 * On success, the array of information is stored into @info. The caller is
8179 * responsible for calling virDomainIOThreadInfoFree() on each array element,
8180 * then calling free() on @info. On error, @info is set to NULL.
8185 virDomainGetIOThreadInfo(virDomainPtr dom
,
8186 virDomainIOThreadInfoPtr
**info
,
8189 VIR_DOMAIN_DEBUG(dom
, "info=%p flags=0x%x", info
, flags
);
8191 virResetLastError();
8193 virCheckDomainReturn(dom
, -1);
8194 virCheckNonNullArgGoto(info
, error
);
8197 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_AFFECT_LIVE
,
8198 VIR_DOMAIN_AFFECT_CONFIG
,
8201 if (dom
->conn
->driver
->domainGetIOThreadInfo
) {
8203 ret
= dom
->conn
->driver
->domainGetIOThreadInfo(dom
, info
, flags
);
8209 virReportUnsupportedError();
8212 virDispatchError(dom
->conn
);
8218 * virDomainIOThreadInfoFree:
8219 * @info: pointer to a virDomainIOThreadInfo object
8221 * Frees the memory used by @info.
8226 virDomainIOThreadInfoFree(virDomainIOThreadInfoPtr info
)
8231 g_free(info
->cpumap
);
8237 * virDomainPinIOThread:
8238 * @domain: a domain object
8239 * @iothread_id: the IOThread ID to set the CPU affinity
8240 * @cpumap: pointer to a bit map of real CPUs (in 8-bit bytes) (IN)
8241 * Each bit set to 1 means that corresponding CPU is usable.
8242 * Bytes are stored in little-endian order: CPU0-7, 8-15...
8243 * In each byte, lowest CPU number is least significant bit.
8244 * @maplen: number of bytes in cpumap, from 1 up to size of CPU map in
8245 * underlying virtualization system (Xen...).
8246 * If maplen < size, missing bytes are set to zero.
8247 * If maplen > size, failure code is returned.
8248 * @flags: bitwise-OR of virDomainModificationImpact
8250 * Dynamically change the real CPUs which can be allocated to an IOThread.
8251 * This function may require privileged access to the hypervisor.
8253 * @flags may include VIR_DOMAIN_AFFECT_LIVE or VIR_DOMAIN_AFFECT_CONFIG.
8254 * Both flags may be set.
8255 * If VIR_DOMAIN_AFFECT_LIVE is set, the change affects a running domain
8256 * and may fail if domain is not alive.
8257 * If VIR_DOMAIN_AFFECT_CONFIG is set, the change affects persistent state,
8258 * and will fail for transient domains. If neither flag is specified (that is,
8259 * @flags is VIR_DOMAIN_AFFECT_CURRENT), then an inactive domain modifies
8260 * persistent setup, while an active domain is hypervisor-dependent on whether
8261 * just live or both live and persistent state is changed.
8262 * Not all hypervisors can support all flag combinations.
8264 * See also virDomainGetIOThreadInfo for querying this information.
8266 * Returns 0 in case of success, -1 in case of failure.
8271 virDomainPinIOThread(virDomainPtr domain
,
8272 unsigned int iothread_id
,
8273 unsigned char *cpumap
,
8279 VIR_DOMAIN_DEBUG(domain
, "iothread_id=%u, cpumap=%p, maplen=%d",
8280 iothread_id
, cpumap
, maplen
);
8282 virResetLastError();
8284 virCheckDomainReturn(domain
, -1);
8285 conn
= domain
->conn
;
8287 virCheckReadOnlyGoto(conn
->flags
, error
);
8288 virCheckNonNullArgGoto(cpumap
, error
);
8289 virCheckPositiveArgGoto(maplen
, error
);
8291 if (conn
->driver
->domainPinIOThread
) {
8293 ret
= conn
->driver
->domainPinIOThread(domain
, iothread_id
,
8294 cpumap
, maplen
, flags
);
8300 virReportUnsupportedError();
8303 virDispatchError(domain
->conn
);
8309 * virDomainAddIOThread:
8310 * @domain: a domain object
8311 * @iothread_id: the specific IOThread ID value to add
8312 * @flags: bitwise-OR of virDomainModificationImpact
8314 * Dynamically add an IOThread to the domain. It is left up to the
8315 * underlying virtual hypervisor to determine the valid range for an
8316 * @iothread_id and determining whether the @iothread_id already exists.
8318 * Note that this call can fail if the underlying virtualization hypervisor
8319 * does not support it or if growing the number is arbitrarily limited.
8320 * This function requires privileged access to the hypervisor.
8322 * @flags may include VIR_DOMAIN_AFFECT_LIVE or VIR_DOMAIN_AFFECT_CONFIG.
8323 * Both flags may be set.
8324 * If VIR_DOMAIN_AFFECT_LIVE is set, the change affects a running domain
8325 * and may fail if domain is not alive.
8326 * If VIR_DOMAIN_AFFECT_CONFIG is set, the change affects persistent state,
8327 * and will fail for transient domains. If neither flag is specified (that is,
8328 * @flags is VIR_DOMAIN_AFFECT_CURRENT), then an inactive domain modifies
8329 * persistent setup, while an active domain is hypervisor-dependent on whether
8330 * just live or both live and persistent state is changed.
8332 * Returns 0 in case of success, -1 in case of failure.
8337 virDomainAddIOThread(virDomainPtr domain
,
8338 unsigned int iothread_id
,
8343 VIR_DOMAIN_DEBUG(domain
, "iothread_id=%u, flags=0x%x",
8344 iothread_id
, flags
);
8346 virResetLastError();
8348 virCheckDomainReturn(domain
, -1);
8349 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
8351 conn
= domain
->conn
;
8353 if (conn
->driver
->domainAddIOThread
) {
8355 ret
= conn
->driver
->domainAddIOThread(domain
, iothread_id
, flags
);
8361 virReportUnsupportedError();
8364 virDispatchError(domain
->conn
);
8370 * virDomainDelIOThread:
8371 * @domain: a domain object
8372 * @iothread_id: the specific IOThread ID value to delete
8373 * @flags: bitwise-OR of virDomainModificationImpact
8375 * Dynamically delete an IOThread from the domain. The @iothread_id to be
8376 * deleted must not have a resource associated with it and can be any of
8377 * the currently valid IOThread ID's.
8379 * Note that this call can fail if the underlying virtualization hypervisor
8380 * does not support it or if reducing the number is arbitrarily limited.
8381 * This function requires privileged access to the hypervisor.
8383 * @flags may include VIR_DOMAIN_AFFECT_LIVE or VIR_DOMAIN_AFFECT_CONFIG.
8384 * Both flags may be set.
8385 * If VIR_DOMAIN_AFFECT_LIVE is set, the change affects a running domain
8386 * and may fail if domain is not alive.
8387 * If VIR_DOMAIN_AFFECT_CONFIG is set, the change affects persistent state,
8388 * and will fail for transient domains. If neither flag is specified (that is,
8389 * @flags is VIR_DOMAIN_AFFECT_CURRENT), then an inactive domain modifies
8390 * persistent setup, while an active domain is hypervisor-dependent on whether
8391 * just live or both live and persistent state is changed.
8393 * Returns 0 in case of success, -1 in case of failure.
8398 virDomainDelIOThread(virDomainPtr domain
,
8399 unsigned int iothread_id
,
8404 VIR_DOMAIN_DEBUG(domain
, "iothread_id=%u, flags=0x%x", iothread_id
, flags
);
8406 virResetLastError();
8408 virCheckDomainReturn(domain
, -1);
8409 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
8410 virCheckNonZeroArgGoto(iothread_id
, error
);
8412 conn
= domain
->conn
;
8414 if (conn
->driver
->domainDelIOThread
) {
8416 ret
= conn
->driver
->domainDelIOThread(domain
, iothread_id
, flags
);
8422 virReportUnsupportedError();
8425 virDispatchError(domain
->conn
);
8431 * virDomainSetIOThreadParams:
8432 * @domain: a domain object
8433 * @iothread_id: the specific IOThread ID value to add
8434 * @params: pointer to IOThread parameter objects
8435 * @nparams: number of IOThread parameters
8436 * @flags: bitwise-OR of virDomainModificationImpact and virTypedParameterFlags
8438 * Dynamically set IOThread parameters to the domain. It is left up to
8439 * the underlying virtual hypervisor to determine the valid range for an
8440 * @iothread_id, determining whether the @iothread_id already exists, and
8441 * determining the validity of the provided param values.
8443 * See VIR_DOMAIN_IOTHREAD_* for detailed description of accepted IOThread
8446 * Since the purpose of this API is to dynamically modify the IOThread
8447 * @flags should only include the VIR_DOMAIN_AFFECT_CURRENT and/or
8448 * VIR_DOMAIN_AFFECT_LIVE virDomainMemoryModFlags. Setting other flags
8449 * may cause errors from the hypervisor.
8451 * Note that this call can fail if the underlying virtualization hypervisor
8452 * does not support it or does not support setting the provided values.
8454 * This function requires privileged access to the hypervisor.
8456 * Returns 0 in case of success, -1 in case of failure.
8461 virDomainSetIOThreadParams(virDomainPtr domain
,
8462 unsigned int iothread_id
,
8463 virTypedParameterPtr params
,
8469 VIR_DOMAIN_DEBUG(domain
, "iothread_id=%u, params=%p, nparams=%d, flags=0x%x",
8470 iothread_id
, params
, nparams
, flags
);
8471 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
8473 virResetLastError();
8475 virCheckDomainReturn(domain
, -1);
8476 conn
= domain
->conn
;
8478 virCheckReadOnlyGoto(conn
->flags
, error
);
8479 virCheckNonNullArgGoto(params
, error
);
8480 virCheckPositiveArgGoto(nparams
, error
);
8482 if (virTypedParameterValidateSet(conn
, params
, nparams
) < 0)
8485 if (conn
->driver
->domainSetIOThreadParams
) {
8487 ret
= conn
->driver
->domainSetIOThreadParams(domain
, iothread_id
,
8488 params
, nparams
, flags
);
8494 virReportUnsupportedError();
8497 virDispatchError(domain
->conn
);
8503 * virDomainGetSecurityLabel:
8504 * @domain: a domain object
8505 * @seclabel: pointer to a virSecurityLabel structure
8507 * Extract security label of an active domain. The 'label' field
8508 * in the @seclabel argument will be initialized to the empty
8509 * string if the domain is not running under a security model.
8511 * Returns 0 in case of success, -1 in case of failure
8516 virDomainGetSecurityLabel(virDomainPtr domain
, virSecurityLabelPtr seclabel
)
8520 VIR_DOMAIN_DEBUG(domain
, "seclabel=%p", seclabel
);
8522 virResetLastError();
8524 virCheckDomainReturn(domain
, -1);
8525 conn
= domain
->conn
;
8527 virCheckNonNullArgGoto(seclabel
, error
);
8529 if (conn
->driver
->domainGetSecurityLabel
) {
8531 ret
= conn
->driver
->domainGetSecurityLabel(domain
, seclabel
);
8537 virReportUnsupportedError();
8540 virDispatchError(domain
->conn
);
8546 * virDomainGetSecurityLabelList:
8547 * @domain: a domain object
8548 * @seclabels: will be auto-allocated and filled with domains' security labels.
8549 * Caller must free memory on return.
8551 * Extract the security labels of an active domain. The 'label' field
8552 * in the @seclabels argument will be initialized to the empty
8553 * string if the domain is not running under a security model.
8555 * Returns number of elements in @seclabels on success, -1 in case of failure.
8560 virDomainGetSecurityLabelList(virDomainPtr domain
,
8561 virSecurityLabelPtr
* seclabels
)
8565 VIR_DOMAIN_DEBUG(domain
, "seclabels=%p", seclabels
);
8567 virResetLastError();
8569 virCheckDomainReturn(domain
, -1);
8571 virCheckNonNullArgGoto(seclabels
, error
);
8573 conn
= domain
->conn
;
8575 if (conn
->driver
->domainGetSecurityLabelList
) {
8577 ret
= conn
->driver
->domainGetSecurityLabelList(domain
, seclabels
);
8583 virReportUnsupportedError();
8586 virDispatchError(domain
->conn
);
8592 * virDomainSetMetadata:
8593 * @domain: a domain object
8594 * @type: type of metadata, from virDomainMetadataType
8595 * @metadata: new metadata text
8596 * @key: XML namespace key, or NULL
8597 * @uri: XML namespace URI, or NULL
8598 * @flags: bitwise-OR of virDomainModificationImpact
8600 * Sets the appropriate domain element given by @type to the
8601 * value of @metadata. A @type of VIR_DOMAIN_METADATA_DESCRIPTION
8602 * is free-form text; VIR_DOMAIN_METADATA_TITLE is free-form, but no
8603 * newlines are permitted, and should be short (although the length is
8604 * not enforced). For these two options @key and @uri are irrelevant and
8605 * must be set to NULL.
8607 * For type VIR_DOMAIN_METADATA_ELEMENT @metadata must be well-formed
8608 * XML belonging to namespace defined by @uri with local name @key.
8610 * Passing NULL for @metadata says to remove that element from the
8611 * domain XML (passing the empty string leaves the element present).
8613 * The resulting metadata will be present in virDomainGetXMLDesc(),
8614 * as well as quick access through virDomainGetMetadata().
8616 * @flags controls whether the live domain, persistent configuration,
8617 * or both will be modified.
8619 * Returns 0 on success, -1 in case of failure.
8624 virDomainSetMetadata(virDomainPtr domain
,
8626 const char *metadata
,
8633 VIR_DOMAIN_DEBUG(domain
,
8634 "type=%d, metadata='%s', key='%s', uri='%s', flags=0x%x",
8635 type
, NULLSTR(metadata
), NULLSTR(key
), NULLSTR(uri
),
8638 virResetLastError();
8640 virCheckDomainReturn(domain
, -1);
8641 conn
= domain
->conn
;
8643 virCheckReadOnlyGoto(conn
->flags
, error
);
8646 case VIR_DOMAIN_METADATA_TITLE
:
8647 if (metadata
&& strchr(metadata
, '\n')) {
8648 virReportInvalidArg(metadata
, "%s",
8649 _("metadata title can't contain newlines"));
8653 case VIR_DOMAIN_METADATA_DESCRIPTION
:
8654 virCheckNullArgGoto(uri
, error
);
8655 virCheckNullArgGoto(key
, error
);
8657 case VIR_DOMAIN_METADATA_ELEMENT
:
8658 virCheckNonNullArgGoto(uri
, error
);
8660 virCheckNonNullArgGoto(key
, error
);
8663 /* For future expansion */
8667 if (conn
->driver
->domainSetMetadata
) {
8669 ret
= conn
->driver
->domainSetMetadata(domain
, type
, metadata
, key
, uri
,
8676 virReportUnsupportedError();
8679 virDispatchError(domain
->conn
);
8685 * virDomainGetMetadata:
8686 * @domain: a domain object
8687 * @type: type of metadata, from virDomainMetadataType
8688 * @uri: XML namespace identifier
8689 * @flags: bitwise-OR of virDomainModificationImpact
8691 * Retrieves the appropriate domain element given by @type.
8692 * If VIR_DOMAIN_METADATA_ELEMENT is requested parameter @uri
8693 * must be set to the name of the namespace the requested elements
8694 * belong to, otherwise must be NULL.
8696 * If an element of the domain XML is not present, the resulting
8697 * error will be VIR_ERR_NO_DOMAIN_METADATA. This method forms
8698 * a shortcut for seeing information from virDomainSetMetadata()
8699 * without having to go through virDomainGetXMLDesc().
8701 * @flags controls whether the live domain or persistent
8702 * configuration will be queried.
8704 * Returns the metadata string on success (caller must free),
8705 * or NULL in case of failure.
8710 virDomainGetMetadata(virDomainPtr domain
,
8717 VIR_DOMAIN_DEBUG(domain
, "type=%d, uri='%s', flags=0x%x",
8718 type
, NULLSTR(uri
), flags
);
8720 virResetLastError();
8722 virCheckDomainReturn(domain
, NULL
);
8724 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_AFFECT_LIVE
,
8725 VIR_DOMAIN_AFFECT_CONFIG
,
8729 case VIR_DOMAIN_METADATA_TITLE
:
8730 case VIR_DOMAIN_METADATA_DESCRIPTION
:
8731 virCheckNullArgGoto(uri
, error
);
8733 case VIR_DOMAIN_METADATA_ELEMENT
:
8734 virCheckNonNullArgGoto(uri
, error
);
8737 /* For future expansion */
8741 conn
= domain
->conn
;
8743 if (conn
->driver
->domainGetMetadata
) {
8745 if (!(ret
= conn
->driver
->domainGetMetadata(domain
, type
, uri
, flags
)))
8750 virReportUnsupportedError();
8753 virDispatchError(domain
->conn
);
8759 * virDomainAttachDevice:
8760 * @domain: pointer to domain object
8761 * @xml: pointer to XML description of one device
8763 * Create a virtual device attachment to backend. This function,
8764 * having hotplug semantics, is only allowed on an active domain.
8766 * For compatibility, this method can also be used to change the media
8767 * in an existing CDROM/Floppy device, however, applications are
8768 * recommended to use the virDomainUpdateDeviceFlags method instead.
8770 * Be aware that hotplug changes might not persist across a domain going
8771 * into S4 state (also known as hibernation) unless you also modify the
8772 * persistent domain definition.
8774 * Returns 0 in case of success, -1 in case of failure.
8779 virDomainAttachDevice(virDomainPtr domain
, const char *xml
)
8783 VIR_DOMAIN_DEBUG(domain
, "xml=%s", xml
);
8785 virResetLastError();
8787 virCheckDomainReturn(domain
, -1);
8788 conn
= domain
->conn
;
8790 virCheckNonNullArgGoto(xml
, error
);
8791 virCheckReadOnlyGoto(conn
->flags
, error
);
8793 if (conn
->driver
->domainAttachDevice
) {
8795 ret
= conn
->driver
->domainAttachDevice(domain
, xml
);
8801 virReportUnsupportedError();
8804 virDispatchError(domain
->conn
);
8810 * virDomainAttachDeviceFlags:
8811 * @domain: pointer to domain object
8812 * @xml: pointer to XML description of one device
8813 * @flags: bitwise-OR of virDomainDeviceModifyFlags
8815 * Attach a virtual device to a domain, using the flags parameter
8816 * to control how the device is attached. VIR_DOMAIN_AFFECT_CURRENT
8817 * specifies that the device allocation is made based on current domain
8818 * state. VIR_DOMAIN_AFFECT_LIVE specifies that the device shall be
8819 * allocated to the active domain instance only and is not added to the
8820 * persisted domain configuration. VIR_DOMAIN_AFFECT_CONFIG
8821 * specifies that the device shall be allocated to the persisted domain
8822 * configuration only. Note that the target hypervisor must return an
8823 * error if unable to satisfy flags. E.g. the hypervisor driver will
8824 * return failure if LIVE is specified but it only supports modifying the
8825 * persisted device allocation.
8827 * For compatibility, this method can also be used to change the media
8828 * in an existing CDROM/Floppy device, however, applications are
8829 * recommended to use the virDomainUpdateDeviceFlag method instead.
8831 * Be aware that hotplug changes might not persist across a domain going
8832 * into S4 state (also known as hibernation) unless you also modify the
8833 * persistent domain definition.
8835 * Returns 0 in case of success, -1 in case of failure.
8840 virDomainAttachDeviceFlags(virDomainPtr domain
,
8841 const char *xml
, unsigned int flags
)
8845 VIR_DOMAIN_DEBUG(domain
, "xml=%s, flags=0x%x", xml
, flags
);
8847 virResetLastError();
8849 virCheckDomainReturn(domain
, -1);
8850 conn
= domain
->conn
;
8852 virCheckNonNullArgGoto(xml
, error
);
8853 virCheckReadOnlyGoto(conn
->flags
, error
);
8855 if (conn
->driver
->domainAttachDeviceFlags
) {
8857 ret
= conn
->driver
->domainAttachDeviceFlags(domain
, xml
, flags
);
8863 virReportUnsupportedError();
8866 virDispatchError(domain
->conn
);
8872 * virDomainDetachDevice:
8873 * @domain: pointer to domain object
8874 * @xml: pointer to XML description of one device
8876 * This is an equivalent of virDomainDetachDeviceFlags() when called with
8877 * @flags parameter set to VIR_DOMAIN_AFFECT_LIVE.
8879 * See virDomainDetachDeviceFlags() for more details.
8881 * Returns 0 in case of success, -1 in case of failure.
8886 virDomainDetachDevice(virDomainPtr domain
, const char *xml
)
8890 VIR_DOMAIN_DEBUG(domain
, "xml=%s", xml
);
8892 virResetLastError();
8894 virCheckDomainReturn(domain
, -1);
8895 conn
= domain
->conn
;
8897 virCheckNonNullArgGoto(xml
, error
);
8898 virCheckReadOnlyGoto(conn
->flags
, error
);
8900 if (conn
->driver
->domainDetachDevice
) {
8902 ret
= conn
->driver
->domainDetachDevice(domain
, xml
);
8908 virReportUnsupportedError();
8911 virDispatchError(domain
->conn
);
8917 * virDomainDetachDeviceFlags:
8918 * @domain: pointer to domain object
8919 * @xml: pointer to XML description of one device
8920 * @flags: bitwise-OR of virDomainDeviceModifyFlags
8922 * Detach a virtual device from a domain, using the flags parameter
8923 * to control how the device is detached. VIR_DOMAIN_AFFECT_CURRENT
8924 * specifies that the device allocation is removed based on current domain
8925 * state. VIR_DOMAIN_AFFECT_LIVE specifies that the device shall be
8926 * deallocated from the active domain instance only and is not from the
8927 * persisted domain configuration. VIR_DOMAIN_AFFECT_CONFIG
8928 * specifies that the device shall be deallocated from the persisted domain
8929 * configuration only. Note that the target hypervisor must return an
8930 * error if unable to satisfy flags. E.g. the hypervisor driver will
8931 * return failure if LIVE is specified but it only supports removing the
8932 * persisted device allocation.
8934 * Some hypervisors may prevent this operation if there is a current
8935 * block job running operation on the device being detached; in that case,
8936 * use virDomainBlockJobAbort() to stop the block job first.
8938 * Beware that depending on the hypervisor and device type, detaching a device
8939 * from a running domain may be asynchronous. That is, calling
8940 * virDomainDetachDeviceFlags may just request device removal while the device
8941 * is actually removed later (in cooperation with a guest OS). Previously,
8942 * this fact was ignored and the device could have been removed from domain
8943 * configuration before it was actually removed by the hypervisor causing
8944 * various failures on subsequent operations. To check whether the device was
8945 * successfully removed, either recheck domain configuration using
8946 * virDomainGetXMLDesc() or add a handler for the VIR_DOMAIN_EVENT_ID_DEVICE_REMOVED
8947 * event. In case the device is already gone when virDomainDetachDeviceFlags
8948 * returns, the event is delivered before this API call ends. To help existing
8949 * clients work better in most cases, this API will try to transform an
8950 * asynchronous device removal that finishes shortly after the request into
8951 * a synchronous removal. In other words, this API may wait a bit for the
8952 * removal to complete in case it was not synchronous.
8954 * Be aware that hotplug changes might not persist across a domain going
8955 * into S4 state (also known as hibernation) unless you also modify the
8956 * persistent domain definition.
8958 * The supplied XML description of the device should be as specific
8959 * as its definition in the domain XML. The set of attributes used
8960 * to match the device are internal to the drivers. Using a partial definition,
8961 * or attempting to detach a device that is not present in the domain XML,
8962 * but shares some specific attributes with one that is present,
8963 * may lead to unexpected results.
8965 * Returns 0 in case of success, -1 in case of failure.
8970 virDomainDetachDeviceFlags(virDomainPtr domain
,
8971 const char *xml
, unsigned int flags
)
8975 VIR_DOMAIN_DEBUG(domain
, "xml=%s, flags=0x%x", xml
, flags
);
8977 virResetLastError();
8979 virCheckDomainReturn(domain
, -1);
8980 conn
= domain
->conn
;
8982 virCheckNonNullArgGoto(xml
, error
);
8983 virCheckReadOnlyGoto(conn
->flags
, error
);
8985 if (conn
->driver
->domainDetachDeviceFlags
) {
8987 ret
= conn
->driver
->domainDetachDeviceFlags(domain
, xml
, flags
);
8993 virReportUnsupportedError();
8996 virDispatchError(domain
->conn
);
9002 * virDomainUpdateDeviceFlags:
9003 * @domain: pointer to domain object
9004 * @xml: pointer to XML description of one device
9005 * @flags: bitwise-OR of virDomainDeviceModifyFlags
9007 * Change a virtual device on a domain, using the flags parameter
9008 * to control how the device is changed. VIR_DOMAIN_AFFECT_CURRENT
9009 * specifies that the device change is made based on current domain
9010 * state. VIR_DOMAIN_AFFECT_LIVE specifies that the device shall be
9011 * changed on the active domain instance only and is not added to the
9012 * persisted domain configuration. VIR_DOMAIN_AFFECT_CONFIG
9013 * specifies that the device shall be changed on the persisted domain
9014 * configuration only. Note that the target hypervisor must return an
9015 * error if unable to satisfy flags. E.g. the hypervisor driver will
9016 * return failure if LIVE is specified but it only supports modifying the
9017 * persisted device allocation.
9019 * This method is used for actions such changing CDROM/Floppy device
9020 * media, altering the graphics configuration such as password,
9021 * reconfiguring the NIC device backend connectivity, etc.
9023 * The supplied XML description of the device should contain all
9024 * the information that is found in the corresponding domain XML.
9025 * Leaving out any piece of information may be treated as a
9026 * request for its removal, which may be denied. For instance,
9027 * when users want to change CDROM media only for live XML, they
9028 * must provide live disk XML as found in the corresponding live
9029 * domain XML with only the disk path changed.
9031 * Returns 0 in case of success, -1 in case of failure.
9036 virDomainUpdateDeviceFlags(virDomainPtr domain
,
9037 const char *xml
, unsigned int flags
)
9041 VIR_DOMAIN_DEBUG(domain
, "xml=%s, flags=0x%x", xml
, flags
);
9043 virResetLastError();
9045 virCheckDomainReturn(domain
, -1);
9046 conn
= domain
->conn
;
9048 virCheckNonNullArgGoto(xml
, error
);
9049 virCheckReadOnlyGoto(conn
->flags
, error
);
9051 if (conn
->driver
->domainUpdateDeviceFlags
) {
9053 ret
= conn
->driver
->domainUpdateDeviceFlags(domain
, xml
, flags
);
9059 virReportUnsupportedError();
9062 virDispatchError(domain
->conn
);
9068 * virDomainDetachDeviceAlias:
9069 * @domain: pointer to a domain object
9070 * @alias: device alias
9071 * @flags: bitwise-OR of virDomainDeviceModifyFlags
9073 * Detach a virtual device from a domain, using the alias to
9074 * specify the device. The value of @flags should be either
9075 * VIR_DOMAIN_AFFECT_CURRENT, or a bitwise-or of values from
9076 * VIR_DOMAIN_AFFECT_LIVE and VIR_DOMAIN_AFFECT_CURRENT, although
9077 * hypervisors vary in which flags are supported.
9079 * In contrast to virDomainDetachDeviceFlags() this API is
9080 * asynchronous - it returns immediately after sending the detach
9081 * request to the hypervisor. It's caller's responsibility to
9082 * wait for VIR_DOMAIN_EVENT_ID_DEVICE_REMOVED event to signal
9083 * actual device removal or for
9084 * VIR_DOMAIN_EVENT_ID_DEVICE_REMOVAL_FAILED to signal rejected
9087 * Returns 0 in case of success, -1 in case of failure.
9092 virDomainDetachDeviceAlias(virDomainPtr domain
,
9098 VIR_DOMAIN_DEBUG(domain
, "alias=%s, flags=0x%x", alias
, flags
);
9100 virResetLastError();
9102 virCheckDomainReturn(domain
, -1);
9103 conn
= domain
->conn
;
9105 virCheckNonNullArgGoto(alias
, error
);
9106 virCheckReadOnlyGoto(conn
->flags
, error
);
9108 if (conn
->driver
->domainDetachDeviceAlias
) {
9110 ret
= conn
->driver
->domainDetachDeviceAlias(domain
, alias
, flags
);
9116 virReportUnsupportedError();
9119 virDispatchError(domain
->conn
);
9125 * virConnectDomainEventRegister:
9126 * @conn: pointer to the connection
9127 * @cb: callback to the function handling domain events
9128 * @opaque: opaque data to pass on to the callback
9129 * @freecb: optional function to deallocate opaque when not used anymore
9131 * Adds a callback to receive notifications of domain lifecycle events
9132 * occurring on a connection. This function requires that an event loop
9133 * has been previously registered with virEventRegisterImpl() or
9134 * virEventRegisterDefaultImpl().
9136 * Use of this method is no longer recommended. Instead applications
9137 * should try virConnectDomainEventRegisterAny() which has a more flexible
9140 * The virDomainPtr object handle passed into the callback upon delivery
9141 * of an event is only valid for the duration of execution of the callback.
9142 * If the callback wishes to keep the domain object after the callback returns,
9143 * it shall take a reference to it, by calling virDomainRef.
9144 * The reference can be released once the object is no longer required
9145 * by calling virDomainFree.
9147 * Returns 0 on success, -1 on failure. Older versions of some hypervisors
9148 * sometimes returned a positive number on success, but without any reliable
9149 * semantics on what that number represents.
9154 virConnectDomainEventRegister(virConnectPtr conn
,
9155 virConnectDomainEventCallback cb
,
9157 virFreeCallback freecb
)
9159 VIR_DEBUG("conn=%p, cb=%p, opaque=%p, freecb=%p", conn
, cb
, opaque
, freecb
);
9160 virResetLastError();
9162 virCheckConnectReturn(conn
, -1);
9163 virCheckNonNullArgGoto(cb
, error
);
9165 if (conn
->driver
&& conn
->driver
->connectDomainEventRegister
) {
9167 ret
= conn
->driver
->connectDomainEventRegister(conn
, cb
, opaque
, freecb
);
9173 virReportUnsupportedError();
9175 virDispatchError(conn
);
9181 * virConnectDomainEventDeregister:
9182 * @conn: pointer to the connection
9183 * @cb: callback to the function handling domain events
9185 * Removes a callback previously registered with the
9186 * virConnectDomainEventRegister() function.
9188 * Use of this method is no longer recommended. Instead applications
9189 * should try virConnectDomainEventDeregisterAny() which has a more flexible
9192 * Returns 0 on success, -1 on failure. Older versions of some hypervisors
9193 * sometimes returned a positive number on success, but without any reliable
9194 * semantics on what that number represents.
9199 virConnectDomainEventDeregister(virConnectPtr conn
,
9200 virConnectDomainEventCallback cb
)
9202 VIR_DEBUG("conn=%p, cb=%p", conn
, cb
);
9204 virResetLastError();
9206 virCheckConnectReturn(conn
, -1);
9207 virCheckNonNullArgGoto(cb
, error
);
9209 if (conn
->driver
&& conn
->driver
->connectDomainEventDeregister
) {
9211 ret
= conn
->driver
->connectDomainEventDeregister(conn
, cb
);
9217 virReportUnsupportedError();
9219 virDispatchError(conn
);
9225 * virDomainIsActive:
9226 * @dom: pointer to the domain object
9228 * Determine if the domain is currently running
9230 * Returns 1 if running, 0 if inactive, -1 on error
9235 virDomainIsActive(virDomainPtr dom
)
9237 VIR_DEBUG("dom=%p", dom
);
9239 virResetLastError();
9241 virCheckDomainReturn(dom
, -1);
9243 if (dom
->conn
->driver
->domainIsActive
) {
9245 ret
= dom
->conn
->driver
->domainIsActive(dom
);
9251 virReportUnsupportedError();
9253 virDispatchError(dom
->conn
);
9259 * virDomainIsPersistent:
9260 * @dom: pointer to the domain object
9262 * Determine if the domain has a persistent configuration
9263 * which means it will still exist after shutting down
9265 * Returns 1 if persistent, 0 if transient, -1 on error
9270 virDomainIsPersistent(virDomainPtr dom
)
9272 VIR_DOMAIN_DEBUG(dom
);
9274 virResetLastError();
9276 virCheckDomainReturn(dom
, -1);
9278 if (dom
->conn
->driver
->domainIsPersistent
) {
9280 ret
= dom
->conn
->driver
->domainIsPersistent(dom
);
9286 virReportUnsupportedError();
9288 virDispatchError(dom
->conn
);
9294 * @dom: pointer to the domain object
9295 * @new_name: new domain name
9296 * @flags: extra flags; not used yet, so callers should always pass 0
9298 * Rename a domain. New domain name is specified in the second
9299 * argument. Depending on each driver implementation it may be
9300 * required that domain is in a specific state.
9302 * There might be some attributes and/or elements in domain XML that if no
9303 * value provided at XML defining time, libvirt will derive their value from
9304 * the domain name. These are not updated by this API. Users are strongly
9305 * advised to change these after the rename was successful.
9307 * Returns 0 if successfully renamed, -1 on error
9312 virDomainRename(virDomainPtr dom
,
9313 const char *new_name
,
9316 VIR_DEBUG("dom=%p, new_name=%s", dom
, NULLSTR(new_name
));
9318 virResetLastError();
9319 virCheckDomainReturn(dom
, -1);
9320 virCheckNonEmptyStringArgGoto(new_name
, error
);
9321 virCheckReadOnlyGoto(dom
->conn
->flags
, error
);
9323 if (dom
->conn
->driver
->domainRename
) {
9324 int ret
= dom
->conn
->driver
->domainRename(dom
, new_name
, flags
);
9330 virReportUnsupportedError();
9332 virDispatchError(dom
->conn
);
9337 * virDomainIsUpdated:
9338 * @dom: pointer to the domain object
9340 * Determine if the domain has been updated.
9342 * Returns 1 if updated, 0 if not, -1 on error
9347 virDomainIsUpdated(virDomainPtr dom
)
9349 VIR_DOMAIN_DEBUG(dom
);
9351 virResetLastError();
9353 virCheckDomainReturn(dom
, -1);
9355 if (dom
->conn
->driver
->domainIsUpdated
) {
9357 ret
= dom
->conn
->driver
->domainIsUpdated(dom
);
9363 virReportUnsupportedError();
9365 virDispatchError(dom
->conn
);
9371 * virDomainGetJobInfo:
9372 * @domain: a domain object
9373 * @info: pointer to a virDomainJobInfo structure allocated by the user
9375 * Extract information about progress of a background job on a domain.
9376 * Will return an error if the domain is not active.
9378 * This function returns a limited amount of information in comparison
9379 * to virDomainGetJobStats().
9381 * Returns 0 in case of success and -1 in case of failure.
9386 virDomainGetJobInfo(virDomainPtr domain
, virDomainJobInfoPtr info
)
9390 VIR_DOMAIN_DEBUG(domain
, "info=%p", info
);
9392 virResetLastError();
9395 memset(info
, 0, sizeof(*info
));
9397 virCheckDomainReturn(domain
, -1);
9398 virCheckNonNullArgGoto(info
, error
);
9400 conn
= domain
->conn
;
9402 if (conn
->driver
->domainGetJobInfo
) {
9404 ret
= conn
->driver
->domainGetJobInfo(domain
, info
);
9410 virReportUnsupportedError();
9413 virDispatchError(domain
->conn
);
9419 * virDomainGetJobStats:
9420 * @domain: a domain object
9421 * @type: where to store the job type (one of virDomainJobType)
9422 * @params: where to store job statistics
9423 * @nparams: number of items in @params
9424 * @flags: bitwise-OR of virDomainGetJobStatsFlags
9426 * Extract information about progress of a background job on a domain.
9427 * Will return an error if the domain is not active. The function returns
9428 * a superset of progress information provided by virDomainGetJobInfo.
9429 * Possible fields returned in @params are defined by VIR_DOMAIN_JOB_*
9430 * macros and new fields will likely be introduced in the future so callers
9431 * may receive fields that they do not understand in case they talk to a
9434 * When @flags contains VIR_DOMAIN_JOB_STATS_COMPLETED, the function will
9435 * return statistics about a recently completed job. Specifically, this
9436 * flag may be used to query statistics of a completed incoming pre-copy
9437 * migration (statistics for post-copy migration are only available on the
9438 * source host). Statistics of a completed job are automatically destroyed
9439 * once read (unless the VIR_DOMAIN_JOB_STATS_COMPLETED_KEEP is used as well)
9440 * or when libvirtd is restarted. Note that time information
9441 * returned for completed migrations may be completely irrelevant unless both
9442 * source and destination hosts have synchronized time (i.e., NTP daemon is
9443 * running on both of them). The statistics of a completed job can also be
9444 * obtained by listening to a VIR_DOMAIN_EVENT_ID_JOB_COMPLETED event (on the
9445 * source host in case of a migration job).
9447 * Returns 0 in case of success and -1 in case of failure.
9452 virDomainGetJobStats(virDomainPtr domain
,
9454 virTypedParameterPtr
*params
,
9460 VIR_DOMAIN_DEBUG(domain
, "type=%p, params=%p, nparams=%p, flags=0x%x",
9461 type
, params
, nparams
, flags
);
9463 virResetLastError();
9465 virCheckDomainReturn(domain
, -1);
9466 virCheckNonNullArgGoto(type
, error
);
9467 virCheckNonNullArgGoto(params
, error
);
9468 virCheckNonNullArgGoto(nparams
, error
);
9469 VIR_REQUIRE_FLAG_GOTO(VIR_DOMAIN_JOB_STATS_KEEP_COMPLETED
,
9470 VIR_DOMAIN_JOB_STATS_COMPLETED
,
9473 conn
= domain
->conn
;
9475 if (conn
->driver
->domainGetJobStats
) {
9477 ret
= conn
->driver
->domainGetJobStats(domain
, type
, params
,
9484 virReportUnsupportedError();
9487 virDispatchError(domain
->conn
);
9493 * virDomainAbortJob:
9494 * @domain: a domain object
9496 * Requests that the current background job be aborted at the
9497 * soonest opportunity. In case the job is a migration in a post-copy mode,
9498 * virDomainAbortJob will report an error (see virDomainMigrateStartPostCopy
9499 * for more details).
9501 * Returns 0 in case of success and -1 in case of failure.
9506 virDomainAbortJob(virDomainPtr domain
)
9510 VIR_DOMAIN_DEBUG(domain
);
9512 virResetLastError();
9514 virCheckDomainReturn(domain
, -1);
9515 conn
= domain
->conn
;
9517 virCheckReadOnlyGoto(conn
->flags
, error
);
9519 if (conn
->driver
->domainAbortJob
) {
9521 ret
= conn
->driver
->domainAbortJob(domain
);
9527 virReportUnsupportedError();
9530 virDispatchError(conn
);
9536 * virDomainAbortJobFlags:
9537 * @domain: a domain object
9538 * @flags: bitwise-OR of virDomainAbortJobFlagsValues
9540 * Requests that the current background job be aborted at the
9541 * soonest opportunity. In case the job is a migration in a post-copy mode,
9542 * this function will report an error unless VIR_DOMAIN_ABORT_JOB_POSTCOPY
9543 * flag is used (see virDomainMigrateStartPostCopy for more details).
9545 * Returns 0 in case of success and -1 in case of failure.
9550 virDomainAbortJobFlags(virDomainPtr domain
,
9555 VIR_DOMAIN_DEBUG(domain
);
9557 virResetLastError();
9559 virCheckDomainReturn(domain
, -1);
9560 conn
= domain
->conn
;
9562 virCheckReadOnlyGoto(conn
->flags
, error
);
9564 if (conn
->driver
->domainAbortJobFlags
) {
9566 ret
= conn
->driver
->domainAbortJobFlags(domain
, flags
);
9572 virReportUnsupportedError();
9575 virDispatchError(conn
);
9581 * virDomainMigrateSetMaxDowntime:
9582 * @domain: a domain object
9583 * @downtime: maximum tolerable downtime for live migration, in milliseconds
9584 * @flags: extra flags; not used yet, so callers should always pass 0
9586 * Sets maximum tolerable time for which the domain is allowed to be paused
9587 * at the end of live migration. It's supposed to be called while the domain is
9588 * being live-migrated as a reaction to migration progress.
9590 * Returns 0 in case of success, -1 otherwise.
9595 virDomainMigrateSetMaxDowntime(virDomainPtr domain
,
9596 unsigned long long downtime
,
9601 VIR_DOMAIN_DEBUG(domain
, "downtime=%llu, flags=0x%x", downtime
, flags
);
9603 virResetLastError();
9605 virCheckDomainReturn(domain
, -1);
9606 conn
= domain
->conn
;
9608 virCheckReadOnlyGoto(conn
->flags
, error
);
9610 if (conn
->driver
->domainMigrateSetMaxDowntime
) {
9611 if (conn
->driver
->domainMigrateSetMaxDowntime(domain
, downtime
, flags
) < 0)
9616 virReportUnsupportedError();
9618 virDispatchError(conn
);
9624 * virDomainMigrateGetMaxDowntime:
9625 * @domain: a domain object
9626 * @downtime: return value of the maximum tolerable downtime for live
9627 * migration, in milliseconds
9628 * @flags: extra flags; not used yet, so callers should always pass 0
9630 * Gets current maximum tolerable time for which the domain may be paused
9631 * at the end of live migration.
9633 * Returns 0 in case of success, -1 otherwise.
9638 virDomainMigrateGetMaxDowntime(virDomainPtr domain
,
9639 unsigned long long *downtime
,
9644 VIR_DOMAIN_DEBUG(domain
, "downtime = %p, flags=0x%x", downtime
, flags
);
9646 virResetLastError();
9648 virCheckDomainReturn(domain
, -1);
9649 conn
= domain
->conn
;
9651 virCheckNonNullArgGoto(downtime
, error
);
9653 if (conn
->driver
->domainMigrateGetMaxDowntime
) {
9654 if (conn
->driver
->domainMigrateGetMaxDowntime(domain
, downtime
, flags
) < 0)
9659 virReportUnsupportedError();
9661 virDispatchError(conn
);
9667 * virDomainMigrateGetCompressionCache:
9668 * @domain: a domain object
9669 * @cacheSize: return value of current size of the cache (in bytes)
9670 * @flags: extra flags; not used yet, so callers should always pass 0
9672 * Gets current size of the cache (in bytes) used for compressing repeatedly
9673 * transferred memory pages during live migration.
9675 * Returns 0 in case of success, -1 otherwise.
9680 virDomainMigrateGetCompressionCache(virDomainPtr domain
,
9681 unsigned long long *cacheSize
,
9686 VIR_DOMAIN_DEBUG(domain
, "cacheSize=%p, flags=0x%x", cacheSize
, flags
);
9688 virResetLastError();
9690 virCheckDomainReturn(domain
, -1);
9691 conn
= domain
->conn
;
9693 virCheckNonNullArgGoto(cacheSize
, error
);
9695 if (conn
->driver
->domainMigrateGetCompressionCache
) {
9696 if (conn
->driver
->domainMigrateGetCompressionCache(domain
, cacheSize
,
9702 virReportUnsupportedError();
9704 virDispatchError(conn
);
9710 * virDomainMigrateSetCompressionCache:
9711 * @domain: a domain object
9712 * @cacheSize: size of the cache (in bytes) used for compression
9713 * @flags: extra flags; not used yet, so callers should always pass 0
9715 * Sets size of the cache (in bytes) used for compressing repeatedly
9716 * transferred memory pages during live migration. It's supposed to be called
9717 * while the domain is being live-migrated as a reaction to migration progress
9718 * and increasing number of compression cache misses obtained from
9719 * virDomainGetJobStats.
9721 * Returns 0 in case of success, -1 otherwise.
9726 virDomainMigrateSetCompressionCache(virDomainPtr domain
,
9727 unsigned long long cacheSize
,
9732 VIR_DOMAIN_DEBUG(domain
, "cacheSize=%llu, flags=0x%x", cacheSize
, flags
);
9734 virResetLastError();
9736 virCheckDomainReturn(domain
, -1);
9737 conn
= domain
->conn
;
9739 virCheckReadOnlyGoto(conn
->flags
, error
);
9741 if (conn
->driver
->domainMigrateSetCompressionCache
) {
9742 if (conn
->driver
->domainMigrateSetCompressionCache(domain
, cacheSize
,
9748 virReportUnsupportedError();
9750 virDispatchError(conn
);
9756 * virDomainMigrateSetMaxSpeed:
9757 * @domain: a domain object
9758 * @bandwidth: migration bandwidth limit in MiB/s
9759 * @flags: bitwise-OR of virDomainMigrateMaxSpeedFlags
9761 * The maximum bandwidth (in MiB/s) that will be used to do migration
9762 * can be specified with the bandwidth parameter. Not all hypervisors
9763 * will support a bandwidth cap. When VIR_DOMAIN_MIGRATE_MAX_SPEED_POSTCOPY
9764 * is set in @flags, this API sets the maximum bandwidth for the post-copy
9765 * phase of the migration.
9767 * Returns 0 in case of success, -1 otherwise.
9772 virDomainMigrateSetMaxSpeed(virDomainPtr domain
,
9773 unsigned long bandwidth
,
9778 VIR_DOMAIN_DEBUG(domain
, "bandwidth=%lu, flags=0x%x", bandwidth
, flags
);
9780 virResetLastError();
9782 virCheckDomainReturn(domain
, -1);
9783 conn
= domain
->conn
;
9785 virCheckReadOnlyGoto(conn
->flags
, error
);
9787 if (conn
->driver
->domainMigrateSetMaxSpeed
) {
9788 if (conn
->driver
->domainMigrateSetMaxSpeed(domain
, bandwidth
, flags
) < 0)
9793 virReportUnsupportedError();
9795 virDispatchError(conn
);
9801 * virDomainMigrateGetMaxSpeed:
9802 * @domain: a domain object
9803 * @bandwidth: return value of current migration bandwidth limit in MiB/s
9804 * @flags: bitwise-OR of virDomainMigrateMaxSpeedFlags
9806 * Get the current maximum bandwidth (in MiB/s) that will be used if the
9807 * domain is migrated. Not all hypervisors will support a bandwidth limit.
9808 * When VIR_DOMAIN_MIGRATE_MAX_SPEED_POSTCOPY is set in @flags, this API
9809 * gets the current maximum bandwidth for the post-copy phase of the
9812 * Returns 0 in case of success, -1 otherwise.
9817 virDomainMigrateGetMaxSpeed(virDomainPtr domain
,
9818 unsigned long *bandwidth
,
9823 VIR_DOMAIN_DEBUG(domain
, "bandwidth = %p, flags=0x%x", bandwidth
, flags
);
9825 virResetLastError();
9827 virCheckDomainReturn(domain
, -1);
9828 conn
= domain
->conn
;
9830 virCheckNonNullArgGoto(bandwidth
, error
);
9831 virCheckReadOnlyGoto(conn
->flags
, error
);
9833 if (conn
->driver
->domainMigrateGetMaxSpeed
) {
9834 if (conn
->driver
->domainMigrateGetMaxSpeed(domain
, bandwidth
, flags
) < 0)
9839 virReportUnsupportedError();
9841 virDispatchError(conn
);
9847 * virDomainMigrateStartPostCopy:
9848 * @domain: a domain object
9849 * @flags: extra flags; not used yet, so callers should always pass 0
9851 * Starts post-copy migration. This function has to be called while
9852 * migration (initiated with VIR_MIGRATE_POSTCOPY flag) is in progress.
9854 * Traditional pre-copy migration iteratively walks through guest memory
9855 * pages and migrates those that changed since the previous iteration. The
9856 * iterative phase stops when the number of dirty pages is low enough so that
9857 * the virtual CPUs can be paused, all dirty pages transferred to the
9858 * destination, where the virtual CPUs are unpaused, and all this can happen
9859 * within a predefined downtime period. It's clear that this process may never
9860 * converge if downtime is too short and/or the guest keeps changing a lot of
9863 * When migration is switched to post-copy mode, the virtual CPUs are paused
9864 * immediately, only a minimum set of pages is transferred, and the CPUs are
9865 * unpaused on destination. The source keeps sending all remaining memory pages
9866 * to the destination while the guest is already running there. Whenever the
9867 * guest tries to read a memory page which has not been migrated yet, the
9868 * hypervisor has to tell the source to transfer that page in a priority
9869 * channel. To minimize such page faults, it is a good idea to run at least one
9870 * iteration of pre-copy migration before switching to post-copy.
9872 * Post-copy migration is guaranteed to converge since each page is transferred
9873 * at most once no matter how fast it changes. On the other hand once the
9874 * guest is running on the destination host, the migration can no longer be
9875 * rolled back because none of the hosts has complete state. If this happens,
9876 * libvirt will leave the domain paused on the source host with
9877 * VIR_DOMAIN_PAUSED_POSTCOPY_FAILED reason. The domain on the destination host
9878 * will remain running with VIR_DOMAIN_RUNNING_POSTCOPY_FAILED reason.
9879 * It's up to the upper layer to decide what to do in such case. Because of
9880 * this, libvirt will refuse to cancel post-copy migration via
9881 * virDomainAbortJobFlags unless it is called with
9882 * VIR_DOMAIN_ABORT_JOB_POSTCOPY, in which case the post-copy migration will be
9885 * Failed post-copy migration can be recovered once the cause for the failure
9886 * (e.g., a network issue) is resolved by repeating the migration with an
9887 * additional VIR_MIGRATE_POSTCOPY_RESUME flag. This will recreate the
9888 * connection and resume migration from the point where it failed. This step
9889 * can be repeated in case the migration breaks again.
9891 * The following domain life cycle events are emitted during post-copy
9893 * VIR_DOMAIN_EVENT_SUSPENDED_POSTCOPY (on the source) -- migration entered
9895 * VIR_DOMAIN_EVENT_RESUMED_POSTCOPY (on the destination) -- the guest is
9896 * running on the destination host while some of its memory pages still
9897 * remain on the source host; neither the source nor the destination host
9898 * contain a complete guest state from this point until migration
9900 * VIR_DOMAIN_EVENT_RESUMED_MIGRATED (on the destination),
9901 * VIR_DOMAIN_EVENT_STOPPED_MIGRATED (on the source) -- migration finished
9902 * successfully and the destination host holds a complete guest state.
9903 * VIR_DOMAIN_EVENT_SUSPENDED_POSTCOPY_FAILED (on the source),
9904 * VIR_DOMAIN_EVENT_RESUMED_POSTCOPY_FAILED (on the destination) -- emitted
9905 * when migration fails in post-copy mode and it's unclear whether any of
9906 * the hosts has a complete guest state. Virtual CPUs on the destination
9907 * are still running.
9909 * The progress of a post-copy migration can be monitored normally using
9910 * virDomainGetJobStats on the source host. Fetching statistics of a completed
9911 * post-copy migration can also be done on the source host (by calling
9912 * virDomainGetJobStats or listening to VIR_DOMAIN_EVENT_ID_JOB_COMPLETED
9913 * event, but (in contrast to pre-copy migration) the statistics are not
9914 * available on the destination host. Thus, VIR_DOMAIN_EVENT_ID_JOB_COMPLETED
9915 * event is the only way of getting statistics of a completed post-copy
9916 * migration of a transient domain (because the domain is removed after
9917 * migration and there's no domain to run virDomainGetJobStats on).
9919 * Returns 0 in case of success, -1 otherwise.
9924 virDomainMigrateStartPostCopy(virDomainPtr domain
,
9929 VIR_DOMAIN_DEBUG(domain
);
9931 virResetLastError();
9933 virCheckDomainReturn(domain
, -1);
9934 conn
= domain
->conn
;
9936 virCheckReadOnlyGoto(conn
->flags
, error
);
9938 if (conn
->driver
->domainMigrateStartPostCopy
) {
9939 if (conn
->driver
->domainMigrateStartPostCopy(domain
, flags
) < 0)
9944 virReportUnsupportedError();
9946 virDispatchError(conn
);
9952 * virConnectDomainEventRegisterAny:
9953 * @conn: pointer to the connection
9954 * @dom: pointer to the domain
9955 * @eventID: the event type to receive
9956 * @cb: callback to the function handling domain events
9957 * @opaque: opaque data to pass on to the callback
9958 * @freecb: optional function to deallocate opaque when not used anymore
9960 * Adds a callback to receive notifications of arbitrary domain events
9961 * occurring on a domain. This function requires that an event loop
9962 * has been previously registered with virEventRegisterImpl() or
9963 * virEventRegisterDefaultImpl().
9965 * If @dom is NULL, then events will be monitored for any domain. If @dom
9966 * is non-NULL, then only the specific domain will be monitored.
9968 * Most types of event have a callback providing a custom set of parameters
9969 * for the event. When registering an event, it is thus necessary to use
9970 * the VIR_DOMAIN_EVENT_CALLBACK() macro to cast the supplied function pointer
9971 * to match the signature of this method.
9973 * The virDomainPtr object handle passed into the callback upon delivery
9974 * of an event is only valid for the duration of execution of the callback.
9975 * If the callback wishes to keep the domain object after the callback returns,
9976 * it shall take a reference to it, by calling virDomainRef().
9977 * The reference can be released once the object is no longer required
9978 * by calling virDomainFree().
9980 * The return value from this method is a non-negative integer identifier
9981 * for the callback. To unregister a callback, this callback ID should
9982 * be passed to the virConnectDomainEventDeregisterAny() method.
9984 * Returns a callback identifier on success, -1 on failure.
9989 virConnectDomainEventRegisterAny(virConnectPtr conn
,
9992 virConnectDomainEventGenericCallback cb
,
9994 virFreeCallback freecb
)
9996 VIR_DOMAIN_DEBUG(dom
, "conn=%p, eventID=%d, cb=%p, opaque=%p, freecb=%p",
9997 conn
, eventID
, cb
, opaque
, freecb
);
9999 virResetLastError();
10001 virCheckConnectReturn(conn
, -1);
10003 virCheckDomainGoto(dom
, error
);
10004 if (dom
->conn
!= conn
) {
10005 virReportInvalidArg(dom
,
10006 _("domain '%1$s' must match connection"),
10011 virCheckNonNullArgGoto(cb
, error
);
10012 virCheckNonNegativeArgGoto(eventID
, error
);
10013 if (eventID
>= VIR_DOMAIN_EVENT_ID_LAST
) {
10014 virReportInvalidArg(eventID
,
10015 _("eventID must be less than %1$d"),
10016 VIR_DOMAIN_EVENT_ID_LAST
);
10020 if (conn
->driver
&& conn
->driver
->connectDomainEventRegisterAny
) {
10022 ret
= conn
->driver
->connectDomainEventRegisterAny(conn
, dom
, eventID
, cb
, opaque
, freecb
);
10028 virReportUnsupportedError();
10030 virDispatchError(conn
);
10036 * virConnectDomainEventDeregisterAny:
10037 * @conn: pointer to the connection
10038 * @callbackID: the callback identifier
10040 * Removes an event callback. The callbackID parameter should be the
10041 * value obtained from a previous virConnectDomainEventRegisterAny() method.
10043 * Returns 0 on success, -1 on failure. Older versions of some hypervisors
10044 * sometimes returned a positive number on success, but without any reliable
10045 * semantics on what that number represents.
10050 virConnectDomainEventDeregisterAny(virConnectPtr conn
,
10053 VIR_DEBUG("conn=%p, callbackID=%d", conn
, callbackID
);
10055 virResetLastError();
10057 virCheckConnectReturn(conn
, -1);
10058 virCheckNonNegativeArgGoto(callbackID
, error
);
10060 if (conn
->driver
&& conn
->driver
->connectDomainEventDeregisterAny
) {
10062 ret
= conn
->driver
->connectDomainEventDeregisterAny(conn
, callbackID
);
10068 virReportUnsupportedError();
10070 virDispatchError(conn
);
10076 * virDomainManagedSave:
10077 * @dom: pointer to the domain
10078 * @flags: bitwise-OR of virDomainSaveRestoreFlags
10080 * This method will suspend a domain and save its memory contents to
10081 * a file on disk. After the call, if successful, the domain is not
10082 * listed as running anymore.
10083 * The difference from virDomainSave() is that libvirt is keeping track of
10084 * the saved state itself, and will reuse it once the domain is being
10085 * restarted (automatically or via an explicit libvirt call).
10086 * As a result any running domain is sure to not have a managed saved image.
10087 * This also implies that managed save only works on persistent domains,
10088 * since the domain must still exist in order to use virDomainCreate() to
10091 * If @flags includes VIR_DOMAIN_SAVE_BYPASS_CACHE, then libvirt will
10092 * attempt to bypass the file system cache while creating the file, or
10093 * fail if it cannot do so for the given system; this can allow less
10094 * pressure on file system cache, but also risks slowing saves to NFS.
10096 * Normally, the managed saved state will remember whether the domain
10097 * was running or paused, and start will resume to the same state.
10098 * Specifying VIR_DOMAIN_SAVE_RUNNING or VIR_DOMAIN_SAVE_PAUSED in
10099 * @flags will override the default saved into the file. These two
10100 * flags are mutually exclusive.
10102 * Returns 0 in case of success or -1 in case of failure
10107 virDomainManagedSave(virDomainPtr dom
, unsigned int flags
)
10109 virConnectPtr conn
;
10111 VIR_DOMAIN_DEBUG(dom
, "flags=0x%x", flags
);
10113 virResetLastError();
10115 virCheckDomainReturn(dom
, -1);
10118 virCheckReadOnlyGoto(conn
->flags
, error
);
10120 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_SAVE_RUNNING
,
10121 VIR_DOMAIN_SAVE_PAUSED
,
10124 if (conn
->driver
->domainManagedSave
) {
10127 ret
= conn
->driver
->domainManagedSave(dom
, flags
);
10133 virReportUnsupportedError();
10136 virDispatchError(conn
);
10142 * virDomainHasManagedSaveImage:
10143 * @dom: pointer to the domain
10144 * @flags: extra flags; not used yet, so callers should always pass 0
10146 * Check if a domain has a managed save image as created by
10147 * virDomainManagedSave(). Note that any running domain should not have
10148 * such an image, as it should have been removed on restart.
10150 * Returns 0 if no image is present, 1 if an image is present, and
10151 * -1 in case of error
10156 virDomainHasManagedSaveImage(virDomainPtr dom
, unsigned int flags
)
10158 virConnectPtr conn
;
10160 VIR_DOMAIN_DEBUG(dom
, "flags=0x%x", flags
);
10162 virResetLastError();
10164 virCheckDomainReturn(dom
, -1);
10167 if (conn
->driver
->domainHasManagedSaveImage
) {
10170 ret
= conn
->driver
->domainHasManagedSaveImage(dom
, flags
);
10176 virReportUnsupportedError();
10179 virDispatchError(conn
);
10185 * virDomainManagedSaveRemove:
10186 * @dom: pointer to the domain
10187 * @flags: extra flags; not used yet, so callers should always pass 0
10189 * Remove any managed save image for this domain.
10191 * Returns 0 in case of success, and -1 in case of error
10196 virDomainManagedSaveRemove(virDomainPtr dom
, unsigned int flags
)
10198 virConnectPtr conn
;
10200 VIR_DOMAIN_DEBUG(dom
, "flags=0x%x", flags
);
10202 virResetLastError();
10204 virCheckDomainReturn(dom
, -1);
10207 virCheckReadOnlyGoto(conn
->flags
, error
);
10209 if (conn
->driver
->domainManagedSaveRemove
) {
10212 ret
= conn
->driver
->domainManagedSaveRemove(dom
, flags
);
10218 virReportUnsupportedError();
10221 virDispatchError(conn
);
10227 * virDomainManagedSaveGetXMLDesc:
10228 * @domain: a domain object
10229 * @flags: bitwise-OR of supported virDomainSaveImageXMLFlags
10231 * This method will extract the XML description of the managed save
10232 * state file of a domain.
10234 * No security-sensitive data will be included unless @flags contains
10235 * VIR_DOMAIN_SAVE_IMAGE_XML_SECURE; this flag is rejected on read-only
10238 * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of
10239 * error. The caller must free() the returned value.
10244 virDomainManagedSaveGetXMLDesc(virDomainPtr domain
, unsigned int flags
)
10246 virConnectPtr conn
;
10248 VIR_DOMAIN_DEBUG(domain
, "flags=0x%x", flags
);
10250 virResetLastError();
10252 virCheckDomainReturn(domain
, NULL
);
10253 conn
= domain
->conn
;
10255 if ((conn
->flags
& VIR_CONNECT_RO
) &&
10256 (flags
& VIR_DOMAIN_SAVE_IMAGE_XML_SECURE
)) {
10257 virReportError(VIR_ERR_OPERATION_DENIED
, "%s",
10258 _("virDomainManagedSaveGetXMLDesc with secure flag"));
10262 if (conn
->driver
->domainManagedSaveGetXMLDesc
) {
10264 ret
= conn
->driver
->domainManagedSaveGetXMLDesc(domain
, flags
);
10270 virReportUnsupportedError();
10273 virDispatchError(domain
->conn
);
10279 * virDomainManagedSaveDefineXML:
10280 * @domain: a domain object
10281 * @dxml: XML config for adjusting guest xml used on restore
10282 * @flags: bitwise-OR of virDomainSaveRestoreFlags
10284 * This updates the definition of a domain stored in a saved state
10287 * @dxml can be used to alter host-specific portions of the domain XML
10288 * that will be used on the next start of the domain. For example, it is
10289 * possible to alter the backing filename that is associated with a
10292 * Normally, the saved state file will remember whether the domain was
10293 * running or paused, and restore defaults to the same state.
10294 * Specifying VIR_DOMAIN_SAVE_RUNNING or VIR_DOMAIN_SAVE_PAUSED in
10295 * @flags will override the default saved into the file; omitting both
10296 * leaves the file's default unchanged. These two flags are mutually
10299 * Returns 0 in case of success and -1 in case of failure.
10304 virDomainManagedSaveDefineXML(virDomainPtr domain
, const char *dxml
,
10305 unsigned int flags
)
10307 virConnectPtr conn
;
10309 VIR_DOMAIN_DEBUG(domain
, "flags=0x%x", flags
);
10311 virResetLastError();
10313 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_SAVE_RUNNING
,
10314 VIR_DOMAIN_SAVE_PAUSED
,
10317 virCheckDomainReturn(domain
, -1);
10318 conn
= domain
->conn
;
10319 virCheckReadOnlyGoto(conn
->flags
, error
);
10321 if (conn
->driver
->domainManagedSaveDefineXML
) {
10323 ret
= conn
->driver
->domainManagedSaveDefineXML(domain
, dxml
, flags
);
10330 virReportUnsupportedError();
10333 virDispatchError(domain
->conn
);
10339 * virDomainOpenConsole:
10340 * @dom: a domain object
10341 * @dev_name: the console, serial or parallel port device alias, or NULL
10342 * @st: a stream to associate with the console
10343 * @flags: bitwise-OR of virDomainConsoleFlags
10345 * This opens the backend associated with a console, serial or
10346 * parallel port device on a guest, if the backend is supported.
10347 * If the @dev_name is omitted, then the first console or serial
10348 * device is opened. The console is associated with the passed
10349 * in @st stream, which should have been opened in non-blocking
10350 * mode for bi-directional I/O.
10352 * By default, when @flags is 0, the open will fail if libvirt
10353 * detects that the console is already in use by another client;
10354 * passing VIR_DOMAIN_CONSOLE_FORCE will cause libvirt to forcefully
10355 * remove the other client prior to opening this console.
10357 * If flag VIR_DOMAIN_CONSOLE_SAFE the console is opened only in the
10358 * case where the hypervisor driver supports safe (mutually exclusive)
10359 * console handling.
10361 * Older servers did not support either flag, and also did not forbid
10362 * simultaneous clients on a console, with potentially confusing results.
10363 * When passing @flags of 0 in order to support a wider range of server
10364 * versions, it is up to the client to ensure mutual exclusion.
10366 * Returns 0 if the console was opened, -1 on error
10371 virDomainOpenConsole(virDomainPtr dom
,
10372 const char *dev_name
,
10374 unsigned int flags
)
10376 virConnectPtr conn
;
10378 VIR_DOMAIN_DEBUG(dom
, "dev_name=%s, st=%p, flags=0x%x",
10379 NULLSTR(dev_name
), st
, flags
);
10381 virResetLastError();
10383 virCheckDomainReturn(dom
, -1);
10386 virCheckStreamGoto(st
, error
);
10387 virCheckReadOnlyGoto(conn
->flags
, error
);
10389 if (conn
!= st
->conn
) {
10390 virReportInvalidArg(st
,
10391 _("stream must match connection of domain '%1$s'"),
10396 if (conn
->driver
->domainOpenConsole
) {
10398 ret
= conn
->driver
->domainOpenConsole(dom
, dev_name
, st
, flags
);
10404 virReportUnsupportedError();
10407 virDispatchError(conn
);
10413 * virDomainOpenChannel:
10414 * @dom: a domain object
10415 * @name: the channel name, or NULL
10416 * @st: a stream to associate with the channel
10417 * @flags: bitwise-OR of virDomainChannelFlags
10419 * This opens the host interface associated with a channel device on a
10420 * guest, if the host interface is supported. If @name is given, it
10421 * can match either the device alias (e.g. "channel0"), or the virtio
10422 * target name (e.g. "org.qemu.guest_agent.0"). If @name is omitted,
10423 * then the first channel is opened. The channel is associated with
10424 * the passed in @st stream, which should have been opened in
10425 * non-blocking mode for bi-directional I/O.
10427 * By default, when @flags is 0, the open will fail if libvirt detects
10428 * that the channel is already in use by another client; passing
10429 * VIR_DOMAIN_CHANNEL_FORCE will cause libvirt to forcefully remove the
10430 * other client prior to opening this channel.
10432 * Returns 0 if the channel was opened, -1 on error
10437 virDomainOpenChannel(virDomainPtr dom
,
10440 unsigned int flags
)
10442 virConnectPtr conn
;
10444 VIR_DOMAIN_DEBUG(dom
, "name=%s, st=%p, flags=0x%x",
10445 NULLSTR(name
), st
, flags
);
10447 virResetLastError();
10449 virCheckDomainReturn(dom
, -1);
10452 virCheckStreamGoto(st
, error
);
10453 virCheckReadOnlyGoto(conn
->flags
, error
);
10455 if (conn
!= st
->conn
) {
10456 virReportInvalidArg(st
,
10457 _("stream must match connection of domain '%1$s'"),
10462 if (conn
->driver
->domainOpenChannel
) {
10464 ret
= conn
->driver
->domainOpenChannel(dom
, name
, st
, flags
);
10470 virReportUnsupportedError();
10473 virDispatchError(conn
);
10479 * virDomainGetPerfEvents:
10480 * @domain: a domain object
10481 * @params: where to store perf events setting
10482 * @nparams: number of items in @params
10483 * @flags: bitwise-OR of virDomainModificationImpact and virTypedParameterFlags
10485 * Get all Linux perf events setting. Possible fields returned in
10486 * @params are defined by VIR_PERF_EVENT_* macros and new fields
10487 * will likely be introduced in the future.
10489 * Linux perf events are performance analyzing tool in Linux.
10491 * Returns -1 in case of failure, 0 in case of success.
10495 int virDomainGetPerfEvents(virDomainPtr domain
,
10496 virTypedParameterPtr
*params
,
10498 unsigned int flags
)
10500 virConnectPtr conn
;
10502 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%p flags=0x%x",
10503 params
, nparams
, flags
);
10505 virResetLastError();
10507 virCheckDomainReturn(domain
, -1);
10508 virCheckNonNullArgGoto(params
, error
);
10509 virCheckNonNullArgGoto(nparams
, error
);
10511 conn
= domain
->conn
;
10513 if (conn
->driver
->domainGetPerfEvents
) {
10515 ret
= conn
->driver
->domainGetPerfEvents(domain
, params
,
10521 virReportUnsupportedError();
10524 virDispatchError(domain
->conn
);
10530 * virDomainSetPerfEvents:
10531 * @domain: a domain object
10532 * @params: pointer to perf events parameter object
10533 * @nparams: number of perf event parameters (this value can be the same
10534 * less than the number of parameters supported)
10535 * @flags: bitwise-OR of virDomainModificationImpact
10537 * Enable or disable the particular list of Linux perf events you
10538 * care about. The @params argument should contain any subset of
10539 * VIR_PERF_EVENT_ macros.
10541 * Linux perf events are performance analyzing tool in Linux.
10543 * Returns -1 in case of error, 0 in case of success.
10547 int virDomainSetPerfEvents(virDomainPtr domain
,
10548 virTypedParameterPtr params
,
10550 unsigned int flags
)
10552 virConnectPtr conn
;
10554 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%d flags=0x%x",
10555 params
, nparams
, flags
);
10556 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
10558 virResetLastError();
10560 virCheckDomainReturn(domain
, -1);
10561 conn
= domain
->conn
;
10563 virCheckReadOnlyGoto(conn
->flags
, error
);
10564 virCheckNonNullArgGoto(params
, error
);
10565 virCheckPositiveArgGoto(nparams
, error
);
10567 if (virTypedParameterValidateSet(conn
, params
, nparams
) < 0)
10570 if (conn
->driver
->domainSetPerfEvents
) {
10572 ret
= conn
->driver
->domainSetPerfEvents(domain
, params
,
10579 virReportUnsupportedError();
10582 virDispatchError(domain
->conn
);
10588 * virDomainBlockJobAbort:
10589 * @dom: pointer to domain object
10590 * @disk: path to the block device, or device shorthand
10591 * @flags: bitwise-OR of virDomainBlockJobAbortFlags
10593 * Cancel the active block job on the given disk.
10595 * The @disk parameter is either an unambiguous source name of the
10596 * block device (the <source file='...'/> sub-element, such as
10597 * "/path/to/image"), or (since 0.9.5) the device target shorthand
10598 * (the <target dev='...'/> sub-element, such as "vda"). Valid names
10599 * can be found by calling virDomainGetXMLDesc() and inspecting
10600 * elements within //domain/devices/disk.
10602 * If the current block job for @disk is VIR_DOMAIN_BLOCK_JOB_TYPE_PULL, then
10603 * by default, this function performs a synchronous operation and the caller
10604 * may assume that the operation has completed when 0 is returned. However,
10605 * BlockJob operations may take a long time to cancel, and during this time
10606 * further domain interactions may be unresponsive. To avoid this problem,
10607 * pass VIR_DOMAIN_BLOCK_JOB_ABORT_ASYNC in the @flags argument to enable
10608 * asynchronous behavior, returning as soon as possible. When the job has
10609 * been canceled, a BlockJob event will be emitted, with status
10610 * VIR_DOMAIN_BLOCK_JOB_CANCELED (even if the ABORT_ASYNC flag was not
10611 * used); it is also possible to poll virDomainBlockJobInfo() to see if
10612 * the job cancellation is still pending. This type of job can be restarted
10613 * to pick up from where it left off.
10615 * If the current block job for @disk is VIR_DOMAIN_BLOCK_JOB_TYPE_COPY, then
10616 * the default is to abort the mirroring and revert to the source disk;
10617 * likewise, if the current job is VIR_DOMAIN_BLOCK_JOB_TYPE_ACTIVE_COMMIT,
10618 * the default is to abort without changing the active layer of @disk.
10619 * Adding @flags of VIR_DOMAIN_BLOCK_JOB_ABORT_PIVOT causes this call to
10620 * fail with VIR_ERR_BLOCK_COPY_ACTIVE if the copy or commit is not yet
10621 * ready; otherwise it will swap the disk over to the new active image
10622 * to end the mirroring or active commit. An event will be issued when the
10623 * job is ended, and it is possible to use VIR_DOMAIN_BLOCK_JOB_ABORT_ASYNC
10624 * to control whether this command waits for the completion of the job.
10625 * Restarting a copy or active commit job requires starting over from the
10626 * beginning of the first phase.
10628 * Returns -1 in case of failure, 0 when successful.
10633 virDomainBlockJobAbort(virDomainPtr dom
, const char *disk
,
10634 unsigned int flags
)
10636 virConnectPtr conn
;
10638 VIR_DOMAIN_DEBUG(dom
, "disk=%s, flags=0x%x", disk
, flags
);
10640 virResetLastError();
10642 virCheckDomainReturn(dom
, -1);
10645 virCheckReadOnlyGoto(conn
->flags
, error
);
10646 virCheckNonNullArgGoto(disk
, error
);
10648 if (conn
->driver
->domainBlockJobAbort
) {
10650 ret
= conn
->driver
->domainBlockJobAbort(dom
, disk
, flags
);
10656 virReportUnsupportedError();
10659 virDispatchError(dom
->conn
);
10665 * virDomainGetBlockJobInfo:
10666 * @dom: pointer to domain object
10667 * @disk: path to the block device, or device shorthand
10668 * @info: pointer to a virDomainBlockJobInfo structure
10669 * @flags: bitwise-OR of virDomainBlockJobInfoFlags
10671 * Request block job information for the given disk. If an operation is active
10672 * @info will be updated with the current progress. The units used for the
10673 * bandwidth field of @info depends on @flags. If @flags includes
10674 * VIR_DOMAIN_BLOCK_JOB_INFO_BANDWIDTH_BYTES, bandwidth is in bytes/second
10675 * (although this mode can risk failure due to overflow, depending on both
10676 * client and server word size); otherwise, the value is rounded up to MiB/s.
10678 * The @disk parameter is either an unambiguous source name of the
10679 * block device (the <source file='...'/> sub-element, such as
10680 * "/path/to/image"), or (since 0.9.5) the device target shorthand
10681 * (the <target dev='...'/> sub-element, such as "vda"). Valid names
10682 * can be found by calling virDomainGetXMLDesc() and inspecting
10683 * elements within //domain/devices/disk.
10685 * In cases when libvirt can't determine actual progress of the block job from
10686 * the underlying hypervisor due to corner cases such as the job wasn't yet
10687 * fully initialized, or finalized and thus the progress can't be queried,
10688 * libvirt reports 'cur = 0, end = 1'.
10690 * For jobs requiring finalizing via qemuDomainBlockJobAbort() with
10691 * VIR_DOMAIN_BLOCK_JOB_ABORT_PIVOT flag which reached synchronised phase, but
10692 * were empty, or the progress can't be determined libvirt returns
10693 * 'cur = 1, end = 1'.
10695 * Users thus should not consider any data where 'end = 1' as absolute progress
10698 * Applications looking for a reliable and low-overhead way to determine whether
10699 * a block job already finished or reached synchronised phase should register a
10700 * handler for the VIR_DOMAIN_EVENT_ID_BLOCK_JOB_2 event instead of polling this
10703 * Note that the progress reported for blockjobs corresponding to a pull-mode
10704 * backup don't report progress of the backup but rather usage of temporary
10705 * space required for the backup.
10707 * Returns -1 in case of failure, 0 when nothing found, 1 when info was found.
10712 virDomainGetBlockJobInfo(virDomainPtr dom
, const char *disk
,
10713 virDomainBlockJobInfoPtr info
, unsigned int flags
)
10715 virConnectPtr conn
;
10717 VIR_DOMAIN_DEBUG(dom
, "disk=%s, info=%p, flags=0x%x", disk
, info
, flags
);
10719 virResetLastError();
10722 memset(info
, 0, sizeof(*info
));
10724 virCheckDomainReturn(dom
, -1);
10727 virCheckNonNullArgGoto(disk
, error
);
10728 virCheckNonNullArgGoto(info
, error
);
10730 if (conn
->driver
->domainGetBlockJobInfo
) {
10732 ret
= conn
->driver
->domainGetBlockJobInfo(dom
, disk
, info
, flags
);
10738 virReportUnsupportedError();
10741 virDispatchError(dom
->conn
);
10747 * virDomainBlockJobSetSpeed:
10748 * @dom: pointer to domain object
10749 * @disk: path to the block device, or device shorthand
10750 * @bandwidth: specify bandwidth limit; flags determine the unit
10751 * @flags: bitwise-OR of virDomainBlockJobSetSpeedFlags
10753 * Set the maximum allowable bandwidth that a block job may consume. If
10754 * bandwidth is 0, the limit will revert to the hypervisor default of
10757 * If @flags contains VIR_DOMAIN_BLOCK_JOB_SPEED_BANDWIDTH_BYTES, @bandwidth
10758 * is in bytes/second; otherwise, it is in MiB/second. Values larger than
10759 * 2^52 bytes/sec may be rejected due to overflow considerations based on
10760 * the word size of both client and server, and values larger than 2^31
10761 * bytes/sec may cause overflow problems if later queried by
10762 * virDomainGetBlockJobInfo() without scaling. Hypervisors may further
10763 * restrict the range of valid bandwidth values.
10765 * The @disk parameter is either an unambiguous source name of the
10766 * block device (the <source file='...'/> sub-element, such as
10767 * "/path/to/image"), or (since 0.9.5) the device target shorthand
10768 * (the <target dev='...'/> sub-element, such as "vda"). Valid names
10769 * can be found by calling virDomainGetXMLDesc() and inspecting
10770 * elements within //domain/devices/disk.
10772 * Returns -1 in case of failure, 0 when successful.
10777 virDomainBlockJobSetSpeed(virDomainPtr dom
, const char *disk
,
10778 unsigned long bandwidth
, unsigned int flags
)
10780 virConnectPtr conn
;
10782 VIR_DOMAIN_DEBUG(dom
, "disk=%s, bandwidth=%lu, flags=0x%x",
10783 disk
, bandwidth
, flags
);
10785 virResetLastError();
10787 virCheckDomainReturn(dom
, -1);
10790 virCheckReadOnlyGoto(conn
->flags
, error
);
10791 virCheckNonNullArgGoto(disk
, error
);
10793 if (conn
->driver
->domainBlockJobSetSpeed
) {
10795 ret
= conn
->driver
->domainBlockJobSetSpeed(dom
, disk
, bandwidth
, flags
);
10801 virReportUnsupportedError();
10804 virDispatchError(dom
->conn
);
10810 * virDomainBlockPull:
10811 * @dom: pointer to domain object
10812 * @disk: path to the block device, or device shorthand
10813 * @bandwidth: (optional) specify bandwidth limit; flags determine the unit
10814 * @flags: bitwise-OR of virDomainBlockPullFlags
10816 * Populate a disk image with data from its backing image. Once all data from
10817 * its backing image has been pulled, the disk no longer depends on a backing
10818 * image. This function pulls data for the entire device in the background.
10819 * Progress of the operation can be checked with virDomainGetBlockJobInfo() and
10820 * the operation can be aborted with virDomainBlockJobAbort(). When finished,
10821 * an asynchronous event is raised to indicate the final status. To move
10822 * data in the opposite direction, see virDomainBlockCommit().
10824 * The @disk parameter is either an unambiguous source name of the
10825 * block device (the <source file='...'/> sub-element, such as
10826 * "/path/to/image"), or (since 0.9.5) the device target shorthand
10827 * (the <target dev='...'/> sub-element, such as "vda"). Valid names
10828 * can be found by calling virDomainGetXMLDesc() and inspecting
10829 * elements within //domain/devices/disk.
10831 * The maximum bandwidth that will be used to do the copy can be
10832 * specified with the @bandwidth parameter. If set to 0, there is no
10833 * limit. If @flags includes VIR_DOMAIN_BLOCK_PULL_BANDWIDTH_BYTES,
10834 * @bandwidth is in bytes/second; otherwise, it is in MiB/second.
10835 * Values larger than 2^52 bytes/sec may be rejected due to overflow
10836 * considerations based on the word size of both client and server,
10837 * and values larger than 2^31 bytes/sec may cause overflow problems
10838 * if later queried by virDomainGetBlockJobInfo() without scaling.
10839 * Hypervisors may further restrict the range of valid bandwidth
10840 * values. Some hypervisors do not support this feature and will
10841 * return an error if bandwidth is not 0; in this case, it might still
10842 * be possible for a later call to virDomainBlockJobSetSpeed() to
10843 * succeed. The actual speed can be determined with
10844 * virDomainGetBlockJobInfo().
10846 * This is shorthand for virDomainBlockRebase() with a NULL base.
10848 * Returns 0 if the operation has started, -1 on failure.
10853 virDomainBlockPull(virDomainPtr dom
, const char *disk
,
10854 unsigned long bandwidth
, unsigned int flags
)
10856 virConnectPtr conn
;
10858 VIR_DOMAIN_DEBUG(dom
, "disk=%s, bandwidth=%lu, flags=0x%x",
10859 disk
, bandwidth
, flags
);
10861 virResetLastError();
10863 virCheckDomainReturn(dom
, -1);
10866 virCheckReadOnlyGoto(conn
->flags
, error
);
10867 virCheckNonNullArgGoto(disk
, error
);
10869 if (conn
->driver
->domainBlockPull
) {
10871 ret
= conn
->driver
->domainBlockPull(dom
, disk
, bandwidth
, flags
);
10877 virReportUnsupportedError();
10880 virDispatchError(dom
->conn
);
10886 * virDomainBlockRebase:
10887 * @dom: pointer to domain object
10888 * @disk: path to the block device, or device shorthand
10889 * @base: path to backing file to keep, or device shorthand,
10890 * or NULL for no backing file
10891 * @bandwidth: (optional) specify bandwidth limit; flags determine the unit
10892 * @flags: bitwise-OR of virDomainBlockRebaseFlags
10894 * Populate a disk image with data from its backing image chain, and
10895 * setting the backing image to @base, or alternatively copy an entire
10896 * backing chain to a new file @base.
10898 * When @flags is 0, this starts a pull, where @base must be the absolute
10899 * path of one of the backing images further up the chain, or NULL to
10900 * convert the disk image so that it has no backing image. Once all
10901 * data from its backing image chain has been pulled, the disk no
10902 * longer depends on those intermediate backing images. This function
10903 * pulls data for the entire device in the background. Progress of
10904 * the operation can be checked with virDomainGetBlockJobInfo() with a
10905 * job type of VIR_DOMAIN_BLOCK_JOB_TYPE_PULL, and the operation can be
10906 * aborted with virDomainBlockJobAbort(). When finished, an asynchronous
10907 * event is raised to indicate the final status, and the job no longer
10908 * exists. If the job is aborted, a new one can be started later to
10909 * resume from the same point.
10911 * If @flags contains VIR_DOMAIN_BLOCK_REBASE_RELATIVE, the name recorded
10912 * into the active disk as the location for @base will be kept relative.
10913 * The operation will fail if libvirt can't infer the name.
10915 * When @flags includes VIR_DOMAIN_BLOCK_REBASE_COPY, this starts a copy,
10916 * where @base must be the name of a new file to copy the chain to. By
10917 * default, the copy will pull the entire source chain into the destination
10918 * file, but if @flags also contains VIR_DOMAIN_BLOCK_REBASE_SHALLOW, then
10919 * only the top of the source chain will be copied (the source and
10920 * destination have a common backing file). By default, @base will be
10921 * created with the same file format as the source, but this can be altered
10922 * by adding VIR_DOMAIN_BLOCK_REBASE_COPY_RAW to force the copy to be raw
10923 * (does not make sense with the shallow flag unless the source is also raw),
10924 * or by using VIR_DOMAIN_BLOCK_REBASE_REUSE_EXT to reuse an existing file
10925 * which was pre-created with the correct format and metadata and sufficient
10926 * size to hold the copy. In case the VIR_DOMAIN_BLOCK_REBASE_SHALLOW flag
10927 * is used the pre-created file has to exhibit the same guest visible contents
10928 * as the backing file of the original image. This allows a management app to
10929 * pre-create files with relative backing file names, rather than the default
10930 * of absolute backing file names; as a security precaution, you should
10931 * generally only use reuse_ext with the shallow flag and a non-raw
10932 * destination file. By default, the copy destination will be treated as
10933 * type='file', but using VIR_DOMAIN_BLOCK_REBASE_COPY_DEV treats the
10934 * destination as type='block' (affecting how virDomainGetBlockInfo() will
10935 * report allocation after pivoting).
10937 * A copy job has two parts; in the first phase, the @bandwidth parameter
10938 * affects how fast the source is pulled into the destination, and the job
10939 * can only be canceled by reverting to the source file; progress in this
10940 * phase can be tracked via the virDomainBlockJobInfo() command, with a
10941 * job type of VIR_DOMAIN_BLOCK_JOB_TYPE_COPY. The job transitions to the
10942 * second phase when the job info states cur == end, and remains alive to
10943 * mirror all further changes to both source and destination. The user
10944 * must call virDomainBlockJobAbort() to end the mirroring while choosing
10945 * whether to revert to source or pivot to the destination. An event is
10946 * issued when the job ends, and depending on the hypervisor, an event may
10947 * also be issued when the job transitions from pulling to mirroring. If
10948 * the job is aborted, a new job will have to start over from the beginning
10949 * of the first phase.
10951 * Some hypervisors will restrict certain actions, such as virDomainSave()
10952 * or virDomainDetachDevice(), while a copy job is active; they may
10953 * also restrict a copy job to transient domains.
10955 * The @disk parameter is either an unambiguous source name of the
10956 * block device (the <source file='...'/> sub-element, such as
10957 * "/path/to/image"), or the device target shorthand (the
10958 * <target dev='...'/> sub-element, such as "vda"). Valid names
10959 * can be found by calling virDomainGetXMLDesc() and inspecting
10960 * elements within //domain/devices/disk.
10962 * The @base parameter can be either a path to a file within the backing
10963 * chain, or the device target shorthand (the <target dev='...'/>
10964 * sub-element, such as "vda") followed by an index to the backing chain
10965 * enclosed in square brackets. Backing chain indexes can be found by
10966 * inspecting //disk//backingStore/@index in the domain XML. Thus, for
10967 * example, "vda[3]" refers to the backing store with index equal to "3"
10968 * in the chain of disk "vda".
10970 * The maximum bandwidth that will be used to do the copy can be
10971 * specified with the @bandwidth parameter. If set to 0, there is no
10972 * limit. If @flags includes VIR_DOMAIN_BLOCK_REBASE_BANDWIDTH_BYTES,
10973 * @bandwidth is in bytes/second; otherwise, it is in MiB/second.
10974 * Values larger than 2^52 bytes/sec may be rejected due to overflow
10975 * considerations based on the word size of both client and server,
10976 * and values larger than 2^31 bytes/sec may cause overflow problems
10977 * if later queried by virDomainGetBlockJobInfo() without scaling.
10978 * Hypervisors may further restrict the range of valid bandwidth
10979 * values. Some hypervisors do not support this feature and will
10980 * return an error if bandwidth is not 0; in this case, it might still
10981 * be possible for a later call to virDomainBlockJobSetSpeed() to
10982 * succeed. The actual speed can be determined with
10983 * virDomainGetBlockJobInfo().
10985 * When @base is NULL and @flags is 0, this is identical to
10986 * virDomainBlockPull(). When @flags contains VIR_DOMAIN_BLOCK_REBASE_COPY,
10987 * this command is shorthand for virDomainBlockCopy() where the destination
10988 * XML encodes @base as a <disk type='file'>, @bandwidth is properly scaled
10989 * and passed as a typed parameter, the shallow and reuse external flags
10990 * are preserved, and remaining flags control whether the XML encodes a
10991 * destination format of raw instead of leaving the destination identical
10992 * to the source format or probed from the reused file.
10994 * Returns 0 if the operation has started, -1 on failure.
10999 virDomainBlockRebase(virDomainPtr dom
, const char *disk
,
11000 const char *base
, unsigned long bandwidth
,
11001 unsigned int flags
)
11003 virConnectPtr conn
;
11005 VIR_DOMAIN_DEBUG(dom
, "disk=%s, base=%s, bandwidth=%lu, flags=0x%x",
11006 disk
, NULLSTR(base
), bandwidth
, flags
);
11008 virResetLastError();
11010 virCheckDomainReturn(dom
, -1);
11013 virCheckReadOnlyGoto(conn
->flags
, error
);
11014 virCheckNonNullArgGoto(disk
, error
);
11016 if (flags
& VIR_DOMAIN_BLOCK_REBASE_COPY
) {
11017 virCheckNonNullArgGoto(base
, error
);
11018 } else if (flags
& (VIR_DOMAIN_BLOCK_REBASE_SHALLOW
|
11019 VIR_DOMAIN_BLOCK_REBASE_REUSE_EXT
|
11020 VIR_DOMAIN_BLOCK_REBASE_COPY_RAW
|
11021 VIR_DOMAIN_BLOCK_REBASE_COPY_DEV
)) {
11022 virReportInvalidArg(flags
, "%s",
11023 _("use of flags requires a copy job"));
11027 if (conn
->driver
->domainBlockRebase
) {
11029 ret
= conn
->driver
->domainBlockRebase(dom
, disk
, base
, bandwidth
,
11036 virReportUnsupportedError();
11039 virDispatchError(dom
->conn
);
11045 * virDomainBlockCopy:
11046 * @dom: pointer to domain object
11047 * @disk: path to the block device, or device shorthand
11048 * @destxml: XML description of the copy destination
11049 * @params: Pointer to block copy parameter objects, or NULL
11050 * @nparams: Number of block copy parameters (this value can be the same or
11051 * less than the number of parameters supported)
11052 * @flags: bitwise-OR of virDomainBlockCopyFlags
11054 * Copy the guest-visible contents of a disk image to a new file described
11055 * by @destxml. The destination XML has a top-level element of <disk>, and
11056 * resembles what is used when hot-plugging a disk via virDomainAttachDevice(),
11057 * except that only sub-elements related to describing the new host resource
11058 * are necessary (sub-elements related to the guest view, such as <target>,
11059 * are ignored). It is strongly recommended to include a <driver type='...'/>
11060 * format designation for the destination, to avoid the potential of any
11061 * security problem that might be caused by probing a file for its format.
11063 * This command starts a long-running copy. By default, the copy will pull
11064 * the entire source chain into the destination file, but if @flags also
11065 * contains VIR_DOMAIN_BLOCK_COPY_SHALLOW, then only the top of the source
11066 * chain will be copied (the source and destination have a common backing
11067 * file). The format of the destination file is controlled by the <driver>
11068 * sub-element of the XML. The destination will be created unless the
11069 * VIR_DOMAIN_BLOCK_COPY_REUSE_EXT flag is present stating that the file
11070 * was pre-created with the correct format and metadata and sufficient
11071 * size to hold the copy. In case the VIR_DOMAIN_BLOCK_COPY_SHALLOW flag
11072 * is used the pre-created file has to exhibit the same guest visible contents
11073 * as the backing file of the original image. This allows a management app to
11074 * pre-create files with relative backing file names, rather than the default
11075 * of absolute backing file names.
11077 * A copy job has two parts; in the first phase, the source is copied into
11078 * the destination, and the job can only be canceled by reverting to the
11079 * source file; progress in this phase can be tracked via the
11080 * virDomainBlockJobInfo() command, with a job type of
11081 * VIR_DOMAIN_BLOCK_JOB_TYPE_COPY. The job transitions to the second
11082 * phase when the block job event with state VIR_DOMAIN_BLOCK_JOB_READY is
11083 * emitted for the given device. This information is also visible in the
11084 * live XML as 'ready="yes"' attribute of the corresponding <mirror> element.
11085 * All further changes are saved to both source and destination. The user must
11086 * call virDomainBlockJobAbort() to end the mirroring while choosing
11087 * whether to revert to source or pivot to the destination. An event is
11088 * issued when the job ends, and depending on the hypervisor, an event may
11089 * also be issued when the job transitions from pulling to mirroring. If
11090 * the job is aborted, a new job will have to start over from the beginning
11091 * of the first phase.
11093 * Some hypervisors will restrict certain actions, such as virDomainSave()
11094 * or virDomainDetachDevice(), while a copy job is active; they may
11095 * also restrict a copy job to transient domains.
11097 * If @flags contains VIR_DOMAIN_BLOCK_COPY_TRANSIENT_JOB the job will not be
11098 * recoverable if the VM is turned off while job is active. This flag will
11099 * remove the restriction of copy jobs to transient domains. Note that this flag
11100 * is automatically implied if the VM is transient at the time it's started.
11102 * If @flags contains VIR_DOMAIN_BLOCK_COPY_SYNCHRONOUS_WRITES the job will wait
11103 * for guest writes to be propagated both to the original image and to the
11104 * destination of the copy so that it's guaranteed that the job converges if
11105 * the destination storage is slower. This may impact performance of writes
11106 * while the blockjob is running.
11108 * The @disk parameter is either an unambiguous source name of the
11109 * block device (the <source file='...'/> sub-element, such as
11110 * "/path/to/image"), or the device target shorthand (the
11111 * <target dev='...'/> sub-element, such as "vda"). Valid names
11112 * can be found by calling virDomainGetXMLDesc() and inspecting
11113 * elements within //domain/devices/disk.
11115 * The @params and @nparams arguments can be used to set hypervisor-specific
11116 * tuning parameters, such as maximum bandwidth or granularity. For a
11117 * parameter that the hypervisor understands, explicitly specifying 0
11118 * behaves the same as omitting the parameter, to use the hypervisor
11119 * default; however, omitting a parameter is less likely to fail.
11121 * This command is a superset of the older virDomainBlockRebase() when used
11122 * with the VIR_DOMAIN_BLOCK_REBASE_COPY flag, and offers better control
11123 * over the destination format, the ability to copy to a destination that
11124 * is not a local file, and the possibility of additional tuning parameters.
11126 * Returns 0 if the operation has started, -1 on failure.
11131 virDomainBlockCopy(virDomainPtr dom
, const char *disk
,
11132 const char *destxml
,
11133 virTypedParameterPtr params
,
11135 unsigned int flags
)
11137 virConnectPtr conn
;
11139 VIR_DOMAIN_DEBUG(dom
,
11140 "disk=%s, destxml=%s, params=%p, nparams=%d, flags=0x%x",
11141 disk
, destxml
, params
, nparams
, flags
);
11142 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
11144 virResetLastError();
11146 virCheckDomainReturn(dom
, -1);
11149 virCheckReadOnlyGoto(conn
->flags
, error
);
11150 virCheckNonNullArgGoto(disk
, error
);
11151 virCheckNonNullArgGoto(destxml
, error
);
11152 virCheckNonNegativeArgGoto(nparams
, error
);
11154 virCheckNonNullArgGoto(params
, error
);
11156 if (conn
->driver
->domainBlockCopy
) {
11158 ret
= conn
->driver
->domainBlockCopy(dom
, disk
, destxml
,
11159 params
, nparams
, flags
);
11165 virReportUnsupportedError();
11168 virDispatchError(dom
->conn
);
11174 * virDomainBlockCommit:
11175 * @dom: pointer to domain object
11176 * @disk: path to the block device, or device shorthand
11177 * @base: path to backing file to merge into, or device shorthand,
11178 * or NULL for default
11179 * @top: path to file within backing chain that contains data to be merged,
11180 * or device shorthand, or NULL to merge all possible data
11181 * @bandwidth: (optional) specify bandwidth limit; flags determine the unit
11182 * @flags: bitwise-OR of virDomainBlockCommitFlags
11184 * Commit changes that were made to temporary top-level files within a disk
11185 * image backing file chain into a lower-level base file. In other words,
11186 * take all the difference between @base and @top, and update @base to contain
11187 * that difference; after the commit, any portion of the chain that previously
11188 * depended on @top will now depend on @base, and all files after @base up
11189 * to and including @top will now be invalidated. A typical use of this
11190 * command is to reduce the length of a backing file chain after taking an
11191 * external disk snapshot. To move data in the opposite direction, see
11192 * virDomainBlockPull().
11194 * This command starts a long-running commit block job, whose status may
11195 * be tracked by virDomainBlockJobInfo() with a job type of
11196 * VIR_DOMAIN_BLOCK_JOB_TYPE_COMMIT, and the operation can be aborted with
11197 * virDomainBlockJobAbort(). When finished, an asynchronous event is
11198 * raised to indicate the final status, and the job no longer exists. If
11199 * the job is aborted, it is up to the hypervisor whether starting a new
11200 * job will resume from the same point, or start over.
11202 * As a special case, if @top is the active image (or NULL), and @flags
11203 * includes VIR_DOMAIN_BLOCK_COMMIT_ACTIVE, the block job will have a type
11204 * of VIR_DOMAIN_BLOCK_JOB_TYPE_ACTIVE_COMMIT, and operates in two phases.
11205 * In the first phase, the contents are being committed into @base, and the
11206 * job can only be canceled. The job transitions to the second phase when
11207 * the block job event with state VIR_DOMAIN_BLOCK_JOB_READY is
11208 * emitted for the given device. This information is also visible in the
11209 * live XML as 'ready="yes"' attribute of the corresponding <mirror> element.
11210 * Once in the second phase, the user must choose whether to cancel the job
11211 * (keeping @top as the active image, but now containing only the changes
11212 * since the time the job ended) or to pivot the job (adjusting to @base as
11213 * the active image, and invalidating @top).
11215 * Be aware that this command may invalidate files even if it is aborted;
11216 * the user is cautioned against relying on the contents of invalidated
11217 * intermediate files such as @top (when @top is not the active image)
11218 * without manually rebasing those files to use a backing file of a
11219 * read-only copy of @base prior to the point where the commit operation
11220 * was started (and such a rebase cannot be safely done until the commit
11221 * has successfully completed). However, the domain itself will not have
11222 * any issues; the active layer remains valid throughout the entire commit
11225 * Some hypervisors may support a shortcut where if @flags contains
11226 * VIR_DOMAIN_BLOCK_COMMIT_DELETE, then this command will unlink all files
11227 * that were invalidated, after the commit successfully completes.
11229 * If @flags contains VIR_DOMAIN_BLOCK_COMMIT_RELATIVE, the name recorded
11230 * into the overlay of the @top image (if there is such image) as the
11231 * path to the new backing file will be kept relative to other images.
11232 * The operation will fail if libvirt can't infer the name.
11234 * By default, if @base is NULL, the commit target will be the bottom of
11235 * the backing chain; if @flags contains VIR_DOMAIN_BLOCK_COMMIT_SHALLOW,
11236 * then the immediate backing file of @top will be used instead. If @top
11237 * is NULL, the active image at the top of the chain will be used. Some
11238 * hypervisors place restrictions on how much can be committed, and might
11239 * fail if @base is not the immediate backing file of @top, or if @top is
11240 * the active layer in use by a running domain but @flags did not include
11241 * VIR_DOMAIN_BLOCK_COMMIT_ACTIVE, or if @top is not the top-most file;
11242 * restrictions may differ for online vs. offline domains.
11244 * The @disk parameter is either an unambiguous source name of the
11245 * block device (the <source file='...'/> sub-element, such as
11246 * "/path/to/image"), or the device target shorthand (the
11247 * <target dev='...'/> sub-element, such as "vda"). Valid names
11248 * can be found by calling virDomainGetXMLDesc() and inspecting
11249 * elements within //domain/devices/disk.
11251 * The @base and @top parameters can be either paths to files within the
11252 * backing chain, or the device target shorthand (the <target dev='...'/>
11253 * sub-element, such as "vda") followed by an index to the backing chain
11254 * enclosed in square brackets. Backing chain indexes can be found by
11255 * inspecting //disk//backingStore/@index in the domain XML. Thus, for
11256 * example, "vda[3]" refers to the backing store with index equal to "3"
11257 * in the chain of disk "vda".
11259 * The maximum bandwidth that will be used to do the commit can be
11260 * specified with the @bandwidth parameter. If set to 0, there is no
11261 * limit. If @flags includes VIR_DOMAIN_BLOCK_COMMIT_BANDWIDTH_BYTES,
11262 * @bandwidth is in bytes/second; otherwise, it is in MiB/second.
11263 * Values larger than 2^52 bytes/sec may be rejected due to overflow
11264 * considerations based on the word size of both client and server,
11265 * and values larger than 2^31 bytes/sec may cause overflow problems
11266 * if later queried by virDomainGetBlockJobInfo() without scaling.
11267 * Hypervisors may further restrict the range of valid bandwidth
11268 * values. Some hypervisors do not support this feature and will
11269 * return an error if bandwidth is not 0; in this case, it might still
11270 * be possible for a later call to virDomainBlockJobSetSpeed() to
11271 * succeed. The actual speed can be determined with
11272 * virDomainGetBlockJobInfo().
11274 * Returns 0 if the operation has started, -1 on failure.
11279 virDomainBlockCommit(virDomainPtr dom
, const char *disk
,
11280 const char *base
, const char *top
,
11281 unsigned long bandwidth
, unsigned int flags
)
11283 virConnectPtr conn
;
11285 VIR_DOMAIN_DEBUG(dom
, "disk=%s, base=%s, top=%s, bandwidth=%lu, flags=0x%x",
11286 disk
, NULLSTR(base
), NULLSTR(top
), bandwidth
, flags
);
11288 virResetLastError();
11290 virCheckDomainReturn(dom
, -1);
11293 virCheckReadOnlyGoto(conn
->flags
, error
);
11294 virCheckNonNullArgGoto(disk
, error
);
11296 if (conn
->driver
->domainBlockCommit
) {
11298 ret
= conn
->driver
->domainBlockCommit(dom
, disk
, base
, top
, bandwidth
,
11305 virReportUnsupportedError();
11308 virDispatchError(dom
->conn
);
11314 * virDomainOpenGraphics:
11315 * @dom: pointer to domain object
11316 * @idx: index of graphics config to open
11317 * @fd: file descriptor to attach graphics to
11318 * @flags: bitwise-OR of virDomainOpenGraphicsFlags
11320 * This will attempt to connect the file descriptor @fd, to
11321 * the graphics backend of @dom. If @dom has multiple graphics
11322 * backends configured, then @idx will determine which one is
11323 * opened, starting from @idx 0.
11325 * To disable any authentication, pass the VIR_DOMAIN_OPEN_GRAPHICS_SKIPAUTH
11326 * constant for @flags.
11328 * The caller should use an anonymous socketpair to open
11329 * @fd before invocation.
11331 * This method can only be used when connected to a local
11332 * libvirt hypervisor, over a UNIX domain socket. Attempts
11333 * to use this method over a TCP connection will always fail
11335 * Returns 0 on success, -1 on failure
11340 virDomainOpenGraphics(virDomainPtr dom
,
11343 unsigned int flags
)
11348 VIR_DOMAIN_DEBUG(dom
, "idx=%u, fd=%d, flags=0x%x",
11351 virResetLastError();
11353 virCheckDomainReturn(dom
, -1);
11354 virCheckNonNegativeArgGoto(fd
, error
);
11356 if (fstat(fd
, &sb
) < 0) {
11357 virReportSystemError(errno
,
11358 _("Unable to access file descriptor %1$d"), fd
);
11363 if (!S_ISSOCK(sb
.st_mode
)) {
11364 virReportInvalidArg(fd
,
11365 _("fd %1$d must be a socket"),
11369 #endif /* !WIN32 */
11371 virCheckReadOnlyGoto(dom
->conn
->flags
, error
);
11373 rc
= VIR_DRV_SUPPORTS_FEATURE(dom
->conn
->driver
, dom
->conn
,
11374 VIR_DRV_FEATURE_FD_PASSING
);
11377 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
11378 _("fd passing is not supported by this connection"));
11382 if (dom
->conn
->driver
->domainOpenGraphics
) {
11384 ret
= dom
->conn
->driver
->domainOpenGraphics(dom
, idx
, fd
, flags
);
11390 virReportUnsupportedError();
11393 virDispatchError(dom
->conn
);
11399 * virDomainOpenGraphicsFD:
11400 * @dom: pointer to domain object
11401 * @idx: index of graphics config to open
11402 * @flags: bitwise-OR of virDomainOpenGraphicsFlags
11404 * This will create a socket pair connected to the graphics backend of @dom.
11405 * One end of the socket will be returned on success, and the other end is
11406 * handed to the hypervisor.
11407 * If @dom has multiple graphics backends configured, then @idx will determine
11408 * which one is opened, starting from @idx 0.
11410 * To disable any authentication, pass the VIR_DOMAIN_OPEN_GRAPHICS_SKIPAUTH
11411 * constant for @flags.
11413 * This method can only be used when connected to a local
11414 * libvirt hypervisor, over a UNIX domain socket. Attempts
11415 * to use this method over a TCP connection will always fail.
11417 * Returns an fd on success, -1 on failure
11422 virDomainOpenGraphicsFD(virDomainPtr dom
,
11424 unsigned int flags
)
11428 VIR_DOMAIN_DEBUG(dom
, "idx=%u, flags=0x%x", idx
, flags
);
11430 virResetLastError();
11432 virCheckDomainReturn(dom
, -1);
11434 virCheckReadOnlyGoto(dom
->conn
->flags
, error
);
11436 rc
= VIR_DRV_SUPPORTS_FEATURE(dom
->conn
->driver
, dom
->conn
,
11437 VIR_DRV_FEATURE_FD_PASSING
);
11441 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
11442 _("fd passing is not supported by this connection"));
11446 if (dom
->conn
->driver
->domainOpenGraphicsFD
) {
11448 ret
= dom
->conn
->driver
->domainOpenGraphicsFD(dom
, idx
, flags
);
11454 virReportUnsupportedError();
11457 virDispatchError(dom
->conn
);
11463 * virDomainSetBlockIoTune:
11464 * @dom: pointer to domain object
11465 * @disk: path to the block device, or device shorthand
11466 * @params: Pointer to blkio parameter objects
11467 * @nparams: Number of blkio parameters (this value can be the same or
11468 * less than the number of parameters supported)
11469 * @flags: bitwise-OR of virDomainModificationImpact
11471 * Change all or a subset of the per-device block IO tunables.
11473 * The @disk parameter is either an unambiguous source name of the
11474 * block device (the <source file='...'/> sub-element, such as
11475 * "/path/to/image"), or the device target shorthand (the <target
11476 * dev='...'/> sub-element, such as "xvda"). Valid names can be found
11477 * by calling virDomainGetXMLDesc() and inspecting elements
11478 * within //domain/devices/disk.
11480 * Returns -1 in case of error, 0 in case of success.
11485 virDomainSetBlockIoTune(virDomainPtr dom
,
11487 virTypedParameterPtr params
,
11489 unsigned int flags
)
11491 virConnectPtr conn
;
11493 VIR_DOMAIN_DEBUG(dom
, "disk=%s, params=%p, nparams=%d, flags=0x%x",
11494 disk
, params
, nparams
, flags
);
11495 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
11497 virResetLastError();
11499 virCheckDomainReturn(dom
, -1);
11502 virCheckReadOnlyGoto(conn
->flags
, error
);
11503 virCheckNonNullArgGoto(disk
, error
);
11504 virCheckPositiveArgGoto(nparams
, error
);
11505 virCheckNonNullArgGoto(params
, error
);
11507 if (virTypedParameterValidateSet(dom
->conn
, params
, nparams
) < 0)
11510 if (conn
->driver
->domainSetBlockIoTune
) {
11512 ret
= conn
->driver
->domainSetBlockIoTune(dom
, disk
, params
, nparams
, flags
);
11518 virReportUnsupportedError();
11521 virDispatchError(dom
->conn
);
11527 * virDomainGetBlockIoTune:
11528 * @dom: pointer to domain object
11529 * @disk: path to the block device, or device shorthand
11530 * @params: Pointer to blkio parameter object
11531 * (return value, allocated by the caller)
11532 * @nparams: Pointer to number of blkio parameters
11533 * @flags: bitwise-OR of virDomainModificationImpact and virTypedParameterFlags
11535 * Get all block IO tunable parameters for a given device. On input,
11536 * @nparams gives the size of the @params array; on output, @nparams
11537 * gives how many slots were filled with parameter information, which
11538 * might be less but will not exceed the input value.
11540 * As a special case, calling with @params as NULL and @nparams as 0
11541 * on input will cause @nparams on output to contain the number of
11542 * parameters supported by the hypervisor, either for the given @disk
11543 * (note that block devices of different types might support different
11544 * parameters), or if @disk is NULL, for all possible disks. The
11545 * caller should then allocate @params array,
11546 * i.e. (sizeof(@virTypedParameter) * @nparams) bytes and call the API
11547 * again. See virDomainGetMemoryParameters() for more details.
11549 * The @disk parameter is either an unambiguous source name of the
11550 * block device (the <source file='...'/> sub-element, such as
11551 * "/path/to/image"), or the device target shorthand (the <target
11552 * dev='...'/> sub-element, such as "xvda"). Valid names can be found
11553 * by calling virDomainGetXMLDesc() and inspecting elements
11554 * within //domain/devices/disk. This parameter cannot be NULL
11555 * unless @nparams is 0 on input.
11557 * Returns -1 in case of error, 0 in case of success.
11562 virDomainGetBlockIoTune(virDomainPtr dom
,
11564 virTypedParameterPtr params
,
11566 unsigned int flags
)
11568 virConnectPtr conn
;
11571 VIR_DOMAIN_DEBUG(dom
, "disk=%s, params=%p, nparams=%d, flags=0x%x",
11572 NULLSTR(disk
), params
, (nparams
) ? *nparams
: -1, flags
);
11574 virResetLastError();
11576 virCheckDomainReturn(dom
, -1);
11578 virCheckNonNullArgGoto(nparams
, error
);
11579 virCheckNonNegativeArgGoto(*nparams
, error
);
11580 if (*nparams
!= 0) {
11581 virCheckNonNullArgGoto(params
, error
);
11582 virCheckNonNullArgGoto(disk
, error
);
11585 rc
= VIR_DRV_SUPPORTS_FEATURE(dom
->conn
->driver
, dom
->conn
,
11586 VIR_DRV_FEATURE_TYPED_PARAM_STRING
);
11590 flags
|= VIR_TYPED_PARAM_STRING_OKAY
;
11592 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_AFFECT_LIVE
,
11593 VIR_DOMAIN_AFFECT_CONFIG
,
11598 if (conn
->driver
->domainGetBlockIoTune
) {
11600 ret
= conn
->driver
->domainGetBlockIoTune(dom
, disk
, params
, nparams
, flags
);
11606 virReportUnsupportedError();
11609 virDispatchError(dom
->conn
);
11615 * virDomainGetCPUStats:
11616 * @domain: domain to query
11617 * @params: array to populate on output
11618 * @nparams: number of parameters per cpu
11619 * @start_cpu: which cpu to start with, or -1 for summary
11620 * @ncpus: how many cpus to query
11621 * @flags: bitwise-OR of virTypedParameterFlags
11623 * Get statistics relating to CPU usage attributable to a single
11624 * domain (in contrast to the statistics returned by
11625 * virNodeGetCPUStats() for all processes on the host). @dom
11626 * must be running (an inactive domain has no attributable cpu
11627 * usage). On input, @params must contain at least @nparams * @ncpus
11628 * entries, allocated by the caller.
11630 * If @start_cpu is -1, then @ncpus must be 1, and the returned
11631 * results reflect the statistics attributable to the entire
11632 * domain (such as user and system time for the process as a
11633 * whole). Otherwise, @start_cpu represents which cpu to start
11634 * with, and @ncpus represents how many consecutive processors to
11635 * query, with statistics attributable per processor (such as
11636 * per-cpu usage). If @ncpus is larger than the number of cpus
11637 * available to query, then the trailing part of the array will
11640 * The remote driver imposes a limit of 128 @ncpus and 16 @nparams;
11641 * the number of parameters per cpu should not exceed 16, but if you
11642 * have a host with more than 128 CPUs, your program should split
11643 * the request into multiple calls.
11645 * As special cases, if @params is NULL and @nparams is 0 and
11646 * @ncpus is 1, and the return value will be how many
11647 * statistics are available for the given @start_cpu. This number
11648 * may be different for @start_cpu of -1 than for any non-negative
11649 * value, but will be the same for all non-negative @start_cpu.
11650 * Likewise, if @params is NULL and @nparams is 0 and @ncpus is 0,
11651 * the number of cpus available to query is returned. From the
11652 * host perspective, this would typically match the cpus member
11653 * of virNodeGetInfo(), but might be less due to host cpu hotplug.
11655 * For now, @flags is unused, and the statistics all relate to the
11656 * usage from the host perspective. It is possible that a future
11657 * version will support a flag that queries the cpu usage from the
11658 * guest's perspective, where the maximum cpu to query would be
11659 * related to virDomainGetVcpusFlags() rather than virNodeGetInfo().
11660 * An individual guest vcpu cannot be reliably mapped back to a
11661 * specific host cpu unless a single-processor vcpu pinning was used,
11662 * but when @start_cpu is -1, any difference in usage between a host
11663 * and guest perspective would serve as a measure of hypervisor overhead.
11665 * Typical use sequence is below.
11667 * getting total stats: set start_cpu as -1, ncpus 1
11669 * virDomainGetCPUStats(dom, NULL, 0, -1, 1, 0); // nparams
11670 * params = calloc(nparams, sizeof(virTypedParameter))
11671 * virDomainGetCPUStats(dom, params, nparams, -1, 1, 0); // total stats.
11673 * getting per-cpu stats:
11675 * virDomainGetCPUStats(dom, NULL, 0, 0, 0, 0); // ncpus
11676 * virDomainGetCPUStats(dom, NULL, 0, 0, 1, 0); // nparams
11677 * params = calloc(ncpus * nparams, sizeof(virTypedParameter));
11678 * virDomainGetCPUStats(dom, params, nparams, 0, ncpus, 0); // per-cpu stats
11680 * Returns -1 on failure, or the number of statistics that were
11681 * populated per cpu on success (this will be less than the total
11682 * number of populated @params, unless @ncpus was 1; and may be
11683 * less than @nparams). The populated parameters start at each
11684 * stride of @nparams, which means the results may be discontiguous;
11685 * any unpopulated parameters will be zeroed on success (this includes
11686 * skipped elements if @nparams is too large, and tail elements if
11687 * @ncpus is too large). The caller is responsible for freeing any
11688 * returned string parameters.
11693 virDomainGetCPUStats(virDomainPtr domain
,
11694 virTypedParameterPtr params
,
11695 unsigned int nparams
,
11697 unsigned int ncpus
,
11698 unsigned int flags
)
11700 virConnectPtr conn
;
11703 VIR_DOMAIN_DEBUG(domain
,
11704 "params=%p, nparams=%d, start_cpu=%d, ncpus=%u, flags=0x%x",
11705 params
, nparams
, start_cpu
, ncpus
, flags
);
11706 virResetLastError();
11708 virCheckDomainReturn(domain
, -1);
11709 conn
= domain
->conn
;
11712 * start_cpu must be non-negative, or else -1
11713 * if start_cpu is -1, ncpus must be 1
11714 * params == NULL must match nparams == 0
11715 * ncpus must be non-zero unless params == NULL
11716 * nparams * ncpus must not overflow (RPC may restrict it even more)
11718 if (start_cpu
== -1) {
11720 virReportInvalidArg(start_cpu
, "%s",
11721 _("ncpus must be 1 when start_cpu is -1"));
11725 virCheckNonNegativeArgGoto(start_cpu
, error
);
11728 virCheckNonNullArgGoto(params
, error
);
11730 virCheckNullArgGoto(params
, error
);
11732 virCheckNullArgGoto(params
, error
);
11734 if (nparams
&& ncpus
> UINT_MAX
/ nparams
) {
11735 virReportError(VIR_ERR_OVERFLOW
, _("input too large: %1$u * %2$u"),
11739 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
11740 VIR_DRV_FEATURE_TYPED_PARAM_STRING
);
11744 flags
|= VIR_TYPED_PARAM_STRING_OKAY
;
11746 if (conn
->driver
->domainGetCPUStats
) {
11749 ret
= conn
->driver
->domainGetCPUStats(domain
, params
, nparams
,
11750 start_cpu
, ncpus
, flags
);
11756 virReportUnsupportedError();
11759 virDispatchError(domain
->conn
);
11765 * virDomainGetDiskErrors:
11766 * @dom: a domain object
11767 * @errors: array to populate on output
11768 * @maxerrors: size of @errors array
11769 * @flags: extra flags; not used yet, so callers should always pass 0
11771 * The function populates @errors array with all disks that encountered an
11772 * I/O error. Disks with no error will not be returned in the @errors array.
11773 * Each disk is identified by its target (the dev attribute of target
11774 * subelement in domain XML), such as "vda", and accompanied with the error
11775 * that was seen on it. The caller is also responsible for calling free()
11776 * on each disk name returned.
11778 * In a special case when @errors is NULL and @maxerrors is 0, the function
11779 * returns preferred size of @errors that the caller should use to get all
11782 * Since calling virDomainGetDiskErrors(dom, NULL, 0, 0) to get preferred size
11783 * of @errors array and getting the errors are two separate operations, new
11784 * disks may be hotplugged to the domain and new errors may be encountered
11785 * between the two calls. Thus, this function may not return all disk errors
11786 * because the supplied array is not large enough. Such errors may, however,
11787 * be detected by listening to domain events.
11789 * Returns number of disks with errors filled in the @errors array or -1 on
11795 virDomainGetDiskErrors(virDomainPtr dom
,
11796 virDomainDiskErrorPtr errors
,
11797 unsigned int maxerrors
,
11798 unsigned int flags
)
11800 VIR_DOMAIN_DEBUG(dom
, "errors=%p, maxerrors=%u, flags=0x%x",
11801 errors
, maxerrors
, flags
);
11803 virResetLastError();
11805 virCheckDomainReturn(dom
, -1);
11807 virCheckNonNullArrayArgGoto(errors
, maxerrors
, error
);
11809 if (dom
->conn
->driver
->domainGetDiskErrors
) {
11810 int ret
= dom
->conn
->driver
->domainGetDiskErrors(dom
, errors
,
11817 virReportUnsupportedError();
11820 virDispatchError(dom
->conn
);
11826 * virDomainGetHostname:
11827 * @domain: a domain object
11828 * @flags: bitwise-OR of virDomainGetHostnameFlags
11830 * Get the hostname for that domain. If no hostname is found,
11831 * then an error is raised with VIR_ERR_NO_HOSTNAME code.
11833 * Dependent on hypervisor and @flags used, this may require a
11834 * guest agent to be available.
11836 * Returns the hostname which must be freed by the caller, or
11837 * NULL if there was an error.
11842 virDomainGetHostname(virDomainPtr domain
, unsigned int flags
)
11844 virConnectPtr conn
;
11846 VIR_DOMAIN_DEBUG(domain
, "flags=0x%x", flags
);
11848 virResetLastError();
11850 virCheckDomainReturn(domain
, NULL
);
11851 conn
= domain
->conn
;
11853 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
11855 if (conn
->driver
->domainGetHostname
) {
11857 ret
= conn
->driver
->domainGetHostname(domain
, flags
);
11863 virReportUnsupportedError();
11866 virDispatchError(domain
->conn
);
11873 * @dom: a domain object
11874 * @mountPoint: which mount point to trim
11875 * @minimum: Minimum contiguous free range to discard in bytes
11876 * @flags: extra flags, not used yet, so callers should always pass 0
11878 * Calls FITRIM within the guest (hence guest agent may be
11879 * required depending on hypervisor used). Either call it on each
11880 * mounted filesystem (@mountPoint is NULL) or just on specified
11881 * @mountPoint. @minimum hints that free ranges smaller than this
11882 * may be ignored (this is a hint and the guest may not respect
11883 * it). By increasing this value, the fstrim operation will
11884 * complete more quickly for filesystems with badly fragmented
11885 * free space, although not all blocks will be discarded.
11886 * If @minimum is not zero, the command may fail.
11888 * Returns 0 on success, -1 otherwise.
11893 virDomainFSTrim(virDomainPtr dom
,
11894 const char *mountPoint
,
11895 unsigned long long minimum
,
11896 unsigned int flags
)
11898 VIR_DOMAIN_DEBUG(dom
, "mountPoint=%s, minimum=%llu, flags=0x%x",
11899 mountPoint
, minimum
, flags
);
11901 virResetLastError();
11903 virCheckDomainReturn(dom
, -1);
11904 virCheckReadOnlyGoto(dom
->conn
->flags
, error
);
11906 if (dom
->conn
->driver
->domainFSTrim
) {
11907 int ret
= dom
->conn
->driver
->domainFSTrim(dom
, mountPoint
,
11914 virReportUnsupportedError();
11917 virDispatchError(dom
->conn
);
11922 * virDomainFSFreeze:
11923 * @dom: a domain object
11924 * @mountpoints: list of mount points to be frozen
11925 * @nmountpoints: the number of mount points specified in @mountpoints
11926 * @flags: extra flags; not used yet, so callers should always pass 0
11928 * Freeze specified filesystems within the guest (hence guest agent
11929 * may be required depending on hypervisor used). If @mountpoints is NULL and
11930 * @nmountpoints is 0, every mounted filesystem on the guest is frozen.
11931 * In some environments (e.g. QEMU guest with guest agent which doesn't
11932 * support mountpoints argument), @mountpoints may need to be NULL.
11934 * Returns the number of frozen filesystems on success, -1 otherwise.
11939 virDomainFSFreeze(virDomainPtr dom
,
11940 const char **mountpoints
,
11941 unsigned int nmountpoints
,
11942 unsigned int flags
)
11944 VIR_DOMAIN_DEBUG(dom
, "mountpoints=%p, nmountpoints=%d, flags=0x%x",
11945 mountpoints
, nmountpoints
, flags
);
11947 virResetLastError();
11949 virCheckDomainReturn(dom
, -1);
11950 virCheckReadOnlyGoto(dom
->conn
->flags
, error
);
11951 virCheckNonNullArrayArgGoto(mountpoints
, nmountpoints
, error
);
11953 if (dom
->conn
->driver
->domainFSFreeze
) {
11954 int ret
= dom
->conn
->driver
->domainFSFreeze(
11955 dom
, mountpoints
, nmountpoints
, flags
);
11961 virReportUnsupportedError();
11964 virDispatchError(dom
->conn
);
11970 * @dom: a domain object
11971 * @mountpoints: list of mount points to be thawed
11972 * @nmountpoints: the number of mount points specified in @mountpoints
11973 * @flags: extra flags; not used yet, so callers should always pass 0
11975 * Thaw specified filesystems within the guest. If @mountpoints is NULL and
11976 * @nmountpoints is 0, every mounted filesystem on the guest is thawed.
11977 * In some drivers (e.g. QEMU driver), @mountpoints may need to be NULL.
11979 * Returns the number of thawed filesystems on success, -1 otherwise.
11984 virDomainFSThaw(virDomainPtr dom
,
11985 const char **mountpoints
,
11986 unsigned int nmountpoints
,
11987 unsigned int flags
)
11989 VIR_DOMAIN_DEBUG(dom
, "flags=0x%x", flags
);
11991 virResetLastError();
11993 virCheckDomainReturn(dom
, -1);
11994 virCheckReadOnlyGoto(dom
->conn
->flags
, error
);
11995 virCheckNonNullArrayArgGoto(mountpoints
, nmountpoints
, error
);
11997 if (dom
->conn
->driver
->domainFSThaw
) {
11998 int ret
= dom
->conn
->driver
->domainFSThaw(
11999 dom
, mountpoints
, nmountpoints
, flags
);
12005 virReportUnsupportedError();
12008 virDispatchError(dom
->conn
);
12013 * virDomainGetTime:
12014 * @dom: a domain object
12015 * @seconds: domain's time in seconds
12016 * @nseconds: the nanosecond part of @seconds
12017 * @flags: extra flags; not used yet, so callers should always pass 0
12019 * Extract information about guest time and store it into
12020 * @seconds and @nseconds. The @seconds represents the number of
12021 * seconds since the UNIX Epoch of 1970-01-01 00:00:00 in UTC.
12023 * Please note that some hypervisors may require guest agent to
12024 * be configured and running in order to run this API.
12026 * Returns 0 on success, -1 otherwise.
12031 virDomainGetTime(virDomainPtr dom
,
12032 long long *seconds
,
12033 unsigned int *nseconds
,
12034 unsigned int flags
)
12036 VIR_DOMAIN_DEBUG(dom
, "seconds=%p, nseconds=%p, flags=0x%x",
12037 seconds
, nseconds
, flags
);
12039 virResetLastError();
12041 virCheckDomainReturn(dom
, -1);
12042 virCheckReadOnlyGoto(dom
->conn
->flags
, error
);
12044 if (dom
->conn
->driver
->domainGetTime
) {
12045 int ret
= dom
->conn
->driver
->domainGetTime(dom
, seconds
,
12052 virReportUnsupportedError();
12055 virDispatchError(dom
->conn
);
12060 * virDomainSetTime:
12061 * @dom: a domain object
12062 * @seconds: time to set
12063 * @nseconds: the nanosecond part of @seconds
12064 * @flags: bitwise-OR of virDomainSetTimeFlags
12066 * When a domain is suspended or restored from a file the
12067 * domain's OS has no idea that there was a big gap in the time.
12068 * Depending on how long the gap was, NTP might not be able to
12069 * resynchronize the guest.
12071 * This API tries to set guest time to the given value. The time
12072 * to set (@seconds and @nseconds) should be in seconds relative
12073 * to the Epoch of 1970-01-01 00:00:00 in UTC.
12075 * Please note that some hypervisors may require guest agent to
12076 * be configured and running in order to be able to run this API.
12078 * Returns 0 on success, -1 otherwise.
12083 virDomainSetTime(virDomainPtr dom
,
12085 unsigned int nseconds
,
12086 unsigned int flags
)
12088 VIR_DOMAIN_DEBUG(dom
, "seconds=%lld, nseconds=%u, flags=0x%x",
12089 seconds
, nseconds
, flags
);
12091 virResetLastError();
12093 virCheckDomainReturn(dom
, -1);
12094 virCheckReadOnlyGoto(dom
->conn
->flags
, error
);
12096 if (dom
->conn
->driver
->domainSetTime
) {
12097 int ret
= dom
->conn
->driver
->domainSetTime(dom
, seconds
,
12104 virReportUnsupportedError();
12107 virDispatchError(dom
->conn
);
12113 * virDomainSetUserPassword:
12114 * @dom: a domain object
12115 * @user: the username that will get a new password
12116 * @password: the password to set
12117 * @flags: bitwise-OR of virDomainSetUserPasswordFlags
12119 * Sets the @user password to the value specified by @password.
12120 * If @flags contain VIR_DOMAIN_PASSWORD_ENCRYPTED, the password
12121 * is assumed to be encrypted by the method required by the guest OS.
12123 * Please note that some hypervisors may require guest agent to
12124 * be configured and running in order to be able to run this API.
12126 * Returns 0 on success, -1 otherwise.
12131 virDomainSetUserPassword(virDomainPtr dom
,
12133 const char *password
,
12134 unsigned int flags
)
12136 VIR_DOMAIN_DEBUG(dom
, "user=%s, password=%s, flags=0x%x",
12137 NULLSTR(user
), NULLSTR(password
), flags
);
12139 virResetLastError();
12141 virCheckDomainReturn(dom
, -1);
12142 virCheckReadOnlyGoto(dom
->conn
->flags
, error
);
12143 virCheckNonNullArgGoto(user
, error
);
12144 virCheckNonNullArgGoto(password
, error
);
12146 if (dom
->conn
->driver
->domainSetUserPassword
) {
12147 int ret
= dom
->conn
->driver
->domainSetUserPassword(dom
, user
, password
,
12154 virReportUnsupportedError();
12157 virDispatchError(dom
->conn
);
12163 * virConnectGetDomainCapabilities:
12164 * @conn: pointer to the hypervisor connection
12165 * @emulatorbin: path to emulator
12166 * @arch: domain architecture
12167 * @machine: machine type
12168 * @virttype: virtualization type
12169 * @flags: extra flags; not used yet, so callers should always pass 0
12171 * Prior creating a domain (for instance via virDomainCreateXML
12172 * or virDomainDefineXML) it may be suitable to know what the
12173 * underlying emulator and/or libvirt is capable of. For
12174 * instance, if host, libvirt and qemu is capable of VFIO
12175 * passthrough and so on.
12177 * Returns NULL in case of error or an XML string
12178 * defining the capabilities.
12183 virConnectGetDomainCapabilities(virConnectPtr conn
,
12184 const char *emulatorbin
,
12186 const char *machine
,
12187 const char *virttype
,
12188 unsigned int flags
)
12190 VIR_DEBUG("conn=%p, emulatorbin=%s, arch=%s, "
12191 "machine=%s, virttype=%s, flags=0x%x",
12192 conn
, NULLSTR(emulatorbin
), NULLSTR(arch
),
12193 NULLSTR(machine
), NULLSTR(virttype
), flags
);
12195 virResetLastError();
12197 virCheckConnectReturn(conn
, NULL
);
12198 virCheckReadOnlyGoto(conn
->flags
, error
);
12200 if (conn
->driver
->connectGetDomainCapabilities
) {
12202 ret
= conn
->driver
->connectGetDomainCapabilities(conn
, emulatorbin
,
12207 VIR_DEBUG("conn=%p, ret=%s", conn
, ret
);
12211 virReportUnsupportedError();
12214 virDispatchError(conn
);
12220 * virConnectGetAllDomainStats:
12221 * @conn: pointer to the hypervisor connection
12222 * @stats: stats to return, binary-OR of virDomainStatsTypes
12223 * @retStats: Pointer that will be filled with the array of returned stats
12224 * @flags: extra flags; binary-OR of virConnectGetAllDomainStatsFlags
12226 * Query statistics for all domains on a given connection.
12228 * Report statistics of various parameters for a running VM according to @stats
12229 * field. The statistics are returned as an array of structures for each queried
12230 * domain. The structure contains an array of typed parameters containing the
12231 * individual statistics. The typed parameter name for each statistic field
12232 * consists of a dot-separated string containing name of the requested group
12233 * followed by a group specific description of the statistic value.
12235 * The statistic groups are enabled using the @stats parameter which is a
12236 * binary-OR of enum virDomainStatsTypes. The following groups are available
12237 * (although not necessarily implemented for each hypervisor):
12239 * VIR_DOMAIN_STATS_STATE:
12240 * Return domain state and reason for entering that state. The typed
12241 * parameter keys are in this format:
12243 * "state.state" - state of the VM, returned as int from virDomainState enum
12244 * "state.reason" - reason for entering given state, returned as int from
12245 * virDomain*Reason enum corresponding to given state.
12247 * VIR_DOMAIN_STATS_CPU_TOTAL:
12248 * Return CPU statistics and usage information. The typed parameter keys
12249 * are in this format:
12251 * "cpu.time" - total cpu time spent for this domain in nanoseconds
12252 * as unsigned long long.
12253 * "cpu.user" - user cpu time spent in nanoseconds as unsigned long long.
12254 * "cpu.system" - system cpu time spent in nanoseconds as unsigned long
12256 * "cpu.haltpoll.success.time" - halt-polling cpu usage about the VCPU polled
12257 * until a virtual interrupt was delivered in
12258 * nanoseconds as unsigned long long.
12259 * "cpu.haltpoll.fail.time" - halt-polling cpu usage about the VCPU had to schedule
12260 * out (either because the maximum poll time was reached
12261 * or it needed to yield the CPU) in nanoseconds as
12262 * unsigned long long.
12263 * "cpu.cache.monitor.count" - the number of cache monitors for this domain
12264 * "cpu.cache.monitor.<num>.name" - the name of cache monitor <num>
12265 * "cpu.cache.monitor.<num>.vcpus" - vcpu list of cache monitor <num>
12266 * "cpu.cache.monitor.<num>.bank.count" - the number of cache banks in
12267 * cache monitor <num>
12268 * "cpu.cache.monitor.<num>.bank.<index>.id" - host allocated cache id for
12269 * bank <index> in cache
12271 * "cpu.cache.monitor.<num>.bank.<index>.bytes" - the number of bytes of
12272 * last level cache that the
12273 * domain is using on cache
12276 * VIR_DOMAIN_STATS_BALLOON:
12277 * Return memory balloon device information.
12278 * The typed parameter keys are in this format:
12280 * "balloon.current" - the memory in kiB currently used
12281 * as unsigned long long.
12282 * "balloon.maximum" - the maximum memory in kiB allowed
12283 * as unsigned long long.
12284 * "balloon.swap_in" - the amount of data read from swap space (in KiB)
12285 * as unsigned long long
12286 * "balloon.swap_out" - the amount of memory written out to swap space
12287 * (in KiB) as unsigned long long
12288 * "balloon.major_fault" - the number of page faults when disk IO was
12289 * required as unsigned long long
12290 * "balloon.minor_fault" - the number of other page faults
12291 * as unsigned long long
12292 * "balloon.unused" - the amount of memory left unused by the system
12293 * (in KiB) as unsigned long long
12294 * "balloon.available" - the amount of usable memory as seen by the domain
12295 * (in KiB) as unsigned long long
12296 * "balloon.rss" - Resident Set Size of running domain's process
12297 * (in KiB) as unsigned long long
12298 * "balloon.usable" - the amount of memory which can be reclaimed by balloon
12299 * without causing host swapping (in KiB)
12300 * as unsigned long long
12301 * "balloon.last-update" - timestamp of the last update of statistics
12302 * (in seconds) as unsigned long long
12303 * "balloon.disk_caches" - the amount of memory that can be reclaimed
12304 * without additional I/O, typically disk (in KiB)
12305 * as unsigned long long
12306 * "balloon.hugetlb_pgalloc" - the number of successful huge page allocations
12307 * from inside the domain via virtio balloon
12308 * as unsigned long long
12309 * "balloon.hugetlb_pgfail" - the number of failed huge page allocations
12310 * from inside the domain via virtio balloon
12311 * as unsigned long long
12313 * VIR_DOMAIN_STATS_VCPU:
12314 * Return virtual CPU statistics.
12315 * Due to VCPU hotplug, the vcpu.<num>.* array could be sparse.
12316 * The actual size of the array corresponds to "vcpu.current".
12317 * The array size will never exceed "vcpu.maximum".
12318 * The typed parameter keys are in this format:
12320 * "vcpu.current" - current number of online virtual CPUs as unsigned int.
12321 * "vcpu.maximum" - maximum number of online virtual CPUs as unsigned int.
12322 * "vcpu.<num>.state" - state of the virtual CPU <num>, as int
12323 * from virVcpuState enum.
12324 * "vcpu.<num>.time" - virtual cpu time spent by virtual CPU <num>
12325 * as unsigned long long.
12326 * "vcpu.<num>.wait" - time the vCPU <num> wants to run, but the host
12327 * scheduler has something else running ahead of it.
12328 * "vcpu.<num>.halted" - virtual CPU <num> is halted, may indicate the
12329 * processor is idle or even disabled, depending
12330 * on the architecture)
12331 * "vcpu.<num>.delay" - time the vCPU <num> thread was enqueued by the
12332 * host scheduler, but was waiting in the queue
12333 * instead of running. Exposed to the VM as a steal
12336 * This group of statistics also reports additional hypervisor-originating
12337 * per-vCPU stats. The hypervisor-specific statistics in this group have the
12338 * following naming scheme:
12340 * "vcpu.<num>.$NAME.$TYPE"
12342 * $NAME - name of the statistics field provided by the hypervisor
12344 * $TYPE - Type of the value. The following types are returned:
12345 * 'cur' - current instant value
12346 * 'sum' - aggregate value
12347 * 'max' - peak value
12349 * The returned value may be either an unsigned long long or a boolean.
12350 * Meaning is hypervisor specific. Please see the disclaimer for the
12351 * VIR_DOMAIN_STATS_VM group below.
12353 * VIR_DOMAIN_STATS_INTERFACE:
12354 * Return network interface statistics (from domain point of view).
12355 * The typed parameter keys are in this format:
12357 * "net.count" - number of network interfaces on this domain
12359 * "net.<num>.name" - name of the interface <num> as string.
12360 * "net.<num>.rx.bytes" - bytes received as unsigned long long.
12361 * "net.<num>.rx.pkts" - packets received as unsigned long long.
12362 * "net.<num>.rx.errs" - receive errors as unsigned long long.
12363 * "net.<num>.rx.drop" - receive packets dropped as unsigned long long.
12364 * "net.<num>.tx.bytes" - bytes transmitted as unsigned long long.
12365 * "net.<num>.tx.pkts" - packets transmitted as unsigned long long.
12366 * "net.<num>.tx.errs" - transmission errors as unsigned long long.
12367 * "net.<num>.tx.drop" - transmit packets dropped as unsigned long long.
12369 * VIR_DOMAIN_STATS_BLOCK:
12370 * Return block devices statistics. By default,
12371 * this information is limited to the active layer of each <disk> of the
12372 * domain (where block.count is equal to the number of disks), but adding
12373 * VIR_CONNECT_GET_ALL_DOMAINS_STATS_BACKING to @flags will expand the
12374 * array to cover backing chains (block.count corresponds to the number
12375 * of host resources used together to provide the guest disks).
12376 * The typed parameter keys are in this format:
12378 * "block.count" - number of block devices in the subsequent list,
12380 * "block.<num>.name" - name of the block device <num> as string.
12381 * matches the target name (vda/sda/hda) of the
12382 * block device. If the backing chain is listed,
12383 * this name is the same for all host resources tied
12384 * to the same guest device.
12385 * "block.<num>.backingIndex" - unsigned int giving the <backingStore>
12386 * index, only used when backing images
12388 * "block.<num>.path" - string describing the source of block device <num>,
12389 * if it is a file or block device (omitted for network
12390 * sources and drives with no media inserted).
12391 * "block.<num>.rd.reqs" - number of read requests as unsigned long long.
12392 * "block.<num>.rd.bytes" - number of read bytes as unsigned long long.
12393 * "block.<num>.rd.times" - total time (ns) spent on reads as
12394 * unsigned long long.
12395 * "block.<num>.wr.reqs" - number of write requests as unsigned long long.
12396 * "block.<num>.wr.bytes" - number of written bytes as unsigned long long.
12397 * "block.<num>.wr.times" - total time (ns) spent on writes as
12398 * unsigned long long.
12399 * "block.<num>.fl.reqs" - total flush requests as unsigned long long.
12400 * "block.<num>.fl.times" - total time (ns) spent on cache flushing as
12401 * unsigned long long.
12402 * "block.<num>.errors" - Xen only: the 'oo_req' value as
12403 * unsigned long long.
12404 * "block.<num>.allocation" - offset of the highest written sector
12405 * as unsigned long long.
12406 * "block.<num>.capacity" - logical size in bytes of the block device
12407 * backing image as unsigned long long.
12408 * "block.<num>.physical" - physical size in bytes of the container of the
12409 * backing image as unsigned long long.
12410 * "block.<num>.threshold" - current threshold for delivering the
12411 * VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD
12412 * event in bytes. See virDomainSetBlockThreshold.
12414 * VIR_DOMAIN_STATS_PERF:
12415 * Return perf event statistics.
12416 * The typed parameter keys are in this format:
12418 * "perf.cmt" - the usage of l3 cache (bytes) by applications running on
12419 * the platform as unsigned long long. It is produced by cmt
12421 * "perf.mbmt" - the total system bandwidth (bytes/s) from one level of
12422 * cache to another as unsigned long long. It is produced
12423 * by mbmt perf event.
12424 * "perf.mbml" - the amount of data (bytes/s) sent through the memory
12425 * controller on the socket as unsigned long long. It is
12426 * produced by mbml perf event.
12427 * "perf.cache_misses" - the count of cache misses as unsigned long long.
12428 * It is produced by cache_misses perf event.
12429 * "perf.cache_references" - the count of cache hits as unsigned long long.
12430 * It is produced by cache_references perf event.
12431 * "perf.instructions" - The count of instructions as unsigned long long.
12432 * It is produced by instructions perf event.
12433 * "perf.cpu_cycles" - The count of cpu cycles (total/elapsed) as an
12434 * unsigned long long. It is produced by cpu_cycles
12436 * "perf.branch_instructions" - The count of branch instructions as
12437 * unsigned long long. It is produced by
12438 * branch_instructions perf event.
12439 * "perf.branch_misses" - The count of branch misses as unsigned long
12440 * long. It is produced by branch_misses perf event.
12441 * "perf.bus_cycles" - The count of bus cycles as unsigned long
12442 * long. It is produced by bus_cycles perf event.
12443 * "perf.stalled_cycles_frontend" - The count of stalled cpu cycles in the
12444 * frontend of the instruction processor
12445 * pipeline as unsigned long long. It is
12446 * produced by stalled_cycles_frontend
12448 * "perf.stalled_cycles_backend" - The count of stalled cpu cycles in the
12449 * backend of the instruction processor
12450 * pipeline as unsigned long long. It is
12451 * produced by stalled_cycles_backend
12453 * "perf.ref_cpu_cycles" - The count of total cpu cycles not affected by
12454 * CPU frequency scaling by applications running
12455 * as unsigned long long. It is produced by the
12456 * ref_cpu_cycles perf event.
12457 * "perf.cpu_clock" - The count of cpu clock time as unsigned long long.
12458 * It is produced by the cpu_clock perf event.
12459 * "perf.task_clock" - The count of task clock time as unsigned long long.
12460 * It is produced by the task_clock perf event.
12461 * "perf.page_faults" - The count of page faults as unsigned long long.
12462 * It is produced by the page_faults perf event
12463 * "perf.context_switches" - The count of context switches as unsigned long
12464 * long. It is produced by the context_switches
12466 * "perf.cpu_migrations" - The count of cpu migrations, from one logical
12467 * processor to another, as unsigned long
12468 * long. It is produced by the cpu_migrations
12470 * "perf.page_faults_min" - The count of minor page faults as unsigned
12471 * long long. It is produced by the
12472 * page_faults_min perf event.
12473 * "perf.page_faults_maj" - The count of major page faults as unsigned
12474 * long long. It is produced by the
12475 * page_faults_maj perf event.
12476 * "perf.alignment_faults" - The count of alignment faults as unsigned
12477 * long long. It is produced by the
12478 * alignment_faults perf event
12479 * "perf.emulation_faults" - The count of emulation faults as unsigned
12480 * long long. It is produced by the
12481 * emulation_faults perf event
12483 * VIR_DOMAIN_STATS_IOTHREAD:
12484 * Return IOThread statistics if available. IOThread polling is a
12485 * timing mechanism that allows the hypervisor to generate a longer
12486 * period of time in which the guest will perform operations on the
12487 * CPU being used by the IOThread. The higher the value for poll-max-ns
12488 * the longer the guest will keep the CPU. This may affect other host
12489 * threads using the CPU. The poll-grow and poll-shrink values allow
12490 * the hypervisor to generate a mechanism to add or remove polling time
12491 * within the confines of 0 and poll-max-ns. For QEMU, the poll-grow is
12492 * multiplied by the polling interval, while poll-shrink is used as a
12493 * divisor. When not provided, QEMU may double the polling time until
12494 * poll-max-ns is reached. When poll-shrink is 0 (zero) QEMU may reset
12495 * the polling interval to 0 until it finds its "sweet spot". Setting
12496 * poll-grow too large may cause frequent fluctuation of the time; however,
12497 * this can be tempered by a high poll-shrink to reduce the polling
12498 * interval. For example, a poll-grow of 3 will triple the polling time
12499 * which could quickly exceed poll-max-ns; however, a poll-shrink of
12500 * 10 would cut that polling time more gradually.
12502 * The typed parameter keys are in this format:
12504 * "iothread.count" - maximum number of IOThreads in the subsequent list
12505 * as unsigned int. Each IOThread in the list will
12506 * will use it's iothread_id value as the <id>. There
12507 * may be fewer <id> entries than the iothread.count
12508 * value if the polling values are not supported.
12509 * "iothread.<id>.poll-max-ns" - maximum polling time in ns as an unsigned
12510 * long long. A 0 (zero) means polling is
12512 * "iothread.<id>.poll-grow" - polling time factor as an unsigned int or
12513 * unsigned long long if exceeding range of
12515 * A 0 (zero) indicates to allow the underlying
12516 * hypervisor to choose how to grow the
12518 * "iothread.<id>.poll-shrink" - polling time divisor as an unsigned int or
12519 * unsigned long long if exceeding range of
12521 * A 0 (zero) indicates to allow the underlying
12522 * hypervisor to choose how to shrink the
12525 * VIR_DOMAIN_STATS_MEMORY:
12526 * Return memory bandwidth statistics and the usage information. The typed
12527 * parameter keys are in this format:
12529 * "memory.bandwidth.monitor.count" - the number of memory bandwidth
12530 * monitors for this domain
12531 * "memory.bandwidth.monitor.<num>.name" - the name of monitor <num>
12532 * "memory.bandwidth.monitor.<num>.vcpus" - the vcpu list of monitor <num>
12533 * "memory.bandwidth.monitor.<num>.node.count" - the number of memory
12534 * controller in monitor <num>
12535 * "memory.bandwidth.monitor.<num>.node.<index>.id" - host allocated memory
12536 * controller id for controller
12537 * <index> of monitor <num>
12538 * "memory.bandwidth.monitor.<num>.node.<index>.bytes.local" - the
12539 * accumulative bytes consumed by @vcpus that passing
12540 * through the memory controller in the same processor
12541 * that the scheduled host CPU belongs to.
12542 * "memory.bandwidth.monitor.<num>.node.<index>.bytes.total" - the total
12543 * bytes consumed by @vcpus that passing through all
12544 * memory controllers, either local or remote controller.
12546 * VIR_DOMAIN_STATS_DIRTYRATE:
12547 * Return memory dirty rate information. The typed parameter keys are in
12550 * "dirtyrate.calc_status" - the status of last memory dirty rate calculation,
12551 * returned as int from virDomainDirtyRateStatus
12553 * "dirtyrate.calc_start_time" - the start time of last memory dirty rate
12554 * calculation as long long.
12555 * "dirtyrate.calc_period" - the period of last memory dirty rate calculation
12557 * "dirtyrate.megabytes_per_second" - the calculated memory dirty rate in
12558 * MiB/s as long long. It is produced
12559 * only if the calc_status is measured.
12560 * "dirtyrate.calc_mode" - the calculation mode used last measurement, either
12561 * of these 3 'page-sampling,dirty-bitmap,dirty-ring'
12563 * "dirtyrate.vcpu.<num>.megabytes_per_second" - the calculated memory dirty
12564 * rate for a virtual cpu as
12565 * unsigned long long.
12567 * VIR_DOMAIN_STATS_VM:
12568 * Return hypervisor-specific statistics. Note that the naming and meaning
12569 * of the fields is entirely hypervisor dependent.
12571 * The statistics in this group have the following naming scheme:
12575 * $NAME - name of the statistics field provided by the hypervisor
12577 * $TYPE - Type of the value. The following types are returned:
12578 * 'cur' - current instant value
12579 * 'sum' - aggregate value
12580 * 'max' - peak value
12582 * The returned value may be either an unsigned long long or a boolean.
12585 * The stats reported in this group are runtime-collected and
12586 * hypervisor originated, thus fall outside of the usual stable API
12587 * policies of libvirt.
12589 * Libvirt can't guarantee that the statistics reported from the outside
12590 * source will be present in further versions of the hypervisor, or that
12591 * naming or meaning will stay consistent. Changes to existing fields,
12592 * however, are expected to be rare.
12594 * Note that entire stats groups or individual stat fields may be missing from
12595 * the output in case they are not supported by the given hypervisor, are not
12596 * applicable for the current state of the guest domain, or their retrieval
12597 * was not successful.
12599 * Using 0 for @stats returns all stats groups supported by the given
12602 * Specifying VIR_CONNECT_GET_ALL_DOMAINS_STATS_ENFORCE_STATS as @flags makes
12603 * the function return error in case some of the stat types in @stats were
12604 * not recognized by the daemon. However, even with this flag, a hypervisor
12605 * may omit individual fields within a known group if the information is not
12606 * available; as an extreme example, a supported group may produce zero
12607 * fields for offline domains if the statistics are meaningful only for a
12610 * Passing VIR_CONNECT_GET_ALL_DOMAINS_STATS_NOWAIT in
12611 * @flags means when libvirt is unable to fetch stats for any of
12612 * the domains (for whatever reason) only a subset of statistics
12613 * is returned for the domain. That subset being statistics that
12614 * don't involve querying the underlying hypervisor.
12616 * Similarly to virConnectListAllDomains, @flags can contain various flags to
12617 * filter the list of domains to provide stats for.
12619 * VIR_CONNECT_GET_ALL_DOMAINS_STATS_ACTIVE selects online domains while
12620 * VIR_CONNECT_GET_ALL_DOMAINS_STATS_INACTIVE selects offline ones.
12622 * VIR_CONNECT_GET_ALL_DOMAINS_STATS_PERSISTENT and
12623 * VIR_CONNECT_GET_ALL_DOMAINS_STATS_TRANSIENT allow to filter the list
12624 * according to their persistence.
12626 * To filter the list of VMs by domain state @flags can contain
12627 * VIR_CONNECT_GET_ALL_DOMAINS_STATS_RUNNING,
12628 * VIR_CONNECT_GET_ALL_DOMAINS_STATS_PAUSED,
12629 * VIR_CONNECT_GET_ALL_DOMAINS_STATS_SHUTOFF and/or
12630 * VIR_CONNECT_GET_ALL_DOMAINS_STATS_OTHER for all other states.
12632 * Returns the count of returned statistics structures on success, -1 on error.
12633 * The requested data are returned in the @retStats parameter. The returned
12634 * array should be freed by the caller. See virDomainStatsRecordListFree.
12639 virConnectGetAllDomainStats(virConnectPtr conn
,
12640 unsigned int stats
,
12641 virDomainStatsRecordPtr
**retStats
,
12642 unsigned int flags
)
12646 VIR_DEBUG("conn=%p, stats=0x%x, retStats=%p, flags=0x%x",
12647 conn
, stats
, retStats
, flags
);
12649 virResetLastError();
12651 virCheckConnectReturn(conn
, -1);
12652 virCheckNonNullArgGoto(retStats
, cleanup
);
12654 if (!conn
->driver
->connectGetAllDomainStats
) {
12655 virReportUnsupportedError();
12659 ret
= conn
->driver
->connectGetAllDomainStats(conn
, NULL
, 0, stats
,
12664 virDispatchError(conn
);
12671 * virDomainListGetStats:
12672 * @doms: NULL terminated array of domains
12673 * @stats: stats to return, binary-OR of virDomainStatsTypes
12674 * @retStats: Pointer that will be filled with the array of returned stats
12675 * @flags: extra flags; binary-OR of virConnectGetAllDomainStatsFlags
12677 * Query statistics for domains provided by @doms. Note that all domains in
12678 * @doms must share the same connection.
12680 * Report statistics of various parameters for a running VM according to @stats
12681 * field. The statistics are returned as an array of structures for each queried
12682 * domain. The structure contains an array of typed parameters containing the
12683 * individual statistics. The typed parameter name for each statistic field
12684 * consists of a dot-separated string containing name of the requested group
12685 * followed by a group specific description of the statistic value.
12687 * The statistic groups are enabled using the @stats parameter which is a
12688 * binary-OR of enum virDomainStatsTypes. The stats groups are documented
12689 * in virConnectGetAllDomainStats.
12691 * Using 0 for @stats returns all stats groups supported by the given
12694 * Specifying VIR_CONNECT_GET_ALL_DOMAINS_STATS_ENFORCE_STATS as @flags makes
12695 * the function return error in case some of the stat types in @stats were
12696 * not recognized by the daemon. However, even with this flag, a hypervisor
12697 * may omit individual fields within a known group if the information is not
12698 * available; as an extreme example, a supported group may produce zero
12699 * fields for offline domains if the statistics are meaningful only for a
12702 * Passing VIR_CONNECT_GET_ALL_DOMAINS_STATS_NOWAIT in
12703 * @flags means when libvirt is unable to fetch stats for any of
12704 * the domains (for whatever reason) only a subset of statistics
12705 * is returned for the domain. That subset being statistics that
12706 * don't involve querying the underlying hypervisor.
12708 * Note that any of the domain list filtering flags in @flags may be rejected
12709 * by this function.
12711 * Returns the count of returned statistics structures on success, -1 on error.
12712 * The requested data are returned in the @retStats parameter. The returned
12713 * array should be freed by the caller. See virDomainStatsRecordListFree.
12714 * Note that the count of returned stats may be less than the domain count
12715 * provided via @doms.
12720 virDomainListGetStats(virDomainPtr
*doms
,
12721 unsigned int stats
,
12722 virDomainStatsRecordPtr
**retStats
,
12723 unsigned int flags
)
12725 virConnectPtr conn
= NULL
;
12726 virDomainPtr
*nextdom
= doms
;
12727 unsigned int ndoms
= 0;
12730 VIR_DEBUG("doms=%p, stats=0x%x, retStats=%p, flags=0x%x",
12731 doms
, stats
, retStats
, flags
);
12733 virResetLastError();
12735 virCheckNonNullArgGoto(doms
, cleanup
);
12736 virCheckNonNullArgGoto(retStats
, cleanup
);
12739 virReportError(VIR_ERR_INVALID_ARG
,
12740 _("doms array in %1$s must contain at least one domain"),
12745 conn
= doms
[0]->conn
;
12746 virCheckConnectReturn(conn
, -1);
12748 if (!conn
->driver
->connectGetAllDomainStats
) {
12749 virReportUnsupportedError();
12754 virDomainPtr dom
= *nextdom
;
12756 virCheckDomainGoto(dom
, cleanup
);
12758 if (dom
->conn
!= conn
) {
12759 virReportError(VIR_ERR_INVALID_ARG
, "%s",
12760 _("domains in 'doms' array must belong to a single connection"));
12768 ret
= conn
->driver
->connectGetAllDomainStats(conn
, doms
, ndoms
,
12769 stats
, retStats
, flags
);
12773 virDispatchError(conn
);
12779 * virDomainStatsRecordListFree:
12780 * @stats: NULL terminated array of virDomainStatsRecords to free
12782 * Convenience function to free a list of domain stats returned by
12783 * virDomainListGetStats and virConnectGetAllDomainStats.
12788 virDomainStatsRecordListFree(virDomainStatsRecordPtr
*stats
)
12790 virDomainStatsRecordPtr
*next
;
12795 for (next
= stats
; *next
; next
++) {
12796 virTypedParamsFree((*next
)->params
, (*next
)->nparams
);
12797 virDomainFree((*next
)->dom
);
12806 * virDomainGetFSInfo:
12807 * @dom: a domain object
12808 * @info: a pointer to a variable to store an array of mount points information
12809 * @flags: extra flags; not used yet, so callers should always pass 0
12811 * Get a list of mapping information for each mounted file systems within the
12812 * specified guest and the disks.
12814 * Returns the number of returned mount points, or -1 in case of error.
12815 * On success, the array of the information is stored into @info. The caller is
12816 * responsible for calling virDomainFSInfoFree() on each array element, then
12817 * calling free() on @info. On error, @info is set to NULL.
12822 virDomainGetFSInfo(virDomainPtr dom
,
12823 virDomainFSInfoPtr
**info
,
12824 unsigned int flags
)
12826 VIR_DOMAIN_DEBUG(dom
, "info=%p, flags=0x%x", info
, flags
);
12828 virResetLastError();
12830 virCheckDomainReturn(dom
, -1);
12831 virCheckReadOnlyGoto(dom
->conn
->flags
, error
);
12832 virCheckNonNullArgGoto(info
, error
);
12835 if (dom
->conn
->driver
->domainGetFSInfo
) {
12836 int ret
= dom
->conn
->driver
->domainGetFSInfo(dom
, info
, flags
);
12842 virReportUnsupportedError();
12845 virDispatchError(dom
->conn
);
12851 * virDomainFSInfoFree:
12852 * @info: pointer to a FSInfo object
12854 * Frees all the memory occupied by @info.
12859 virDomainFSInfoFree(virDomainFSInfoPtr info
)
12866 g_free(info
->mountpoint
);
12867 g_free(info
->name
);
12868 g_free(info
->fstype
);
12870 for (i
= 0; i
< info
->ndevAlias
; i
++)
12871 g_free(info
->devAlias
[i
]);
12872 g_free(info
->devAlias
);
12878 * virDomainInterfaceAddresses:
12879 * @dom: domain object
12880 * @ifaces: pointer to an array of pointers pointing to interface objects
12881 * @source: one of the virDomainInterfaceAddressesSource constants
12882 * @flags: currently unused, pass zero
12884 * Return a pointer to the allocated array of pointers to interfaces
12885 * present in given domain along with their IP and MAC addresses. Note that
12886 * single interface can have multiple or even 0 IP addresses.
12888 * This API dynamically allocates the virDomainInterfacePtr struct based on
12889 * how many interfaces domain @dom has, usually there's 1:1 correlation. The
12890 * count of the interfaces is returned as the return value.
12892 * If @source is VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_LEASE, the DHCP lease
12893 * file associated with any virtual networks will be examined to obtain
12894 * the interface addresses. This only returns data for interfaces which
12895 * are connected to virtual networks managed by libvirt.
12897 * If @source is VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_AGENT, a configured
12898 * guest agent is needed for successful return from this API. Moreover, if
12899 * guest agent is used then the interface name is the one seen by guest OS.
12900 * To match such interface with the one from @dom XML use MAC address or IP
12903 * If @source is VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_ARP, the host
12904 * ARP table will be check to obtain the interface addresses. As
12905 * the arp cache refreshes in time, the returned ip address may
12906 * be unreachable. Depending on the route table config of the
12907 * guest, the returned mac address may be duplicated.
12909 * Note that for some @source values some pieces of returned @ifaces
12910 * might be unset (e.g. VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_ARP does not
12911 * set IP address prefix as ARP table does not have any notion of that).
12913 * @ifaces->name and @ifaces->hwaddr are never NULL.
12915 * The caller *must* free @ifaces when no longer needed. Usual use case
12918 * virDomainInterfacePtr *ifaces = NULL;
12919 * int ifaces_count = 0;
12921 * virDomainPtr dom = ... obtain a domain here ...;
12923 * if ((ifaces_count = virDomainInterfaceAddresses(dom, &ifaces,
12924 * VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_LEASE)) < 0)
12927 * ... do something with returned values, for example:
12929 * for (i = 0; i < ifaces_count; i++) {
12930 * printf("name: %s", ifaces[i]->name);
12931 * if (ifaces[i]->hwaddr)
12932 * printf(" hwaddr: %s", ifaces[i]->hwaddr);
12934 * for (j = 0; j < ifaces[i]->naddrs; j++) {
12935 * virDomainIPAddressPtr ip_addr = ifaces[i]->addrs + j;
12936 * printf("[addr: %s prefix: %d type: %d]",
12937 * ip_addr->addr, ip_addr->prefix, ip_addr->type);
12943 * if (ifaces && ifaces_count > 0)
12944 * for (i = 0; i < ifaces_count; i++)
12945 * virDomainInterfaceFree(ifaces[i]);
12948 * Returns the number of interfaces on success, -1 in case of error.
12953 virDomainInterfaceAddresses(virDomainPtr dom
,
12954 virDomainInterfacePtr
**ifaces
,
12955 unsigned int source
,
12956 unsigned int flags
)
12958 VIR_DOMAIN_DEBUG(dom
, "ifaces=%p, source=%d, flags=0x%x", ifaces
, source
, flags
);
12960 virResetLastError();
12964 virCheckDomainReturn(dom
, -1);
12965 virCheckNonNullArgGoto(ifaces
, error
);
12966 if (source
== VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_AGENT
)
12967 virCheckReadOnlyGoto(dom
->conn
->flags
, error
);
12969 if (dom
->conn
->driver
->domainInterfaceAddresses
) {
12971 ret
= dom
->conn
->driver
->domainInterfaceAddresses(dom
, ifaces
, source
, flags
);
12977 virReportError(VIR_ERR_NO_SUPPORT
, __FUNCTION__
);
12980 virDispatchError(dom
->conn
);
12986 * virDomainInterfaceFree:
12987 * @iface: an interface object
12989 * Free the interface object. The data structure is
12990 * freed and should not be used thereafter. If @iface
12991 * is NULL, then this method has no effect.
12996 virDomainInterfaceFree(virDomainInterfacePtr iface
)
13003 g_free(iface
->name
);
13004 g_free(iface
->hwaddr
);
13006 for (i
= 0; i
< iface
->naddrs
; i
++)
13007 g_free(iface
->addrs
[i
].addr
);
13008 g_free(iface
->addrs
);
13015 * virDomainGetGuestVcpus:
13016 * @domain: pointer to domain object
13017 * @params: pointer that will be filled with an array of typed parameters
13018 * @nparams: pointer filled with number of elements in @params
13019 * @flags: currently unused, callers shall pass 0
13021 * Queries the guest agent for state and information regarding vCPUs from
13022 * guest's perspective. The reported data depends on the guest agent
13025 * Reported fields stored in @params:
13026 * 'vcpus': string containing bitmap representing vCPU ids as reported by the
13028 * 'online': string containing bitmap representing online vCPUs as reported
13029 * by the guest agent.
13030 * 'offlinable': string containing bitmap representing ids of vCPUs that can be
13033 * This API requires the VM to run. The caller is responsible for calling
13034 * virTypedParamsFree to free memory returned in @params.
13036 * Returns 0 on success, -1 on error.
13041 virDomainGetGuestVcpus(virDomainPtr domain
,
13042 virTypedParameterPtr
*params
,
13043 unsigned int *nparams
,
13044 unsigned int flags
)
13046 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%p, flags=0x%x",
13047 params
, nparams
, flags
);
13049 virResetLastError();
13051 virCheckDomainReturn(domain
, -1);
13052 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
13054 virCheckNonNullArgGoto(params
, error
);
13055 virCheckNonNullArgGoto(nparams
, error
);
13057 if (domain
->conn
->driver
->domainGetGuestVcpus
) {
13059 ret
= domain
->conn
->driver
->domainGetGuestVcpus(domain
, params
, nparams
,
13066 virReportUnsupportedError();
13069 virDispatchError(domain
->conn
);
13075 * virDomainSetGuestVcpus:
13076 * @domain: pointer to domain object
13077 * @cpumap: text representation of a bitmap of vcpus to set
13078 * @state: 0 to disable/1 to enable cpus described by @cpumap
13079 * @flags: currently unused, callers shall pass 0
13081 * Sets state of individual vcpus described by @cpumap via guest agent. Other
13082 * vcpus are not modified.
13084 * This API requires the VM to run. Various hypervisors or guest agent
13085 * implementation may limit to operate on just 1 vCPU per call.
13087 * @cpumap is a list of vCPU numbers. Its syntax is a comma separated list and
13088 * a special markup using '-' and '^' (ex. '0-4', '0-3,^2'). The '-' denotes
13089 * the range and the '^' denotes exclusive. The expression is sequentially
13090 * evaluated, so "0-15,^8" is identical to "9-14,0-7,15" but not identical to
13093 * Note that OSes (notably Linux) may require vCPU 0 to stay online to support
13094 * low-level features a S3 sleep.
13096 * Returns 0 on success, -1 on error.
13101 virDomainSetGuestVcpus(virDomainPtr domain
,
13102 const char *cpumap
,
13104 unsigned int flags
)
13106 VIR_DOMAIN_DEBUG(domain
, "cpumap='%s' state=%d flags=0x%x",
13107 NULLSTR(cpumap
), state
, flags
);
13109 virResetLastError();
13111 virCheckDomainReturn(domain
, -1);
13112 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
13114 virCheckNonNullArgGoto(cpumap
, error
);
13116 if (domain
->conn
->driver
->domainSetGuestVcpus
) {
13118 ret
= domain
->conn
->driver
->domainSetGuestVcpus(domain
, cpumap
, state
,
13125 virReportUnsupportedError();
13128 virDispatchError(domain
->conn
);
13134 * virDomainSetVcpu:
13135 * @domain: pointer to domain object
13136 * @vcpumap: text representation of a bitmap of vcpus to set
13137 * @state: 0 to disable/1 to enable cpus described by @vcpumap
13138 * @flags: bitwise-OR of virDomainModificationImpact
13140 * Enables/disables individual vcpus described by @vcpumap in the hypervisor.
13142 * Various hypervisor implementations may limit to operate on just 1
13143 * hotpluggable entity (which may contain multiple vCPUs on certain platforms).
13145 * Note that OSes and hypervisors may require vCPU 0 to stay online.
13147 * Returns 0 on success, -1 on error.
13152 virDomainSetVcpu(virDomainPtr domain
,
13153 const char *vcpumap
,
13155 unsigned int flags
)
13157 VIR_DOMAIN_DEBUG(domain
, "vcpumap='%s' state=%i flags=0x%x",
13158 NULLSTR(vcpumap
), state
, flags
);
13160 virResetLastError();
13162 virCheckDomainReturn(domain
, -1);
13163 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
13165 virCheckNonNullArgGoto(vcpumap
, error
);
13167 if (domain
->conn
->driver
->domainSetVcpu
) {
13169 ret
= domain
->conn
->driver
->domainSetVcpu(domain
, vcpumap
, state
, flags
);
13175 virReportUnsupportedError();
13178 virDispatchError(domain
->conn
);
13183 * virDomainGetGuestInfo:
13184 * @domain: pointer to domain object
13185 * @types: types of information to return, binary-OR of virDomainGuestInfoTypes
13186 * @params: location to store the guest info parameters
13187 * @nparams: number of items in @params
13188 * @flags: currently unused, set to 0
13190 * Queries the guest agent for the various information about the guest system.
13191 * The reported data depends on the guest agent implementation. The information
13192 * is returned as an array of typed parameters containing the individual
13193 * parameters. The parameter name for each information field consists of a
13194 * dot-separated string containing the name of the requested group followed by
13195 * a group-specific description of the statistic value.
13197 * The information groups are enabled using the @types parameter which is a
13198 * binary-OR of enum virDomainGuestInfoTypes. The following groups are available
13199 * (although not necessarily implemented for each hypervisor):
13201 * VIR_DOMAIN_GUEST_INFO_USERS:
13202 * returns information about users that are currently logged in within the
13203 * guest domain. The typed parameter keys are in this format:
13205 * "user.count" - the number of active users on this domain as an
13207 * "user.<num>.name" - username of the user as a string
13208 * "user.<num>.domain" - domain of the user as a string (may only be
13209 * present on certain guest types)
13210 * "user.<num>.login-time" - the login time of a user in milliseconds
13211 * since the epoch as unsigned long long
13213 * VIR_DOMAIN_GUEST_INFO_OS:
13214 * Return information about the operating system running within the guest. The
13215 * typed parameter keys are in this format:
13217 * "os.id" - a string identifying the operating system
13218 * "os.name" - the name of the operating system, suitable for presentation
13219 * to a user, as a string
13220 * "os.pretty-name" - a pretty name for the operating system, suitable for
13221 * presentation to a user, as a string
13222 * "os.version" - the version of the operating system suitable for
13223 * presentation to a user, as a string
13224 * "os.version-id" - the version id of the operating system suitable for
13225 * processing by scripts, as a string
13226 * "os.kernel-release" - the release of the operating system kernel, as a
13228 * "os.kernel-version" - the version of the operating system kernel, as a
13230 * "os.machine" - the machine hardware name as a string
13231 * "os.variant" - a specific variant or edition of the operating system
13232 * suitable for presentation to a user, as a string
13233 * "os.variant-id" - the id for a specific variant or edition of the
13234 * operating system, as a string
13236 * VIR_DOMAIN_GUEST_INFO_TIMEZONE:
13237 * Returns information about the timezone within the domain. The typed
13238 * parameter keys are in this format:
13240 * "timezone.name" - the name of the timezone as a string
13241 * "timezone.offset" - the offset to UTC in seconds as an int
13243 * VIR_DOMAIN_GUEST_INFO_FILESYSTEM:
13244 * Returns information about the filesystems within the domain. The typed
13245 * parameter keys are in this format:
13247 * "fs.count" - the number of filesystems defined on this domain
13248 * as an unsigned int
13249 * "fs.<num>.mountpoint" - the path to the mount point for the filesystem
13250 * "fs.<num>.name" - device name in the guest (e.g. "sda1")
13251 * "fs.<num>.fstype" - the type of filesystem
13252 * "fs.<num>.total-bytes" - the total size of the filesystem
13253 * "fs.<num>.used-bytes" - the number of bytes used in the filesystem
13254 * "fs.<num>.disk.count" - the number of disks targeted by this filesystem
13255 * "fs.<num>.disk.<num>.alias" - the device alias of the disk (e.g. sda)
13256 * "fs.<num>.disk.<num>.serial" - the serial number of the disk
13257 * "fs.<num>.disk.<num>.device" - the device node of the disk
13259 * VIR_DOMAIN_GUEST_INFO_DISKS:
13260 * Returns information about the disks within the domain. The typed
13261 * parameter keys are in this format:
13263 * "disk.count" - the number of disks defined on this domain
13264 * as an unsigned int
13265 * "disk.<num>.name" - device node (Linux) or device UNC (Windows)
13266 * "disk.<num>.partition" - whether this is a partition or disk
13267 * "disk.<num>.dependency.count" - the number of device dependencies
13268 * e.g. for LVs of the LVM this will
13269 * hold the list of PVs, for LUKS encrypted volume this will
13270 * contain the disk where the volume is placed. (Linux)
13271 * "disk.<num>.dependency.<num>.name" - a dependency
13272 * "disk.<num>.serial" - optional disk serial number (as string)
13273 * "disk.<num>.alias" - the device alias of the disk (e.g. sda)
13274 * "disk.<num>.guest_alias" - optional alias assigned to the disk, on Linux
13275 * this is a name assigned by device mapper
13277 * VIR_DOMAIN_GUEST_INFO_HOSTNAME:
13278 * Returns information about the hostname of the domain. The typed
13279 * parameter keys are in this format:
13281 * "hostname" - the hostname of the domain
13283 * VIR_DOMAIN_GUEST_INFO_INTERFACES:
13284 * Returns information about the interfaces within the domain. The typed
13285 * parameter keys are in this format:
13287 * "if.count" - the number of interfaces defined on this domain
13288 * "if.<num>.name" - name in the guest (e.g. ``eth0``) for interface <num>
13289 * "if.<num>.hwaddr" - hardware address in the guest for interface <num>
13290 * "if.<num>.addr.count - the number of IP addresses of interface <num>
13291 * "if.<num>.addr.<num1>.type" - the IP address type of addr <num1> (e.g. ipv4)
13292 * "if.<num>.addr.<num1>.addr" - the IP address of addr <num1>
13293 * "if.<num>.addr.<num1>.prefix" - the prefix of IP address of addr <num1>
13295 * Using 0 for @types returns all information groups supported by the given
13298 * This API requires the VM to run. The caller is responsible for calling
13299 * virTypedParamsFree to free memory returned in @params.
13301 * Returns 0 on success, -1 on error.
13305 int virDomainGetGuestInfo(virDomainPtr domain
,
13306 unsigned int types
,
13307 virTypedParameterPtr
*params
,
13309 unsigned int flags
)
13311 VIR_DOMAIN_DEBUG(domain
, "types=0x%x, params=%p, nparams=%p, flags=0x%x",
13312 types
, params
, nparams
, flags
);
13314 virResetLastError();
13316 virCheckDomainReturn(domain
, -1);
13317 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
13319 virCheckNonNullArgGoto(params
, error
);
13320 virCheckNonNullArgGoto(nparams
, error
);
13322 if (domain
->conn
->driver
->domainGetGuestInfo
) {
13324 ret
= domain
->conn
->driver
->domainGetGuestInfo(domain
, types
,
13325 params
, nparams
, flags
);
13332 virReportUnsupportedError();
13335 virDispatchError(domain
->conn
);
13340 * virDomainSetBlockThreshold:
13341 * @domain: pointer to domain object
13342 * @dev: string specifying the block device or backing chain element
13343 * @threshold: threshold in bytes when to fire the event
13344 * @flags: currently unused, callers should pass 0
13346 * Set the threshold level for delivering the
13347 * VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD if the device or backing chain element
13348 * described by @dev is written beyond the set threshold level. The threshold
13349 * level is unset once the event fires. The event might not be delivered at all
13350 * if libvirtd was not running at the moment when the threshold was reached.
13351 * Note that if the threshold level is reached for a top level image, the event
13352 * is emitted for @dev corresponding to the disk target, and may also be reported
13353 * with @dev corresponding to the disk target with an index corresponding to the
13354 * 'index' attribute of 'source' in the live VM XML if the attribute is present.
13356 * @dev can either be a disk target name (vda, sda) or disk target with index (
13357 * vda[4]). Without the index the top image in the backing chain will have the
13358 * threshold set. The index corresponds to the 'index' attribute reported in the
13359 * live VM XML for 'backingStore' or 'source' elements of a disk. If index is
13360 * given the threshold is set for the corresponding image.
13362 * In case when @dev does not contain index the
13363 * VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD event may be emitted twice, once for the
13364 * disk device target without index and once containing the index.
13366 * Note that the threshold event can be registered also for destinations of a
13367 * 'virDomainBlockCopy' destination by using the 'index' of the 'mirror' source.
13369 * Hypervisors report the last written sector of an image in the bulk stats API
13370 * (virConnectGetAllDomainStats/virDomainListGetStats) as
13371 * "block.<num>.allocation" in the VIR_DOMAIN_STATS_BLOCK group. The current
13372 * threshold value is reported as "block.<num>.threshold".
13374 * This event allows to use thin-provisioned storage which needs management
13375 * tools to grow it without the need for polling of the data.
13377 * Returns 0 if the operation has started, -1 on failure.
13382 virDomainSetBlockThreshold(virDomainPtr domain
,
13384 unsigned long long threshold
,
13385 unsigned int flags
)
13387 VIR_DOMAIN_DEBUG(domain
, "dev='%s' threshold=%llu flags=0x%x",
13388 NULLSTR(dev
), threshold
, flags
);
13390 virResetLastError();
13392 virCheckDomainReturn(domain
, -1);
13393 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
13395 virCheckNonNullArgGoto(dev
, error
);
13397 if (domain
->conn
->driver
->domainSetBlockThreshold
) {
13399 ret
= domain
->conn
->driver
->domainSetBlockThreshold(domain
, dev
,
13406 virReportUnsupportedError();
13409 virDispatchError(domain
->conn
);
13415 * virDomainSetLifecycleAction:
13416 * @domain: pointer to domain object
13417 * @type: the lifecycle type from virDomainLifecycle
13418 * @action: the action type from virDomainLifecycleAction
13419 * @flags: bitwise-OR of virDomainModificationImpact
13421 * Changes the actions of lifecycle events for domain represented as
13422 * <on_$type>$action</on_$type> in the domain XML.
13424 * QEMU driver has a limitation that if all lifecycle events are set
13425 * to destroy when the domain is started, it's not possible to change
13426 * any action for running domain.
13428 * Returns 0 on success, -1 on failure.
13432 int virDomainSetLifecycleAction(virDomainPtr domain
,
13434 unsigned int action
,
13435 unsigned int flags
)
13437 VIR_DOMAIN_DEBUG(domain
, "type='%u' action='%u' flags='0x%x'",
13438 type
, action
, flags
);
13440 virResetLastError();
13442 virCheckDomainReturn(domain
, -1);
13443 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
13445 if (type
>= VIR_DOMAIN_LIFECYCLE_LAST
) {
13446 virReportError(VIR_ERR_INVALID_ARG
,
13447 _("invalid lifecycle type '%1$u'"), type
);
13451 if (action
>= VIR_DOMAIN_LIFECYCLE_ACTION_LAST
) {
13452 virReportError(VIR_ERR_INVALID_ARG
,
13453 _("invalid lifecycle action '%1$u'"), action
);
13457 if (domain
->conn
->driver
->domainSetLifecycleAction
) {
13459 ret
= domain
->conn
->driver
->domainSetLifecycleAction(domain
,
13468 virReportUnsupportedError();
13471 virDispatchError(domain
->conn
);
13476 * virDomainGetLaunchSecurityInfo:
13477 * @domain: a domain object
13478 * @params: where to store security info
13479 * @nparams: number of items in @params
13480 * @flags: currently used, set to 0.
13482 * Get the launch security info. In case of the SEV guest, this will
13483 * return the launch measurement.
13485 * Returns -1 in case of failure, 0 in case of success.
13489 int virDomainGetLaunchSecurityInfo(virDomainPtr domain
,
13490 virTypedParameterPtr
*params
,
13492 unsigned int flags
)
13494 virConnectPtr conn
= domain
->conn
;
13497 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%p flags=0x%x",
13498 params
, nparams
, flags
);
13500 virResetLastError();
13502 virCheckDomainReturn(domain
, -1);
13503 virCheckNonNullArgGoto(params
, error
);
13504 virCheckNonNullArgGoto(nparams
, error
);
13505 virCheckReadOnlyGoto(conn
->flags
, error
);
13507 rc
= VIR_DRV_SUPPORTS_FEATURE(domain
->conn
->driver
, domain
->conn
,
13508 VIR_DRV_FEATURE_TYPED_PARAM_STRING
);
13512 flags
|= VIR_TYPED_PARAM_STRING_OKAY
;
13514 if (conn
->driver
->domainGetLaunchSecurityInfo
) {
13516 ret
= conn
->driver
->domainGetLaunchSecurityInfo(domain
, params
,
13522 virReportUnsupportedError();
13525 virDispatchError(domain
->conn
);
13531 * virDomainSetLaunchSecurityState:
13532 * @domain: a domain object
13533 * @params: pointer to launch security parameter objects
13534 * @nparams: number of launch security parameters
13535 * @flags: currently used, set to 0.
13537 * Set a launch security secret in the guest's memory. The guest must be
13538 * in a paused state, e.g. in state VIR_DOMIAN_PAUSED as reported by
13539 * virDomainGetState. On success, the guest can be transitioned to a
13540 * running state. On failure, the guest should be destroyed.
13542 * A basic guest attestation process can be achieved by:
13543 * - Start a secure guest in the paused state by passing VIR_DOMAIN_START_PAUSED
13544 * to one of the virDomainCreate APIs
13545 * - Retrieve the guest launch measurement with virDomainGetLaunchSecurityInfo
13546 * - Verify launch measurement and generate a secret for the guest
13547 * - Set the secret in the guest's memory with virDomainSetLaunchSecurityState
13548 * - Start running the guest with virDomainResume
13550 * See VIR_DOMAIN_LAUNCH_SECURITY_* for a detailed description of accepted
13551 * launch security parameters.
13553 * Returns -1 in case of failure, 0 in case of success.
13557 int virDomainSetLaunchSecurityState(virDomainPtr domain
,
13558 virTypedParameterPtr params
,
13560 unsigned int flags
)
13562 virConnectPtr conn
= domain
->conn
;
13564 VIR_DOMAIN_DEBUG(domain
, "params=%p, nparams=%d flags=0x%x",
13565 params
, nparams
, flags
);
13566 VIR_TYPED_PARAMS_DEBUG(params
, nparams
);
13568 virResetLastError();
13570 virCheckDomainReturn(domain
, -1);
13571 virCheckNonNullArgGoto(params
, error
);
13572 virCheckPositiveArgGoto(nparams
, error
);
13573 virCheckReadOnlyGoto(domain
->conn
->flags
, error
);
13575 if (virTypedParameterValidateSet(conn
, params
, nparams
) < 0)
13578 if (conn
->driver
->domainSetLaunchSecurityState
) {
13580 ret
= conn
->driver
->domainSetLaunchSecurityState(domain
, params
,
13586 virReportUnsupportedError();
13589 virDispatchError(domain
->conn
);
13595 * virDomainAgentSetResponseTimeout:
13596 * @domain: a domain object
13597 * @timeout: timeout in seconds
13598 * @flags: extra flags; not used yet, so callers should always pass 0
13600 * Set how long to wait for a response from guest agent commands. By default,
13601 * agent commands block forever waiting for a response.
13603 * @timeout must be a value from virDomainAgentResponseTimeoutValues or
13606 * VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK(-2): meaning to block forever
13607 * waiting for a result.
13608 * VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_DEFAULT(-1): use default timeout value.
13609 * VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_NOWAIT(0): does not wait.
13610 * positive value: wait for @timeout seconds
13612 * Returns 0 on success, -1 on failure
13617 virDomainAgentSetResponseTimeout(virDomainPtr domain
,
13619 unsigned int flags
)
13621 virConnectPtr conn
;
13623 VIR_DOMAIN_DEBUG(domain
, "timeout=%i, flags=0x%x",
13626 virResetLastError();
13628 virCheckDomainReturn(domain
, -1);
13629 conn
= domain
->conn
;
13631 virCheckReadOnlyGoto(conn
->flags
, error
);
13633 if (conn
->driver
->domainAgentSetResponseTimeout
) {
13634 if (conn
->driver
->domainAgentSetResponseTimeout(domain
, timeout
, flags
) < 0)
13639 virReportUnsupportedError();
13642 virDispatchError(conn
);
13648 * virDomainBackupBegin:
13649 * @domain: a domain object
13650 * @backupXML: description of the requested backup
13651 * @checkpointXML: description of a checkpoint to create or NULL
13652 * @flags: bitwise or of virDomainBackupBeginFlags
13654 * Start a point-in-time backup job for the specified disks of a
13657 * A backup job is a domain job and thus mutually exclusive with any other
13658 * domain job such as migration.
13660 * For now, backup jobs are also mutually exclusive with any
13661 * other block job on the same device, although this restriction may
13662 * be lifted in a future release. Progress of the backup job can be
13663 * tracked via virDomainGetJobStats(). Completion of the job is also announced
13664 * asynchronously via VIR_DOMAIN_EVENT_ID_JOB_COMPLETED event.
13666 * There are two fundamental backup approaches. The first, called a
13667 * push model, instructs the hypervisor to copy the state of the guest
13668 * disk to the designated storage destination (which may be on the
13669 * local file system or a network device). In this mode, the
13670 * hypervisor writes the content of the guest disk to the destination,
13671 * then emits VIR_DOMAIN_EVENT_ID_JOB_COMPLETED when the backup is
13672 * either complete or failed (the backup image is invalid if the job
13673 * fails or virDomainAbortJob() is used prior to the event being
13674 * emitted). This kind of the job finishes automatically. Users can
13675 * determine success by using virDomainGetJobStats() with
13676 * VIR_DOMAIN_JOB_STATS_COMPLETED flag.
13678 * The second, called a pull model, instructs the hypervisor to expose
13679 * the state of the guest disk over an NBD export. A third-party
13680 * client can then connect to this export and read whichever portions
13681 * of the disk it desires. In this mode libvirt has to be informed via
13682 * virDomainAbortJob() when the third-party NBD client is done and the backup
13683 * resources can be released.
13685 * The @backupXML parameter contains details about the backup in the top-level
13686 * element <domainbackup>, including which backup mode to use, whether the
13687 * backup is incremental from a previous checkpoint, which disks
13688 * participate in the backup, the destination for a push model backup,
13689 * and the temporary storage and NBD server details for a pull model
13692 * virDomainBackupGetXMLDesc() can be called to learn actual
13693 * values selected. For more information, see
13694 * https://libvirt.org/formatbackup.html#backup-xml
13696 * The @checkpointXML parameter is optional; if non-NULL, then libvirt
13697 * behaves as if virDomainCheckpointCreateXML() were called to create
13698 * a checkpoint atomically covering the same point in time as the
13701 * The VIR_DOMAIN_BACKUP_BEGIN_REUSE_EXTERNAL specifies that the output or
13702 * temporary files described by the @backupXML document were created by the
13703 * caller with correct format and size to hold the backup or temporary data.
13705 * The creation of a new checkpoint allows for future incremental backups.
13706 * Note that some hypervisors may require a particular disk format, such as
13707 * qcow2, in order to take advantage of checkpoints, while allowing arbitrary
13708 * formats if checkpoints are not involved.
13710 * Returns 0 on success or -1 on failure.
13715 virDomainBackupBegin(virDomainPtr domain
,
13716 const char *backupXML
,
13717 const char *checkpointXML
,
13718 unsigned int flags
)
13720 virConnectPtr conn
;
13722 VIR_DOMAIN_DEBUG(domain
, "backupXML=%s, checkpointXML=%s, flags=0x%x",
13723 NULLSTR(backupXML
), NULLSTR(checkpointXML
), flags
);
13725 virResetLastError();
13727 virCheckDomainReturn(domain
, -1);
13728 conn
= domain
->conn
;
13730 virCheckNonNullArgGoto(backupXML
, error
);
13731 virCheckReadOnlyGoto(conn
->flags
, error
);
13733 if (conn
->driver
->domainBackupBegin
) {
13735 ret
= conn
->driver
->domainBackupBegin(domain
, backupXML
, checkpointXML
,
13742 virReportUnsupportedError();
13744 virDispatchError(conn
);
13750 * virDomainBackupGetXMLDesc:
13751 * @domain: a domain object
13752 * @flags: extra flags; not used yet, so callers should always pass 0
13754 * Queries the configuration of the active backup job.
13756 * In some cases, a user can start a backup job without supplying all
13757 * details and rely on libvirt to fill in the rest (for example,
13758 * selecting the port used for an NBD export). This API can then be
13759 * used to learn what default values were chosen.
13761 * Returns a NUL-terminated UTF-8 encoded XML instance or NULL in
13762 * case of error. The caller must free() the returned value.
13767 virDomainBackupGetXMLDesc(virDomainPtr domain
,
13768 unsigned int flags
)
13770 virConnectPtr conn
;
13772 VIR_DOMAIN_DEBUG(domain
, "flags=0x%x", flags
);
13774 virResetLastError();
13776 virCheckDomainReturn(domain
, NULL
);
13777 conn
= domain
->conn
;
13779 if (conn
->driver
->domainBackupGetXMLDesc
) {
13781 ret
= conn
->driver
->domainBackupGetXMLDesc(domain
, flags
);
13787 virReportUnsupportedError();
13789 virDispatchError(conn
);
13795 * virDomainAuthorizedSSHKeysGet:
13796 * @domain: a domain object
13797 * @user: user to list keys for
13798 * @keys: pointer to a variable to store authorized keys
13799 * @flags: extra flags; not used yet, so callers should always pass 0
13801 * For given @user in @domain fetch list of public SSH authorized
13802 * keys and store them into @keys array which is allocated upon
13803 * successful return and is NULL terminated. The caller is
13804 * responsible for freeing @keys when no longer needed.
13806 * Keys are in OpenSSH format (see sshd(8)) but from libvirt's
13807 * point of view are opaque strings, i.e. not interpreted.
13809 * Please note that some hypervisors may require guest agent to
13810 * be configured and running in order to be able to run this API.
13812 * Returns: number of keys stored in @keys,
13818 virDomainAuthorizedSSHKeysGet(virDomainPtr domain
,
13821 unsigned int flags
)
13823 virConnectPtr conn
;
13825 VIR_DOMAIN_DEBUG(domain
, "user=%s, keys=%p, flags=0x%x",
13826 user
, keys
, flags
);
13828 virResetLastError();
13830 virCheckDomainReturn(domain
, -1);
13831 conn
= domain
->conn
;
13832 virCheckNonNullArgGoto(user
, error
);
13833 virCheckNonNullArgGoto(keys
, error
);
13835 virCheckReadOnlyGoto(conn
->flags
, error
);
13837 if (conn
->driver
->domainAuthorizedSSHKeysGet
) {
13839 ret
= conn
->driver
->domainAuthorizedSSHKeysGet(domain
, user
,
13846 virReportUnsupportedError();
13848 virDispatchError(conn
);
13854 * virDomainAuthorizedSSHKeysSet:
13855 * @domain: a domain object
13856 * @user: user to add keys for
13857 * @keys: authorized keys to set
13858 * @nkeys: number of keys in @keys array
13859 * @flags: bitwise or of virDomainAuthorizedSSHKeysSetFlags
13861 * For given @user in @domain set @keys in authorized keys file.
13862 * Any previous content of the file is overwritten with new keys.
13863 * That is, if this API is called with @nkeys = 0, @keys = NULL
13864 * and @flags = 0 then the authorized keys file for @user is
13867 * Keys are in OpenSSH format (see sshd(8)) but from libvirt's
13868 * point of view are opaque strings, i.e. not interpreted.
13870 * If VIR_DOMAIN_AUTHORIZED_SSH_KEYS_SET_APPEND flag is set
13871 * then the file is not overwritten and new @keys are appended
13874 * If VIR_DOMAIN_AUTHORIZED_SSH_KEYS_SET_REMOVE flag is set then
13875 * instead of adding any new keys, provided @keys are removed
13876 * from the file. It's not considered error if the key doesn't
13879 * Please note that some hypervisors may require guest agent to
13880 * be configured and running in order to be able to run this API.
13882 * Returns: 0 on success,
13888 virDomainAuthorizedSSHKeysSet(virDomainPtr domain
,
13891 unsigned int nkeys
,
13892 unsigned int flags
)
13894 virConnectPtr conn
;
13896 VIR_DOMAIN_DEBUG(domain
, "user=%s, keys=%p, nkeys=%u, flags=0x%x",
13897 user
, keys
, nkeys
, flags
);
13899 virResetLastError();
13901 virCheckDomainReturn(domain
, -1);
13902 conn
= domain
->conn
;
13903 virCheckNonNullArgGoto(user
, error
);
13905 if (flags
& VIR_DOMAIN_AUTHORIZED_SSH_KEYS_SET_APPEND
||
13906 flags
& VIR_DOMAIN_AUTHORIZED_SSH_KEYS_SET_REMOVE
)
13907 virCheckNonNullArgGoto(keys
, error
);
13909 VIR_EXCLUSIVE_FLAGS_RET(VIR_DOMAIN_AUTHORIZED_SSH_KEYS_SET_APPEND
,
13910 VIR_DOMAIN_AUTHORIZED_SSH_KEYS_SET_REMOVE
,
13913 virCheckReadOnlyGoto(conn
->flags
, error
);
13915 if (conn
->driver
->domainAuthorizedSSHKeysSet
) {
13917 ret
= conn
->driver
->domainAuthorizedSSHKeysSet(domain
, user
,
13918 keys
, nkeys
, flags
);
13924 virReportUnsupportedError();
13926 virDispatchError(conn
);
13932 * virDomainGetMessages:
13933 * @domain: a domain object
13934 * @msgs: pointer to a variable to store messages
13935 * @flags: zero or more virDomainMessageType flags
13937 * Fetch a list of all messages recorded against the VM and
13938 * store them into @msgs array which is allocated upon
13939 * successful return and is NULL terminated. The caller is
13940 * responsible for freeing @msgs when no longer needed.
13942 * If @flags is zero then all messages are reported. The
13943 * virDomainMessageType constants can be used to restrict
13944 * results to certain types of message.
13946 * Note it is hypervisor dependent whether messages are
13947 * available for shutoff guests, or running guests, or
13948 * both. Thus a client should be prepared to re-fetch
13949 * messages when a guest transitions between running
13950 * and shutoff states.
13952 * Returns: number of messages stored in @msgs,
13958 virDomainGetMessages(virDomainPtr domain
,
13960 unsigned int flags
)
13962 virConnectPtr conn
;
13964 VIR_DOMAIN_DEBUG(domain
, "msgs=%p, flags=0x%x", msgs
, flags
);
13966 virResetLastError();
13968 virCheckDomainReturn(domain
, -1);
13969 conn
= domain
->conn
;
13970 virCheckNonNullArgGoto(msgs
, error
);
13972 if (conn
->driver
->domainGetMessages
) {
13974 ret
= conn
->driver
->domainGetMessages(domain
, msgs
, flags
);
13980 virReportUnsupportedError();
13982 virDispatchError(conn
);
13988 * virDomainStartDirtyRateCalc:
13989 * @domain: a domain object
13990 * @seconds: specified calculating time in seconds
13991 * @flags: bitwise-OR of supported virDomainDirtyRateCalcFlags
13993 * Calculate the current domain's memory dirty rate in next @seconds.
13994 * The calculated dirty rate information is available by calling
13995 * virConnectGetAllDomainStats.
13997 * Returns 0 in case of success, -1 otherwise.
14002 virDomainStartDirtyRateCalc(virDomainPtr domain
,
14004 unsigned int flags
)
14006 virConnectPtr conn
;
14008 VIR_DOMAIN_DEBUG(domain
, "seconds=%d, flags=0x%x", seconds
, flags
);
14010 virResetLastError();
14012 virCheckDomainReturn(domain
, -1);
14013 conn
= domain
->conn
;
14015 virCheckReadOnlyGoto(conn
->flags
, error
);
14017 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_DIRTYRATE_MODE_PAGE_SAMPLING
,
14018 VIR_DOMAIN_DIRTYRATE_MODE_DIRTY_BITMAP
,
14020 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_DIRTYRATE_MODE_PAGE_SAMPLING
,
14021 VIR_DOMAIN_DIRTYRATE_MODE_DIRTY_RING
,
14023 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_DIRTYRATE_MODE_DIRTY_BITMAP
,
14024 VIR_DOMAIN_DIRTYRATE_MODE_DIRTY_RING
,
14027 if (conn
->driver
->domainStartDirtyRateCalc
) {
14029 ret
= conn
->driver
->domainStartDirtyRateCalc(domain
, seconds
, flags
);
14035 virReportUnsupportedError();
14038 virDispatchError(conn
);
14044 * virDomainFDAssociate:
14045 * @domain: a domain object
14046 * @name: name for the file descriptor group
14047 * @nfds: number of fds in @fds
14048 * @fds: file descriptors to associate with domain
14049 * @flags: optional flags; bitwise-OR of supported virDomainFDAssociateFlags
14051 * Associate the FDs in @fd with @domain under @name. The FDs are associated as
14052 * long as the connection used to associated exists and are disposed of
14053 * afterwards. FD may still be kept open by the hypervisor for as long as it's
14056 * Security labelling (e.g. via the selinux) may be applied on the passed FDs
14057 * when required for usage by the VM. By default libvirt does not restore the
14058 * seclabels on the FDs afterwards to avoid keeping it open unnecessarily.
14060 * Restoring of the security label can be requested by passing either
14061 * VIR_DOMAIN_FD_ASSOCIATE_SECLABEL_RESTORE for a best-effort attempt to restore
14062 * the security label after use.
14063 * Requesting the restore of security label will require that the file
14064 * descriptors are kept open for the whole time they are used by the hypervisor,
14065 * or other additional overhead.
14067 * In certain cases usage of the fd group would imply read-only access. Passing
14068 * VIR_DOMAIN_FD_ASSOCIATE_SECLABEL_WRITABLE in @flags ensures that a writable
14069 * security label is picked in case when the file represented by the fds may
14070 * be used in write mode.
14072 * Returns 0 on success, -1 on error.
14077 virDomainFDAssociate(virDomainPtr domain
,
14081 unsigned int flags
)
14083 virConnectPtr conn
;
14086 VIR_DOMAIN_DEBUG(domain
,
14087 "name='%s', nfds=%u, fds=%p, flags=0x%x",
14088 name
, nfds
, fds
, flags
);
14090 virResetLastError();
14092 conn
= domain
->conn
;
14094 if ((rc
= VIR_DRV_SUPPORTS_FEATURE(conn
->driver
, conn
, VIR_DRV_FEATURE_FD_PASSING
)) < 0)
14098 virReportError(VIR_ERR_ARGUMENT_UNSUPPORTED
, "%s",
14099 _("fd passing is not supported by this connection"));
14103 virCheckNonZeroArgGoto(nfds
, error
);
14104 virCheckNonNullArgGoto(fds
, error
);
14105 virCheckReadOnlyGoto(conn
->flags
, error
);
14107 if (!conn
->driver
->domainFDAssociate
) {
14108 virReportUnsupportedError();
14112 if ((rc
= conn
->driver
->domainFDAssociate(domain
, name
, nfds
, fds
, flags
)) < 0)
14118 virDispatchError(conn
);
14124 * virDomainGraphicsReload:
14125 * @domain: a domain object
14126 * @type: graphics type; from the virDomainGraphicsReloadType enum
14127 * @flags: extra flags; not used yet, so callers should always pass 0
14129 * Reload domain's graphics. This can be used to reload TLS certificates
14130 * without restarting the domain.
14132 * Returns 0 in case of success, -1 otherwise.
14137 virDomainGraphicsReload(virDomainPtr domain
,
14139 unsigned int flags
)
14141 virConnectPtr conn
;
14143 VIR_DOMAIN_DEBUG(domain
, "type=%u, flags=0x%x", type
, flags
);
14145 virResetLastError();
14147 virCheckDomainReturn(domain
, -1);
14148 conn
= domain
->conn
;
14149 virCheckReadOnlyGoto(conn
->flags
, error
);
14151 if (conn
->driver
->domainGraphicsReload
) {
14153 ret
= conn
->driver
->domainGraphicsReload(domain
, type
, flags
);
14159 virReportUnsupportedError();
14162 virDispatchError(domain
->conn
);