2019b7c blockjob: add new --raw flag to virsh blockjob

Authored and Committed by ericb 9 years ago
    blockjob: add new --raw flag to virsh blockjob
    
    The current output of 'blockjob [--info]' is a single line
    designed for human consumption; it's not very nice for machine
    parsing.  Furthermore, I have plans to modify the line in
    response to the new flag for controlling bandwidth units.
    Solve that by adding a --raw parameter, which outputs
    information closer to the C struct.
    
    $ virsh blockjob testvm1 vda --raw
     type=Block Copy
     bandwidth=1
     cur=197120
     end=197120
    
    The information is indented, because I'd like for a later patch
    to add a mode that iterates over all the vm's disks with status
    for each; in that mode, each block name would be listed unindented
    before information (if any) about that block.
    
    Now that we have a raw mode, we can guarantee that it won't change
    format over time.  Any app that cares about parsing the output can
    try --raw, and if it fails, know that it was talking to an older
    virsh and fall back to parsing the human-readable format which had
    not changed until now; meanwhile, when not using --raw, we have
    freed future virsh to change the output to whatever makes sense.
    
    My first change to human mode: this command now guarantees a line
    is printed on successful use of the API, even when the API did
    not find a current block job (consistent with the rest of virsh).
    
    Bonus: https://bugzilla.redhat.com/show_bug.cgi?id=1135441
    complained that this message was confusing:
    
    $ virsh blockjob test1 hda  --async --bandwidth 10
    error: conflict between --abort, --info, and --bandwidth modes
    
    even though the man page already documents that --async implies
    abort mode, all because '--abort' wasn't present in the command
    line.  Since I'm adding another case where options are tied
    to or imply a mode, I changed that error to:
    
    error: conflict between abort, info, and bandwidth modes
    
    * tools/virsh-domain.c (cmdBlockJob): Add --raw parameter; tweak
    error wording.
    * tools/virsh.pod (blockjob): Document it.
    
    Signed-off-by: Eric Blake <eblake@redhat.com>
    
        
file modified
+23 -8
file modified
+12 -7