Module libvirt-qemu from libvirt-qemu
Provides the interfaces of the libvirt library to handle qemu specific methods Copyright (C) 2010-2014 Red Hat, Inc. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library. If not, see http://www.gnu.org/licenses/.
Table of Contents
Types
typedef enum virConnectDomainQemuMonitorEventRegisterFlags typedef enum virDomainQemuAgentCommandTimeoutValues typedef enum virDomainQemuMonitorCommandFlags
Functions
typedef virConnectDomainQemuMonitorEventCallback void virConnectDomainQemuMonitorEventCallback (virConnectPtr conn,
virDomainPtr dom,
const char * event,
long long seconds,
unsigned int micros,
const char * details,
void * opaque) int virConnectDomainQemuMonitorEventDeregister (virConnectPtr conn,
int callbackID) int virConnectDomainQemuMonitorEventRegister (virConnectPtr conn,
virDomainPtr dom,
const char * event,
virConnectDomainQemuMonitorEventCallback cb,
void * opaque,
virFreeCallback freecb,
unsigned int flags) char * virDomainQemuAgentCommand (virDomainPtr domain,
const char * cmd,
int timeout,
unsigned int flags) virDomainPtr virDomainQemuAttach (virConnectPtr conn,
unsigned int pid_value,
unsigned int flags) int virDomainQemuMonitorCommand (virDomainPtr domain,
const char * cmd,
char ** result,
unsigned int flags)
Description
Types ¶
virConnectDomainQemuMonitorEventRegisterFlags
¶
enum virConnectDomainQemuMonitorEventRegisterFlags {
VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_REGEX | = | 1 (0x1; 1 << 0) |
Event filter is a regex rather than a literal string
|
VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_NOCASE | = | 2 (0x2; 1 << 1) |
Event filter is case insensitive
|
}
virDomainQemuAgentCommandTimeoutValues
¶
enum virDomainQemuAgentCommandTimeoutValues {
VIR_DOMAIN_QEMU_AGENT_COMMAND_BLOCK | = | VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK | |
VIR_DOMAIN_QEMU_AGENT_COMMAND_DEFAULT | = | VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_DEFAULT | |
VIR_DOMAIN_QEMU_AGENT_COMMAND_MIN | = | VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK | |
VIR_DOMAIN_QEMU_AGENT_COMMAND_NOWAIT | = | VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_NOWAIT | |
VIR_DOMAIN_QEMU_AGENT_COMMAND_SHUTDOWN | = | 60 (0x3c) |
}
virDomainQemuMonitorCommandFlags
¶
enum virDomainQemuMonitorCommandFlags {
VIR_DOMAIN_QEMU_MONITOR_COMMAND_DEFAULT | = | 0 (0x0) | |
VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP | = | 1 (0x1; 1 << 0) |
cmd is in HMP
|
}
Functions ¶
virConnectDomainQemuMonitorEventCallback
¶
typedef void (*virConnectDomainQemuMonitorEventCallback) (virConnectPtr conn, virDomainPtr dom, const char * event, long long seconds, unsigned int micros, const char * details, void * opaque)
The callback signature to use when registering for a qemu monitor event with virConnectDomainQemuMonitorEventRegister().
- conn
- the connection pointer
- dom
- the domain pointer
- event
- the name of the event
- seconds
- the qemu timestamp of the event: seconds since Epoch, or -1 if not available
- micros
- the qemu timestamp of the event: microseconds within the second
- details
- the JSON details of the event, if any were given
- opaque
- application specified data
virConnectDomainQemuMonitorEventDeregister
¶
int virConnectDomainQemuMonitorEventDeregister (virConnectPtr conn, int callbackID)
Removes an event callback. The callbackID parameter should be the value obtained from a previous virConnectDomainQemuMonitorEventRegister() method.
- conn
- pointer to the connection
- callbackID
- the callback identifier
- Returns
- 0 on success, -1 on failure
virConnectDomainQemuMonitorEventRegister
¶
int virConnectDomainQemuMonitorEventRegister (virConnectPtr conn, virDomainPtr dom, const char * event, virConnectDomainQemuMonitorEventCallback cb, void * opaque, virFreeCallback freecb, unsigned int flags)
This API is QEMU specific, so it will only work with hypervisor connections to the QEMU driver.
Adds a callback to receive notifications of arbitrary qemu monitor events occurring on a domain. Many qemu monitor events also result in a libvirt event which can be delivered via virConnectDomainEventRegisterAny(); this command is primarily for testing new qemu events that have not yet been given a libvirt counterpart event.
If @dom is NULL, then events will be monitored for any domain. If @dom is non-NULL, then only the specific domain will be monitored.
If @event is NULL, then all monitor events will be reported. If @event is non-NULL, then only specific monitor events will be reported. @flags controls how the filtering is performed: 0 requests an exact match, while VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_REGEX states that @event is a basic regular expression. Additionally, including VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_NOCASE lets @event match case-insensitively.
The virDomainPtr object handle passed into the callback upon delivery of an event is only valid for the duration of execution of the callback. If the callback wishes to keep the domain object after the callback returns, it shall take a reference to it, by calling virDomainRef(). The reference can be released once the object is no longer required by calling virDomainFree().
The return value from this method is a positive integer identifier for the callback. To unregister a callback, this callback ID should be passed to the virConnectDomainQemuMonitorEventDeregister() method.
- conn
- pointer to the connection
- dom
- pointer to the domain, or NULL
- event
- name of the event, or NULL
- cb
- callback to the function handling monitor events
- opaque
- opaque data to pass on to the callback
- freecb
- optional function to deallocate opaque when not used anymore
- flags
- bitwise-OR of virConnectDomainQemuMonitorEventRegisterFlags
- Returns
- a callback identifier on success, -1 on failure
virDomainQemuAgentCommand
¶
char * virDomainQemuAgentCommand (virDomainPtr domain, const char * cmd, int timeout, unsigned int flags)
Execute an arbitrary Guest Agent command.
Issue @cmd to the guest agent running in @domain. @timeout must be -2, -1, 0 or positive. VIR_DOMAIN_QEMU_AGENT_COMMAND_BLOCK(-2): meaning to block forever waiting for a result. VIR_DOMAIN_QEMU_AGENT_COMMAND_DEFAULT(-1): use default timeout value. VIR_DOMAIN_QEMU_AGENT_COMMAND_NOWAIT(0): does not wait. positive value: wait for @timeout seconds
- domain
- a domain object
- cmd
- the guest agent command string
- timeout
- timeout seconds
- flags
- execution flags
- Returns
- strings if success, NULL in failure.
virDomainQemuAttach
¶
virDomainPtr virDomainQemuAttach (virConnectPtr conn, unsigned int pid_value, unsigned int flags)
This API is QEMU specific, so it will only work with hypervisor connections to the QEMU driver.
This API will attach to an externally launched QEMU process identified by @pid. There are several requirements to successfully attach to an external QEMU process:
- It must have been started with a monitor socket using the UNIX domain socket protocol. - No device hotplug/unplug, or other configuration changes can have been made via the monitor since it started. - The '-name' and '-uuid' arguments should have been set (not mandatory, but strongly recommended)
To date, the only platforms we know of where pid_t is larger than unsigned int (64-bit Windows) also lack UNIX sockets, so the choice of @pid_value as an unsigned int should not present any difficulties.
If successful, then the guest will appear in the list of running domains for this connection, and other APIs should operate normally (provided the above requirements were honored).
- conn
- pointer to a hypervisor connection
- pid_value
- the UNIX process ID of the external QEMU process
- flags
- optional flags, currently unused
- Returns
- a new domain object on success, NULL otherwise
virDomainQemuMonitorCommand
¶
int virDomainQemuMonitorCommand (virDomainPtr domain, const char * cmd, char ** result, unsigned int flags)
This API is QEMU specific, so it will only work with hypervisor connections to the QEMU driver.
Send an arbitrary monitor command @cmd to @domain through the qemu monitor. There are several requirements to safely and successfully use this API:
- A @cmd that queries state without making any modifications is safe - A @cmd that alters state that is also tracked by libvirt is unsafe, and may cause libvirtd to crash - A @cmd that alters state not tracked by the current version of libvirt is possible as a means to test new qemu features before they have support in libvirt, but no guarantees are made to safety
If VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP is set, the command is considered to be a human monitor command and libvirt will automatically convert it into QMP if needed. In that case the @result will also be converted back from QMP.
If successful, @result will be filled with the string output of the @cmd, and the caller must free this string.
- domain
- a domain object
- cmd
- the qemu monitor command string
- result
- a string returned by @cmd
- flags
- bitwise-or of supported virDomainQemuMonitorCommandFlags
- Returns
- 0 in case of success, -1 in case of failure