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