Bug 529380

+++ This bug was initially created as a clone of Bug #514532 +++

Description of problem:

Quote (virsh man page) ---
 Most virsh commands act asynchronously, so just because the virsh pro-
 gram returned, doesn’t mean the action is complete.  This is important,
 as many operations on domains, like create and shutdown, can take con-
 siderable time (30 seconds or more) to bring the machine into a fully
 compliant state.  If you want to know when one of these actions has
 finished you must poll through virsh list periodically.
---

The virsh man page describes 'most operations' as being 'asynchronous', which is not the case.  The virsh commands are tied in to the libvirt APIs which are synchronous.  It looks like the paragraph in question was lifted directly from the 'xm' man page without being updated:


Quote (xm man page) ---
 Most xm commands act asynchronously, so just because the xm command
 returned, doesn’t mean the action is complete.  This is important, as
 many operations on domains, like create and shutdown, can take consid-
 erable time (30 seconds or more) to bring the machine into a fully com-
 pliant state.  If you want to know when one of these actions has fin-
 ished you must poll through xm list periodically.
---


In practice, the implementation of shell scripts using
'virsh', following the man page as it is documented must
do:

   virsh [command]
   if [ $? -eq 0 ]; then
     # per virsh man page...
     # operation was started, now poll to see
     # if it completed
     # if a timeout occurs, give up.
     while ...; do
       ...
       if [ $complete ]; then
         return 0
       fi
     done
   fi
   return 1




Expected results:

It would be nice to either:
(a) remove the above paragraph from the virsh man page, or
(b) explicitly define which virsh commands, if any, are
    actually asynchronous

It is my understanding based on talks with libvirt developers that none of the commands are asynchronous today and that the paragraph is simply wrong.

Either way, clarifying the man page will allow administrators and developers who write scripts around 'virsh' have a reasonable expectation about whether the return code reflects the completion of the operation.  For example:

   virsh [command]
   return $?

--- Additional comment from lhh on 2009-07-29 10:55:10 EDT ---

libvirt-0.6.3-14.el5

---------------------------------------------------------------------------

The same problem exists in the "xm" man page (where this text was lifted from).  The xm migrate, xm save, xm restore commands (at least) are synchronous, and possibly some others.  We should explicitly say which ones are synchronous and which ones aren't.