2489
* virDomainPMSuspendForDuration:
2490
* @dom: a domain object
2491
* @target: a value from virNodeSuspendTarget
2492
* @duration: duration in seconds to suspend, or 0 for indefinite
2493
* @flags: extra flags; not used yet, so callers should always pass 0
2495
* Attempt to have the guest enter the given @target power management
2496
* suspension level. If @duration is non-zero, also schedule the guest to
2497
* resume normal operation after that many seconds, if nothing else has
2498
* resumed it earlier. Some hypervisors require that @duration be 0, for
2499
* an indefinite suspension.
2501
* Dependent on hypervisor used, this may require a
2502
* guest agent to be available, e.g. QEMU.
2504
* Returns: 0 on success,
2508
virDomainPMSuspendForDuration(virDomainPtr dom,
2509
unsigned int target,
2510
unsigned long long duration,
2515
VIR_DOMAIN_DEBUG(dom, "target=%u duration=%llu flags=%x",
2516
target, duration, flags);
2518
virResetLastError();
2520
if (!VIR_IS_CONNECTED_DOMAIN(dom)) {
2521
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2522
virDispatchError(NULL);
2528
if (conn->flags & VIR_CONNECT_RO) {
2529
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
2533
if (conn->driver->domainPMSuspendForDuration) {
2535
ret = conn->driver->domainPMSuspendForDuration(dom, target,
2542
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2545
virDispatchError(conn);
2550
* virDomainPMWakeup:
2551
* @dom: a domain object
2552
* @flags: extra flags; not used yet, so callers should always pass 0
2554
* Inject a wakeup into the guest that previously used
2555
* virDomainPMSuspendForDuration, rather than waiting for the
2556
* previously requested duration (if any) to elapse.
2558
* Returns: 0 on success,
2562
virDomainPMWakeup(virDomainPtr dom,
2567
VIR_DOMAIN_DEBUG(dom, "flags=%x", flags);
2569
virResetLastError();
2571
if (!VIR_IS_CONNECTED_DOMAIN(dom)) {
2572
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2573
virDispatchError(NULL);
2579
if (conn->flags & VIR_CONNECT_RO) {
2580
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
2584
if (conn->driver->domainPMWakeup) {
2586
ret = conn->driver->domainPMWakeup(dom, flags);
2592
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2595
virDispatchError(conn);
2436
2600
* virDomainSave:
2437
2601
* @domain: a domain object
2438
2602
* @to: path for the output file
3277
* virDomainShutdownFlags:
3278
* @domain: a domain object
3279
* @flags: bitwise-OR of virDomainShutdownFlagValues
3281
* Shutdown a domain, the domain object is still usable thereafter but
3282
* the domain OS is being stopped. Note that the guest OS may ignore the
3283
* request. For guests that react to a shutdown request, the differences
3284
* from virDomainDestroy() are that the guest's disk storage will be in a
3285
* stable state rather than having the (virtual) power cord pulled, and
3286
* this command returns as soon as the shutdown request is issued rather
3287
* than blocking until the guest is no longer running.
3289
* If the domain is transient and has any snapshot metadata (see
3290
* virDomainSnapshotNum()), then that metadata will automatically
3291
* be deleted when the domain quits.
3293
* If @flags is set to zero, then the hypervisor will choose the
3294
* method of shutdown it considers best. To have greater control
3295
* pass exactly one of the virDomainShutdownFlagValues.
3297
* Returns 0 in case of success and -1 in case of failure.
3300
virDomainShutdownFlags(virDomainPtr domain, unsigned int flags)
3304
VIR_DOMAIN_DEBUG(domain);
3306
virResetLastError();
3308
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
3309
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
3310
virDispatchError(NULL);
3313
if (domain->conn->flags & VIR_CONNECT_RO) {
3314
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
3318
/* At most one of these two flags should be set. */
3319
if ((flags & VIR_DOMAIN_SHUTDOWN_ACPI_POWER_BTN) &&
3320
(flags & VIR_DOMAIN_SHUTDOWN_GUEST_AGENT)) {
3321
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
3325
conn = domain->conn;
3327
if (conn->driver->domainShutdownFlags) {
3329
ret = conn->driver->domainShutdownFlags(domain, flags);
3335
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3338
virDispatchError(domain->conn);
3109
3343
* virDomainReboot:
3110
3344
* @domain: a domain object
3111
* @flags: extra flags for the reboot operation, not used yet
3345
* @flags: bitwise-OR of virDomainRebootFlagValues
3113
3347
* Reboot a domain, the domain object is still usable there after but
3114
3348
* the domain OS is being stopped for a restart.
3115
3349
* Note that the guest OS may ignore the request.
3351
* If @flags is set to zero, then the hypervisor will choose the
3352
* method of shutdown it considers best. To have greater control
3353
* pass exactly one of the virDomainRebootFlagValues.
3355
* To use guest agent (VIR_DOMAIN_REBOOT_GUEST_AGENT) the domain XML
3356
* must have <channel> configured.
3117
3358
* Returns 0 in case of success and -1 in case of failure.
4026
* virDomainSetNumaParameters:
4027
* @domain: pointer to domain object
4028
* @params: pointer to numa parameter objects
4029
* @nparams: number of numa parameters (this value can be the same or
4030
* less than the number of parameters supported)
4031
* @flags: bitwise-OR of virDomainModificationImpact
4033
* Change all or a subset of the numa tunables.
4034
* This function may require privileged access to the hypervisor.
4036
* Returns -1 in case of error, 0 in case of success.
4039
virDomainSetNumaParameters(virDomainPtr domain,
4040
virTypedParameterPtr params,
4041
int nparams, unsigned int flags)
4045
VIR_DOMAIN_DEBUG(domain, "params=%p, nparams=%d, flags=%x",
4046
params, nparams, flags);
4048
virResetLastError();
4050
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
4051
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
4052
virDispatchError(NULL);
4055
if (domain->conn->flags & VIR_CONNECT_RO) {
4056
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
4059
if ((nparams <= 0) || (params == NULL)) {
4060
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
4063
if (virTypedParameterValidateSet(domain, params, nparams) < 0)
4066
conn = domain->conn;
4068
if (conn->driver->domainSetNumaParameters) {
4070
ret = conn->driver->domainSetNumaParameters(domain, params, nparams,
4077
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4080
virDispatchError(domain->conn);
4085
* virDomainGetNumaParameters:
4086
* @domain: pointer to domain object
4087
* @params: pointer to numa parameter object
4088
* (return value, allocated by the caller)
4089
* @nparams: pointer to number of numa parameters
4090
* @flags: bitwise-OR of virDomainModificationImpact and virTypedParameterFlags
4092
* Get all numa parameters. On input, @nparams gives the size of the
4093
* @params array; on output, @nparams gives how many slots were filled
4094
* with parameter information, which might be less but will not exceed
4097
* As a special case, calling with @params as NULL and @nparams as 0 on
4098
* input will cause @nparams on output to contain the number of parameters
4099
* supported by the hypervisor. The caller should then allocate @params
4100
* array, i.e. (sizeof(@virTypedParameter) * @nparams) bytes and call the API
4103
* See virDomainGetMemoryParameters() for an equivalent usage example.
4105
* This function may require privileged access to the hypervisor. This function
4106
* expects the caller to allocate the @params.
4108
* Returns -1 in case of error, 0 in case of success.
4112
virDomainGetNumaParameters(virDomainPtr domain,
4113
virTypedParameterPtr params,
4114
int *nparams, unsigned int flags)
4118
VIR_DOMAIN_DEBUG(domain, "params=%p, nparams=%d, flags=%x",
4119
params, (nparams) ? *nparams : -1, flags);
4121
virResetLastError();
4123
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
4124
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
4125
virDispatchError(NULL);
4128
if ((nparams == NULL) || (*nparams < 0) ||
4129
(params == NULL && *nparams != 0)) {
4130
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
4133
if (VIR_DRV_SUPPORTS_FEATURE(domain->conn->driver, domain->conn,
4134
VIR_DRV_FEATURE_TYPED_PARAM_STRING))
4135
flags |= VIR_TYPED_PARAM_STRING_OKAY;
4137
conn = domain->conn;
4139
if (conn->driver->domainGetNumaParameters) {
4141
ret = conn->driver->domainGetNumaParameters(domain, params, nparams,
4147
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4150
virDispatchError(domain->conn);
3772
4155
* virDomainSetBlkioParameters:
3773
4156
* @domain: pointer to domain object
3774
4157
* @params: pointer to blkio parameter objects
7334
* virDomainSetInterfaceParameters:
7335
* @domain: pointer to domain object
7336
* @device: the interface name or mac address
7337
* @params: pointer to interface parameter objects
7338
* @nparams: number of interface parameter (this value can be the same or
7339
* less than the number of parameters supported)
7340
* @flags: bitwise-OR of virDomainModificationImpact
7342
* Change a subset or all parameters of interface; currently this
7343
* includes bandwidth parameters. The value of @flags should be
7344
* either VIR_DOMAIN_AFFECT_CURRENT, or a bitwise-or of values
7345
* VIR_DOMAIN_AFFECT_LIVE and VIR_DOMAIN_AFFECT_CONFIG, although
7346
* hypervisors vary in which flags are supported.
7348
* This function may require privileged access to the hypervisor.
7350
* Returns -1 in case of error, 0 in case of success.
7353
virDomainSetInterfaceParameters(virDomainPtr domain,
7355
virTypedParameterPtr params,
7356
int nparams, unsigned int flags)
7360
VIR_DOMAIN_DEBUG(domain, "device=%s, params=%p, nparams=%d, flags=%x",
7361
device, params, nparams, flags);
7363
virResetLastError();
7365
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
7366
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
7367
virDispatchError(NULL);
7370
if (domain->conn->flags & VIR_CONNECT_RO) {
7371
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
7374
if ((nparams <= 0) || (params == NULL)) {
7375
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
7378
if (virTypedParameterValidateSet(domain, params, nparams) < 0)
7381
conn = domain->conn;
7383
if (conn->driver->domainSetInterfaceParameters) {
7385
ret = conn->driver->domainSetInterfaceParameters(domain, device,
7393
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7396
virDispatchError(domain->conn);
7401
* virDomainGetInterfaceParameters:
7402
* @domain: pointer to domain object
7403
* @device: the interface name or mac address
7404
* @params: pointer to interface parameter objects
7405
* (return value, allocated by the caller)
7406
* @nparams: pointer to number of interface parameter; input and output
7407
* @flags: bitwise-OR of virDomainModificationImpact and virTypedParameterFlags
7409
* Get all interface parameters. On input, @nparams gives the size of
7410
* the @params array; on output, @nparams gives how many slots were
7411
* filled with parameter information, which might be less but will not
7412
* exceed the input value.
7414
* As a special case, calling with @params as NULL and @nparams as 0 on
7415
* input will cause @nparams on output to contain the number of parameters
7416
* supported by the hypervisor. The caller should then allocate @params
7417
* array, i.e. (sizeof(@virTypedParameter) * @nparams) bytes and call the
7418
* API again. See virDomainGetMemoryParameters() for an equivalent usage
7421
* This function may require privileged access to the hypervisor. This function
7422
* expects the caller to allocate the @params.
7424
* Returns -1 in case of error, 0 in case of success.
7428
virDomainGetInterfaceParameters(virDomainPtr domain,
7430
virTypedParameterPtr params,
7431
int *nparams, unsigned int flags)
7435
VIR_DOMAIN_DEBUG(domain, "device=%s, params=%p, nparams=%d, flags=%x",
7436
device, params, (nparams) ? *nparams : -1, flags);
7438
virResetLastError();
7440
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
7441
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
7442
virDispatchError(NULL);
7445
if ((nparams == NULL) || (*nparams < 0) ||
7446
(params == NULL && *nparams != 0)) {
7447
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
7450
if (VIR_DRV_SUPPORTS_FEATURE(domain->conn->driver, domain->conn,
7451
VIR_DRV_FEATURE_TYPED_PARAM_STRING))
7452
flags |= VIR_TYPED_PARAM_STRING_OKAY;
7454
conn = domain->conn;
7456
if (conn->driver->domainGetInterfaceParameters) {
7458
ret = conn->driver->domainGetInterfaceParameters(domain, device,
7465
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7468
virDispatchError(domain->conn);
6950
7473
* virDomainMemoryStats:
6951
7474
* @dom: pointer to the domain object
6952
7475
* @stats: nr_stats-sized array of stat structures (returned)
6953
7476
* @nr_stats: number of memory statistics requested
6954
* @flags: unused, always pass 0
7477
* @flags: extra flags; not used yet, so callers should always pass 0
6956
7479
* This function provides memory statistics for the domain.
9027
* virDomainSetMetadata:
9028
* @domain: a domain object
9029
* @type: type of description, from virDomainMetadataType
9030
* @metadata: new metadata text
9031
* @key: XML namespace key, or NULL
9032
* @uri: XML namespace URI, or NULL
9033
* @flags: bitwise-OR of virDomainModificationImpact
9035
* Sets the appropriate domain element given by @type to the
9036
* value of @description. A @type of VIR_DOMAIN_METADATA_DESCRIPTION
9037
* is free-form text; VIR_DOMAIN_METADATA_TITLE is free-form, but no
9038
* newlines are permitted, and should be short (although the length is
9039
* not enforced). For these two options @key and @uri are irrelevant and
9040
* must be set to NULL.
9042
* For type VIR_DOMAIN_METADATA_ELEMENT @metadata must be well-formed
9043
* XML belonging to namespace defined by @uri with local name @key.
9045
* Passing NULL for @metadata says to remove that element from the
9046
* domain XML (passing the empty string leaves the element present).
9048
* The resulting metadata will be present in virDomainGetXMLDesc(),
9049
* as well as quick access through virDomainGetMetadata().
9051
* @flags controls whether the live domain, persistent configuration,
9052
* or both will be modified.
9054
* Returns 0 on success, -1 in case of failure.
9057
virDomainSetMetadata(virDomainPtr domain,
9059
const char *metadata,
9066
VIR_DOMAIN_DEBUG(domain,
9067
"type=%d, metadata='%s', key='%s', uri='%s', flags=%x",
9068
type, NULLSTR(metadata), NULLSTR(key), NULLSTR(uri),
9071
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
9072
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
9076
conn = domain->conn;
9078
if (conn->flags & VIR_CONNECT_RO) {
9079
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
9084
case VIR_DOMAIN_METADATA_TITLE:
9085
if (metadata && strchr(metadata, '\n')) {
9086
virLibDomainError(VIR_ERR_INVALID_ARG, "%s",
9087
_("Domain title can't contain newlines"));
9091
case VIR_DOMAIN_METADATA_DESCRIPTION:
9093
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
9097
case VIR_DOMAIN_METADATA_ELEMENT:
9099
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
9104
/* For future expansion */
9108
if (conn->driver->domainSetMetadata) {
9110
ret = conn->driver->domainSetMetadata(domain, type, metadata, key, uri,
9117
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9120
virDispatchError(domain->conn);
9125
* virDomainGetMetadata:
9126
* @domain: a domain object
9127
* @type: type of description, from virDomainMetadataType
9128
* @uri: XML namespace identifier
9129
* @flags: bitwise-OR of virDomainModificationImpact
9131
* Retrieves the appropriate domain element given by @type.
9132
* If VIR_DOMAIN_METADATA_ELEMENT is requested parameter @uri
9133
* must be set to the name of the namespace the requested elements
9134
* belong to, otherwise must be NULL.
9136
* If an element of the domain XML is not present, the resulting
9137
* error will be VIR_ERR_NO_DOMAIN_METADATA. This method forms
9138
* a shortcut for seeing information from virDomainSetMetadata()
9139
* without having to go through virDomainGetXMLDesc().
9141
* @flags controls whether the live domain or persistent
9142
* configuration will be queried.
9144
* Returns the metadata string on success (caller must free),
9145
* or NULL in case of failure.
9148
virDomainGetMetadata(virDomainPtr domain,
9155
VIR_DOMAIN_DEBUG(domain, "type=%d, uri='%s', flags=%x",
9156
type, NULLSTR(uri), flags);
9158
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
9159
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
9163
if ((flags & VIR_DOMAIN_AFFECT_LIVE) &&
9164
(flags & VIR_DOMAIN_AFFECT_CONFIG)) {
9165
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
9170
case VIR_DOMAIN_METADATA_TITLE:
9171
case VIR_DOMAIN_METADATA_DESCRIPTION:
9173
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
9177
case VIR_DOMAIN_METADATA_ELEMENT:
9179
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
9184
/* For future expansion */
9188
conn = domain->conn;
9190
if (conn->driver->domainGetMetadata) {
9192
if (!(ret = conn->driver->domainGetMetadata(domain, type, uri, flags)))
9197
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9200
virDispatchError(domain->conn);
8482
9205
* virNodeGetSecurityModel:
8483
9206
* @conn: a connection object
8484
9207
* @secmodel: pointer to a virSecurityModel structure
13311
* virStorageVolResize:
13312
* @vol: pointer to storage volume
13313
* @capacity: new capacity, in bytes
13314
* @flags: bitwise-OR of virStorageVolResizeFlags
13316
* Changes the capacity of the storage volume @vol to @capacity. The
13317
* operation will fail if the new capacity requires allocation that would
13318
* exceed the remaining free space in the parent pool. The contents of
13319
* the new capacity will appear as all zero bytes.
13321
* Normally, the operation will attempt to affect capacity with a minimum
13322
* impact on allocation (that is, the default operation favors a sparse
13323
* resize). If @flags contains VIR_STORAGE_VOL_RESIZE_ALLOCATE, then the
13324
* operation will ensure that allocation is sufficient for the new
13325
* capacity; this may make the operation take noticeably longer.
13327
* Normally, the operation treats @capacity as the new size in bytes;
13328
* but if @flags contains VIR_STORAGE_VOL_RESIZE_DELTA, then @capacity
13329
* represents the size difference to add to the current size. It is
13330
* up to the storage pool implementation whether unaligned requests are
13331
* rounded up to the next valid boundary, or rejected.
13333
* Normally, this operation should only be used to enlarge capacity;
13334
* but if @flags contains VIR_STORAGE_VOL_RESIZE_SHRINK, it is possible to
13335
* attempt a reduction in capacity even though it might cause data loss.
13336
* If VIR_STORAGE_VOL_RESIZE_DELTA is also present, then @capacity is
13337
* subtracted from the current size; without it, @capacity represents
13338
* the absolute new size regardless of whether it is larger or smaller
13339
* than the current size.
13341
* Returns 0 on success, or -1 on error.
13344
virStorageVolResize(virStorageVolPtr vol,
13345
unsigned long long capacity,
13346
unsigned int flags)
13348
virConnectPtr conn;
13349
VIR_DEBUG("vol=%p capacity=%llu flags=%x", vol, capacity, flags);
13351
virResetLastError();
13353
if (!VIR_IS_STORAGE_VOL(vol)) {
13354
virLibStorageVolError(VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
13355
virDispatchError(NULL);
13361
if (conn->flags & VIR_CONNECT_RO) {
13362
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
13366
/* Zero capacity is only valid with either delta or shrink. */
13367
if (capacity == 0 && !((flags & VIR_STORAGE_VOL_RESIZE_DELTA) ||
13368
(flags & VIR_STORAGE_VOL_RESIZE_SHRINK))) {
13369
virLibStorageVolError(VIR_ERR_INVALID_ARG, __FUNCTION__);
13373
if (conn->storageDriver && conn->storageDriver->volResize) {
13375
ret = conn->storageDriver->volResize(vol, capacity, flags);
13381
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
13384
virDispatchError(vol->conn);
12533
13389
* virNodeNumOfDevices:
12534
13390
* @conn: pointer to the hypervisor connection
12535
13391
* @cap: capability name
12536
* @flags: flags (unused, pass 0)
13392
* @flags: extra flags; not used yet, so callers should always pass 0
12538
13394
* Provides the number of node devices.
16252
17108
* inconsistent (as if power had been pulled), and specifying this
16253
17109
* with the VIR_DOMAIN_SNAPSHOT_CREATE_HALT flag risks data loss.
17111
* If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_QUIESCE, then the
17112
* libvirt will attempt to use guest agent to freeze and thaw all
17113
* file systems in use within domain OS. However, if the guest agent
17114
* is not present, an error is thrown. Moreover, this flag requires
17115
* VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY to be passed as well.
17117
* By default, if the snapshot involves external files, and any of the
17118
* destination files already exist as a non-empty regular file, the
17119
* snapshot is rejected to avoid losing contents of those files.
17120
* However, if @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_REUSE_EXT,
17121
* then the destination files must already exist and contain content
17122
* identical to the source files (this allows a management app to
17123
* pre-create files with relative backing file names, rather than the
17124
* default of creating with absolute backing file names).
17126
* Be aware that although libvirt prefers to report errors up front with
17127
* no other effect, some hypervisors have certain types of failures where
17128
* the overall command can easily fail even though the guest configuration
17129
* was partially altered (for example, if a disk snapshot request for two
17130
* disks fails on the second disk, but the first disk alteration cannot be
17131
* rolled back). If this API call fails, it is therefore normally
17132
* necessary to follow up with virDomainGetXMLDesc() and check each disk
17133
* to determine if any partial changes occurred. However, if @flags
17134
* contains VIR_DOMAIN_SNAPSHOT_CREATE_ATOMIC, then libvirt guarantees
17135
* that this command will not alter any disks unless the entire set of
17136
* changes can be done atomically, making failure recovery simpler (note
17137
* that it is still possible to fail after disks have changed, but only
17138
* in the much rarer cases of running out of memory or disk space).
17140
* Some hypervisors may prevent this operation if there is a current
17141
* block copy operation; in that case, use virDomainBlockJobAbort()
17142
* to stop the block copy first.
16255
17144
* Returns an (opaque) virDomainSnapshotPtr on success, NULL on failure.
16257
17146
virDomainSnapshotPtr
17027
17930
* can be found by calling virDomainGetXMLDesc() and inspecting
17028
17931
* elements within //domain/devices/disk.
17933
* If the current block job for @disk is VIR_DOMAIN_BLOCK_JOB_TYPE_PULL, then
17934
* by default, this function performs a synchronous operation and the caller
17935
* may assume that the operation has completed when 0 is returned. However,
17936
* BlockJob operations may take a long time to cancel, and during this time
17937
* further domain interactions may be unresponsive. To avoid this problem,
17938
* pass VIR_DOMAIN_BLOCK_JOB_ABORT_ASYNC in the @flags argument to enable
17939
* asynchronous behavior, returning as soon as possible. When the job has
17940
* been canceled, a BlockJob event will be emitted, with status
17941
* VIR_DOMAIN_BLOCK_JOB_CANCELED (even if the ABORT_ASYNC flag was not
17942
* used); it is also possible to poll virDomainBlockJobInfo() to see if
17943
* the job cancellation is still pending. This type of job can be restarted
17944
* to pick up from where it left off.
17946
* If the current block job for @disk is VIR_DOMAIN_BLOCK_JOB_TYPE_COPY, then
17947
* the default is to abort the mirroring and revert to the source disk;
17948
* adding @flags of VIR_DOMAIN_BLOCK_JOB_ABORT_PIVOT causes this call to
17949
* fail with VIR_ERR_BLOCK_COPY_ACTIVE if the copy is not fully populated,
17950
* otherwise it will swap the disk over to the copy to end the mirroring. An
17951
* event will be issued when the job is ended, and it is possible to use
17952
* VIR_DOMAIN_BLOCK_JOB_ABORT_ASYNC to control whether this command waits
17953
* for the completion of the job. Restarting this job requires starting
17954
* over from the beginning of the first phase.
17030
17956
* Returns -1 in case of failure, 0 when successful.
17032
17958
int virDomainBlockJobAbort(virDomainPtr dom, const char *disk,
18201
* virDomainBlockRebase:
18202
* @dom: pointer to domain object
18203
* @disk: path to the block device, or device shorthand
18204
* @base: path to backing file to keep, or NULL for no backing file
18205
* @bandwidth: (optional) specify copy bandwidth limit in Mbps
18206
* @flags: bitwise-OR of virDomainBlockRebaseFlags
18208
* Populate a disk image with data from its backing image chain, and
18209
* setting the backing image to @base, or alternatively copy an entire
18210
* backing chain to a new file @base.
18212
* When @flags is 0, this starts a pull, where @base must be the absolute
18213
* path of one of the backing images further up the chain, or NULL to
18214
* convert the disk image so that it has no backing image. Once all
18215
* data from its backing image chain has been pulled, the disk no
18216
* longer depends on those intermediate backing images. This function
18217
* pulls data for the entire device in the background. Progress of
18218
* the operation can be checked with virDomainGetBlockJobInfo() with a
18219
* job type of VIR_DOMAIN_BLOCK_JOB_TYPE_PULL, and the operation can be
18220
* aborted with virDomainBlockJobAbort(). When finished, an asynchronous
18221
* event is raised to indicate the final status, and the job no longer
18222
* exists. If the job is aborted, a new one can be started later to
18223
* resume from the same point.
18225
* When @flags includes VIR_DOMAIN_BLOCK_REBASE_COPY, this starts a copy,
18226
* where @base must be the name of a new file to copy the chain to. By
18227
* default, the copy will pull the entire source chain into the destination
18228
* file, but if @flags also contains VIR_DOMAIN_BLOCK_REBASE_SHALLOW, then
18229
* only the top of the source chain will be copied (the source and
18230
* destination have a common backing file). By default, @base will be
18231
* created with the same file format as the source, but this can be altered
18232
* by adding VIR_DOMAIN_BLOCK_REBASE_COPY_RAW to force the copy to be raw
18233
* (does not make sense with the shallow flag unless the source is also raw),
18234
* or by using VIR_DOMAIN_BLOCK_REBASE_REUSE_EXT to reuse an existing file
18235
* with initial contents identical to the backing file of the source (this
18236
* allows a management app to pre-create files with relative backing file
18237
* names, rather than the default of absolute backing file names; as a
18238
* security precaution, you should generally only use reuse_ext with the
18239
* shallow flag and a non-raw destination file).
18241
* A copy job has two parts; in the first phase, the @bandwidth parameter
18242
* affects how fast the source is pulled into the destination, and the job
18243
* can only be canceled by reverting to the source file; progress in this
18244
* phase can be tracked via the virDomainBlockJobInfo() command, with a
18245
* job type of VIR_DOMAIN_BLOCK_JOB_TYPE_COPY. The job transitions to the
18246
* second phase when the job info states cur == end, and remains alive to
18247
* mirror all further changes to both source and destination. The user
18248
* must call virDomainBlockJobAbort() to end the mirroring while choosing
18249
* whether to revert to source or pivot to the destination. An event is
18250
* issued when the job ends, and in the future, an event may be added when
18251
* the job transitions from pulling to mirroring. If the job is aborted,
18252
* a new job will have to start over from the beginning of the first phase.
18254
* Some hypervisors will restrict certain actions, such as virDomainSave()
18255
* or virDomainDetachDevice(), while a copy job is active; they may
18256
* also restrict a copy job to transient domains.
18258
* The @disk parameter is either an unambiguous source name of the
18259
* block device (the <source file='...'/> sub-element, such as
18260
* "/path/to/image"), or the device target shorthand (the
18261
* <target dev='...'/> sub-element, such as "xvda"). Valid names
18262
* can be found by calling virDomainGetXMLDesc() and inspecting
18263
* elements within //domain/devices/disk.
18265
* The maximum bandwidth (in Mbps) that will be used to do the copy can be
18266
* specified with the bandwidth parameter. If set to 0, libvirt will choose a
18267
* suitable default. Some hypervisors do not support this feature and will
18268
* return an error if bandwidth is not 0; in this case, it might still be
18269
* possible for a later call to virDomainBlockJobSetSpeed() to succeed.
18270
* The actual speed can be determined with virDomainGetBlockJobInfo().
18272
* When @base is NULL and @flags is 0, this is identical to
18273
* virDomainBlockPull().
18275
* Returns 0 if the operation has started, -1 on failure.
18277
int virDomainBlockRebase(virDomainPtr dom, const char *disk,
18278
const char *base, unsigned long bandwidth,
18279
unsigned int flags)
18281
virConnectPtr conn;
18283
VIR_DOMAIN_DEBUG(dom, "disk=%s, base=%s bandwidth=%lu, flags=%x",
18284
disk, NULLSTR(base), bandwidth, flags);
18286
virResetLastError();
18288
if (!VIR_IS_CONNECTED_DOMAIN (dom)) {
18289
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
18290
virDispatchError(NULL);
18295
if (dom->conn->flags & VIR_CONNECT_RO) {
18296
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
18301
virLibDomainError(VIR_ERR_INVALID_ARG,
18302
_("disk is NULL"));
18306
if (flags & VIR_DOMAIN_BLOCK_REBASE_COPY) {
18308
virLibDomainError(VIR_ERR_INVALID_ARG,
18309
_("base is required when starting a copy"));
18312
} else if (flags & (VIR_DOMAIN_BLOCK_REBASE_SHALLOW |
18313
VIR_DOMAIN_BLOCK_REBASE_REUSE_EXT |
18314
VIR_DOMAIN_BLOCK_REBASE_COPY_RAW)) {
18315
virLibDomainError(VIR_ERR_INVALID_ARG,
18316
_("use of flags requires a copy job"));
18320
if (conn->driver->domainBlockRebase) {
18322
ret = conn->driver->domainBlockRebase(dom, disk, base, bandwidth,
18329
virLibDomainError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
18332
virDispatchError(dom->conn);
17271
18338
* virDomainOpenGraphics:
17272
18339
* @dom: pointer to domain object
17273
18340
* @idx: index of graphics config to open
17274
18341
* @fd: file descriptor to attach graphics to
17275
* @flags: flags to control open operation
18342
* @flags: bitwise-OR of virDomainOpenGraphicsFlags
17277
18344
* This will attempt to connect the file descriptor @fd, to
17278
18345
* the graphics backend of @dom. If @dom has multiple graphics
17599
18664
virDispatchError(dom->conn);
18669
* virDomainGetCPUStats:
18670
* @domain: domain to query
18671
* @params: array to populate on output
18672
* @nparams: number of parameters per cpu
18673
* @start_cpu: which cpu to start with, or -1 for summary
18674
* @ncpus: how many cpus to query
18675
* @flags: bitwise-OR of virTypedParameterFlags
18677
* Get statistics relating to CPU usage attributable to a single
18678
* domain (in contrast to the statistics returned by
18679
* virNodeGetCPUStats() for all processes on the host). @dom
18680
* must be running (an inactive domain has no attributable cpu
18681
* usage). On input, @params must contain at least @nparams * @ncpus
18682
* entries, allocated by the caller.
18684
* If @start_cpu is -1, then @ncpus must be 1, and the returned
18685
* results reflect the statistics attributable to the entire
18686
* domain (such as user and system time for the process as a
18687
* whole). Otherwise, @start_cpu represents which cpu to start
18688
* with, and @ncpus represents how many consecutive processors to
18689
* query, with statistics attributable per processor (such as
18690
* per-cpu usage). If @ncpus is larger than the number of cpus
18691
* available to query, then the trailing part of the array will
18694
* The remote driver imposes a limit of 128 @ncpus and 16 @nparams;
18695
* the number of parameters per cpu should not exceed 16, but if you
18696
* have a host with more than 128 CPUs, your program should split
18697
* the request into multiple calls.
18699
* As special cases, if @params is NULL and @nparams is 0 and
18700
* @ncpus is 1, and the return value will be how many
18701
* statistics are available for the given @start_cpu. This number
18702
* may be different for @start_cpu of -1 than for any non-negative
18703
* value, but will be the same for all non-negative @start_cpu.
18704
* Likewise, if @params is NULL and @nparams is 0 and @ncpus is 0,
18705
* the number of cpus available to query is returned. From the
18706
* host perspective, this would typically match the cpus member
18707
* of virNodeGetInfo(), but might be less due to host cpu hotplug.
18709
* For now, @flags is unused, and the statistics all relate to the
18710
* usage from the host perspective. It is possible that a future
18711
* version will support a flag that queries the cpu usage from the
18712
* guest's perspective, where the maximum cpu to query would be
18713
* related to virDomainGetVcpusFlags() rather than virNodeGetInfo().
18714
* An individual guest vcpu cannot be reliably mapped back to a
18715
* specific host cpu unless a single-processor vcpu pinning was used,
18716
* but when @start_cpu is -1, any difference in usage between a host
18717
* and guest perspective would serve as a measure of hypervisor overhead.
18719
* Typical use sequence is below.
18721
* getting total stats: set start_cpu as -1, ncpus 1
18722
* virDomainGetCPUStats(dom, NULL, 0, -1, 1, 0) => nparams
18723
* params = calloc(nparams, sizeof(virTypedParameter))
18724
* virDomainGetCPUStats(dom, params, nparams, -1, 1, 0) => total stats.
18726
* getting per-cpu stats:
18727
* virDomainGetCPUStats(dom, NULL, 0, 0, 0, 0) => ncpus
18728
* virDomainGetCPUStats(dom, NULL, 0, 0, 1, 0) => nparams
18729
* params = calloc(ncpus * nparams, sizeof(virTypedParameter))
18730
* virDomainGetCPUStats(dom, params, nparams, 0, ncpus, 0) => per-cpu stats
18732
* Returns -1 on failure, or the number of statistics that were
18733
* populated per cpu on success (this will be less than the total
18734
* number of populated @params, unless @ncpus was 1; and may be
18735
* less than @nparams). The populated parameters start at each
18736
* stride of @nparams, which means the results may be discontiguous;
18737
* any unpopulated parameters will be zeroed on success (this includes
18738
* skipped elements if @nparams is too large, and tail elements if
18739
* @ncpus is too large). The caller is responsible for freeing any
18740
* returned string parameters.
18742
int virDomainGetCPUStats(virDomainPtr domain,
18743
virTypedParameterPtr params,
18744
unsigned int nparams,
18746
unsigned int ncpus,
18747
unsigned int flags)
18749
virConnectPtr conn;
18751
VIR_DOMAIN_DEBUG(domain,
18752
"params=%p, nparams=%d, start_cpu=%d, ncpus=%u, flags=%x",
18753
params, nparams, start_cpu, ncpus, flags);
18754
virResetLastError();
18756
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
18757
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
18758
virDispatchError(NULL);
18762
conn = domain->conn;
18764
* start_cpu must be non-negative, or else -1
18765
* if start_cpu is -1, ncpus must be 1
18766
* params == NULL must match nparams == 0
18767
* ncpus must be non-zero unless params == NULL
18768
* nparams * ncpus must not overflow (RPC may restrict it even more)
18770
if (start_cpu < -1 ||
18771
(start_cpu == -1 && ncpus != 1) ||
18772
((params == NULL) != (nparams == 0)) ||
18773
(ncpus == 0 && params != NULL)) {
18774
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
18777
if (nparams && ncpus > UINT_MAX / nparams) {
18778
virLibDomainError(VIR_ERR_OVERFLOW, _("input too large: %u * %u"),
18782
if (VIR_DRV_SUPPORTS_FEATURE(domain->conn->driver, domain->conn,
18783
VIR_DRV_FEATURE_TYPED_PARAM_STRING))
18784
flags |= VIR_TYPED_PARAM_STRING_OKAY;
18786
if (conn->driver->domainGetCPUStats) {
18789
ret = conn->driver->domainGetCPUStats(domain, params, nparams,
18790
start_cpu, ncpus, flags);
18796
virLibDomainError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
18799
virDispatchError(domain->conn);
18804
* virDomainGetDiskErrors:
18805
* @dom: a domain object
18806
* @errors: array to populate on output
18807
* @maxerrors: size of @errors array
18808
* @flags: extra flags; not used yet, so callers should always pass 0
18810
* The function populates @errors array with all disks that encountered an
18811
* I/O error. Disks with no error will not be returned in the @errors array.
18812
* Each disk is identified by its target (the dev attribute of target
18813
* subelement in domain XML), such as "vda", and accompanied with the error
18814
* that was seen on it. The caller is also responsible for calling free()
18815
* on each disk name returned.
18817
* In a special case when @errors is NULL and @maxerrors is 0, the function
18818
* returns preferred size of @errors that the caller should use to get all
18821
* Since calling virDomainGetDiskErrors(dom, NULL, 0, 0) to get preferred size
18822
* of @errors array and getting the errors are two separate operations, new
18823
* disks may be hotplugged to the domain and new errors may be encountered
18824
* between the two calls. Thus, this function may not return all disk errors
18825
* because the supplied array is not large enough. Such errors may, however,
18826
* be detected by listening to domain events.
18828
* Returns number of disks with errors filled in the @errors array or -1 on
18832
virDomainGetDiskErrors(virDomainPtr dom,
18833
virDomainDiskErrorPtr errors,
18834
unsigned int maxerrors,
18835
unsigned int flags)
18837
VIR_DOMAIN_DEBUG(dom, "errors=%p, maxerrors=%u, flags=%x",
18838
errors, maxerrors, flags);
18840
virResetLastError();
18842
if (!VIR_IS_DOMAIN(dom)) {
18843
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
18844
virDispatchError(NULL);
18848
if ((!errors && maxerrors) || (errors && !maxerrors)) {
18849
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
18853
if (dom->conn->driver->domainGetDiskErrors) {
18854
int ret = dom->conn->driver->domainGetDiskErrors(dom, errors,
18861
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
18864
virDispatchError(dom->conn);
added
removed
src/libvirt.c
