The new API splits orderly close into a two-step process:

  if (guestfs_shutdown (g) == -1) {
    /* handle the error, eg. qemu error */
  }
  guestfs_close (g);

Note that the explicit shutdown step is only necessary in the case
where you have made changes to the disk image and want to handle write
errors.  Read the documentation for further information.

This change also:

 - deprecates guestfs_kill_subprocess

 - turns guestfs_kill_subprocess into the same as guestfs_shutdown

 - changes guestfish and other tools to call shutdown + close
   where necessary (not for read-only tools)

 - updates documentation

 - updates examples

(cherry picked from commit ffbf1475f7ae7c462db289ad4834391469e72edd)

This was always incorrect behaviour, but qemu appears to tolerate it.

This cherry picks just the test fixes from
commit 729bb9c6b5ae0c0e7c68dc802b1617936062f966.

'del g' is a trap for the unwary.  If the handle has any other
references, it does nothing (in fact, it can be actively dangerous if
the user was expecting the appliance to go away).  In non-CPython it
can be delayed arbitrarily long.

Using 'g.close()' on the other hand is always safe.

Update all copyright dates to 2012.

This implements set_event_callback and delete_event_callback so that
Python programs can use the new event mechanism.

This large commit changes the generator so that optional arguments
can be supported for functions.

The model for arguments (known as the "style") is changed from
(ret, args) to (ret, args, optargs) where optargs is a more limited
list of arguments.

One function has been added which takes optional arguments, it is
"add-drive-opts", modelled as:

  (RErr, [String "filename"], #required
         [Bool "readonly"; String "format"; String "iface"]) #optional

Note that this function is processed in the library (does not go over
the RPC protocol to the daemon).  This has allowed us to simplify
the current implementation by omitting changes related to RPC or the
daemon, although we plan to add these at some point in the future.

From C this function can be called in 3 different ways as in these
examples:

  guestfs_add_drive_opts (g, filename,
                          GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
			  GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
                          -1);

(the argument(s) between 'filename' and '-1' are the optional ones).

  guestfs_add_drive_opts_va (g, filename, args);

where 'args' is a va_list.  This works like the first version.

  struct guestfs_add_drive_opts_argv optargs = {
    .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK,
    .readonly = 1,
  }
  guestfs_add_drive_opts_argv (g, filename, &optargs);

This last form lets you construct lists of optional arguments, and
is used by guestfish and the language bindings.

In guestfish optional arguments are used like this:

  add-drive-opts filename readonly:true

In OCaml these are mapped naturally to OCaml optional arguments, eg:

  g#add_drive_opts ~readonly:true filename;

In Perl these are mapped to extra arguments, eg:

  $g->add_drive_opts ($filename, readonly => 1);

In Python these are mapped to optional arguments, eg:

  g.add_drive_opts ("file", readonly = 1, format = "qcow2")

In Ruby these are mapped to a final hash argument, eg:

  g.add_drive_opts("file", {})
  g.add_drive_opts("file", :readonly => 1)
  g.add_drive_opts("file", :readonly => 1, :iface => "virtio")

In PHP these are mapped to extra parameters.  This is not quite
accurate since you cannot omit arbitrary optional parameters, but
there's not much than can be done within the limitations of PHP
as a language.

Unimplemented in: Haskell, C#, Java.