You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

2.4 KiB

== qmp_client

This library interfaces with a running QEMU process using the QMP protocol. It
also works with the QEMU-KVM branch.

To get a QMP socket for a QEMU process, use one of these command-line arguments:
-qmp tcp:[host]:port[,server][,nowait][,nodelay]
-qmp unix:path[,server][,nowait]
-qmp stdio
-qmp pipe:filename

The QMP protocol is still evolving, and the kinds of things you can do with it
are changing with each release. It's also currently (QEMU 0.15) impossible to
set every option available on the command line via the QMP console. However,
there are plans to make that possible, and this library will track the features
available from the server as closely as possible.

Usage example:

QMPClient::connect_tcp("", 4440) do |api|

api.on_event('BLOCK_IO_ERROR') do |e|
puts "Block I/O error detected: #{e.inspect}"

msg = api.sync_query("status") # Blocks until a response comes back
puts "VM status: #{m.inspect}"

api.command('eject', 'device' => 'ide1-cd0') {|m| puts "CDROM ejected" }
api.query("status") {|m| puts "VM status now: #{m.inspect}" }

api.wait # Blocks until no commands or queries are outstanding.

api.command('quit') # Specifying a callback is optional

You can also do this perfectly safely:

stopq =
api_outer = nil do
QMPClient::connect_tcp("", 4440) do |api_inner|
api = api_inner

sleep(0.1) while api_outer.nil?
# do stuff with the api object

Or, indeed, this:

QMPClient::connect_tcp("", 4440) do |api| { }.join # use the API object in here

Callbacks are run on a thread pool; if an exception is raised on one of those
threads, the process aborts. The default thread pool size is 10. Both of these
things will be made configurable later.

More information about QMP can be found at the following locations:

Patches to fix bugs or support new functionality are welcome. To submit a patch
or report a bug, go to - follow the usual
fork, commit fixes and tests, send pull request procedure for github.

The aim is to be compatible with Ruby 1.8.7 and 1.9.3 as implemented by MRI,
Rubinius and JRuby - tests and fixes to that aim are especially welcomed.

See LICENSE for copyright details.

- Nick Thomas <>