Provides the interfaces of the libvirt library to handle qemu specific methods
typedef enum virConnectDomainQemuMonitorEventRegisterFlags typedef enum virDomainQemuAgentCommandTimeoutValues typedef enum virDomainQemuMonitorCommandFlags
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) int virDomainQemuMonitorCommandWithFiles (virDomainPtr domain,
const char * cmd,
unsigned int ninfiles,
int * infiles,
unsigned int * noutfiles,
int ** outfiles,
char ** result,
unsigned int flags)
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 |
}
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().
virConnectDomainQemuMonitorEventDeregister¶int virConnectDomainQemuMonitorEventDeregister (virConnectPtr conn, int callbackID)
Removes an event callback. The callbackID parameter should be the value obtained from a previous virConnectDomainQemuMonitorEventRegister() method.
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.
| Object | Permission | Condition |
|---|---|---|
| connect | search-domains | - |
| connect | write | - |
| Object | Permission |
|---|---|
| domain | getattr |
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
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).
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.
cmdvirDomainQemuMonitorCommandWithFiles¶int virDomainQemuMonitorCommandWithFiles (virDomainPtr domain, const char * cmd, unsigned int ninfiles, int * infiles, unsigned int * noutfiles, int ** outfiles, char ** result, unsigned int flags)
This API is QEMU specific, so it will only work with hypervisor connections to the QEMU driver with local connections using the unix socket.
Send an arbitrary monitor command cmd with file descriptors infiles to domain through the QEMU monitor and optionally return file descriptors via outfiles. 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.
infilescmd