diff mbox

[v2,1/1] doc: document chardev option 'append'

Message ID 1450777749-14022-1-git-send-email-den@openvz.org
State New
Headers show

Commit Message

Denis V. Lunev Dec. 22, 2015, 9:49 a.m. UTC
commit 31e38a22a0c5a25646f966f001e1f5513d5a186d
    Author: Olga Krishtal <okrishtal@virtuozzo.com>
    Date:   Fri Dec 4 09:42:04 2015 +0300

        qemu-char: append opt to stop truncation of serial file

has added the option to the runtime but does not added it to -help
output. This blocks libvirt from using it.

Signed-off-by: Denis V. Lunev <den@openvz.org>
CC: Dmitry Mishin <dim@virtuozzo.com>
CC: Eric Blake <eblake@redhat.com>
CC: Markus Armbruster <armbru@redhat.com>
CC: Paolo Bonzini <pbonzini@redhat.com>
---
Changes from v1:
- fixed default value to 'off'

 qemu-options.hx | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

Comments

Daniel P. Berrangé Dec. 22, 2015, 10:26 a.m. UTC | #1
On Tue, Dec 22, 2015 at 12:49:09PM +0300, Denis V. Lunev wrote:
>     commit 31e38a22a0c5a25646f966f001e1f5513d5a186d
>     Author: Olga Krishtal <okrishtal@virtuozzo.com>
>     Date:   Fri Dec 4 09:42:04 2015 +0300
> 
>         qemu-char: append opt to stop truncation of serial file
> 
> has added the option to the runtime but does not added it to -help
> output. This blocks libvirt from using it.

You can remove this sentance about libvirt - we stopped parsing
-help output a long time ago. We exclusively use QMP now.

> 
> Signed-off-by: Denis V. Lunev <den@openvz.org>
> CC: Dmitry Mishin <dim@virtuozzo.com>
> CC: Eric Blake <eblake@redhat.com>
> CC: Markus Armbruster <armbru@redhat.com>
> CC: Paolo Bonzini <pbonzini@redhat.com>
> ---
> Changes from v1:
> - fixed default value to 'off'
> 
>  qemu-options.hx | 7 +++++--
>  1 file changed, 5 insertions(+), 2 deletions(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 49afe6c..f706e4a 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -2044,7 +2044,7 @@ DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
>      "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
>      "         [,mux=on|off]\n"
>      "-chardev ringbuf,id=id[,size=size]\n"
> -    "-chardev file,id=id,path=path[,mux=on|off]\n"
> +    "-chardev file,id=id,path=path[,mux=on|off][,append=on|off]\n"
>      "-chardev pipe,id=id,path=path[,mux=on|off]\n"
>  #ifdef _WIN32
>      "-chardev console,id=id[,mux=on|off]\n"
> @@ -2199,7 +2199,7 @@ console with the given dimensions.
>  Create a ring buffer with fixed size @option{size}.
>  @var{size} must be a power of two, and defaults to @code{64K}).
>  
> -@item -chardev file ,id=@var{id} ,path=@var{path}
> +@item -chardev file ,id=@var{id} ,path=@var{path} [,append=@var{on|off}]
>  
>  Log all traffic received from the guest to a file.
>  
> @@ -2207,6 +2207,9 @@ Log all traffic received from the guest to a file.
>  created if it does not already exist, and overwritten if it does. @option{path}
>  is required.
>  
> +@option{append} specifies that QEMU must truncate the file on open.
> +@option{append} is optional, default value is off.
> +
>  @item -chardev pipe ,id=@var{id} ,path=@var{path}
>  
>  Create a two-way connection to the guest. The behaviour differs slightly between

Assuming the commit msg is tweaked to remove mention of libvirt, then:

  Reviewed-by: Daniel P. Berrange <berrange@redhat.com>

Regards,
Daniel
Denis V. Lunev Dec. 22, 2015, 10:39 a.m. UTC | #2
On 12/22/2015 01:26 PM, Daniel P. Berrange wrote:
> On Tue, Dec 22, 2015 at 12:49:09PM +0300, Denis V. Lunev wrote:
>>      commit 31e38a22a0c5a25646f966f001e1f5513d5a186d
>>      Author: Olga Krishtal <okrishtal@virtuozzo.com>
>>      Date:   Fri Dec 4 09:42:04 2015 +0300
>>
>>          qemu-char: append opt to stop truncation of serial file
>>
>> has added the option to the runtime but does not added it to -help
>> output. This blocks libvirt from using it.
> You can remove this sentance about libvirt - we stopped parsing
> -help output a long time ago. We exclusively use QMP now.
>
>> Signed-off-by: Denis V. Lunev <den@openvz.org>
>> CC: Dmitry Mishin <dim@virtuozzo.com>
>> CC: Eric Blake <eblake@redhat.com>
>> CC: Markus Armbruster <armbru@redhat.com>
>> CC: Paolo Bonzini <pbonzini@redhat.com>
>> ---
>> Changes from v1:
>> - fixed default value to 'off'
>>
>>   qemu-options.hx | 7 +++++--
>>   1 file changed, 5 insertions(+), 2 deletions(-)
>>
>> diff --git a/qemu-options.hx b/qemu-options.hx
>> index 49afe6c..f706e4a 100644
>> --- a/qemu-options.hx
>> +++ b/qemu-options.hx
>> @@ -2044,7 +2044,7 @@ DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
>>       "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
>>       "         [,mux=on|off]\n"
>>       "-chardev ringbuf,id=id[,size=size]\n"
>> -    "-chardev file,id=id,path=path[,mux=on|off]\n"
>> +    "-chardev file,id=id,path=path[,mux=on|off][,append=on|off]\n"
>>       "-chardev pipe,id=id,path=path[,mux=on|off]\n"
>>   #ifdef _WIN32
>>       "-chardev console,id=id[,mux=on|off]\n"
>> @@ -2199,7 +2199,7 @@ console with the given dimensions.
>>   Create a ring buffer with fixed size @option{size}.
>>   @var{size} must be a power of two, and defaults to @code{64K}).
>>   
>> -@item -chardev file ,id=@var{id} ,path=@var{path}
>> +@item -chardev file ,id=@var{id} ,path=@var{path} [,append=@var{on|off}]
>>   
>>   Log all traffic received from the guest to a file.
>>   
>> @@ -2207,6 +2207,9 @@ Log all traffic received from the guest to a file.
>>   created if it does not already exist, and overwritten if it does. @option{path}
>>   is required.
>>   
>> +@option{append} specifies that QEMU must truncate the file on open.
>> +@option{append} is optional, default value is off.
>> +
>>   @item -chardev pipe ,id=@var{id} ,path=@var{path}
>>   
>>   Create a two-way connection to the guest. The behaviour differs slightly between
> Assuming the commit msg is tweaked to remove mention of libvirt, then:
>
>    Reviewed-by: Daniel P. Berrange <berrange@redhat.com>
>
> Regards,
> Daniel
No problem.

Thank you for your help to proceed with this in libvirt support of this
option :)

I'll resubmit this patch later after accumulating all feedback.

Den
Eric Blake Dec. 22, 2015, 3:53 p.m. UTC | #3
On 12/22/2015 02:49 AM, Denis V. Lunev wrote:
>     commit 31e38a22a0c5a25646f966f001e1f5513d5a186d
>     Author: Olga Krishtal <okrishtal@virtuozzo.com>
>     Date:   Fri Dec 4 09:42:04 2015 +0300
> 
>         qemu-char: append opt to stop truncation of serial file
> 
> has added the option to the runtime but does not added it to -help
> output. This blocks libvirt from using it.

In addition to Dan's comment about the dead sentence,


> +@option{append} specifies that QEMU must truncate the file on open.
> +@option{append} is optional, default value is off.

This is backwards.  It should read something more like:

@option{append} specifies that QEMU should append to the file. It
defaults to off, for truncating the file instead of appending.

Or maybe:

@option{append} controls whether QEMU truncates the file (default if
omitted, or if specified as off), or appends to the file (specified as on).

Check if there are other similar wordings to borrow from.
diff mbox

Patch

diff --git a/qemu-options.hx b/qemu-options.hx
index 49afe6c..f706e4a 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -2044,7 +2044,7 @@  DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
     "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
     "         [,mux=on|off]\n"
     "-chardev ringbuf,id=id[,size=size]\n"
-    "-chardev file,id=id,path=path[,mux=on|off]\n"
+    "-chardev file,id=id,path=path[,mux=on|off][,append=on|off]\n"
     "-chardev pipe,id=id,path=path[,mux=on|off]\n"
 #ifdef _WIN32
     "-chardev console,id=id[,mux=on|off]\n"
@@ -2199,7 +2199,7 @@  console with the given dimensions.
 Create a ring buffer with fixed size @option{size}.
 @var{size} must be a power of two, and defaults to @code{64K}).
 
-@item -chardev file ,id=@var{id} ,path=@var{path}
+@item -chardev file ,id=@var{id} ,path=@var{path} [,append=@var{on|off}]
 
 Log all traffic received from the guest to a file.
 
@@ -2207,6 +2207,9 @@  Log all traffic received from the guest to a file.
 created if it does not already exist, and overwritten if it does. @option{path}
 is required.
 
+@option{append} specifies that QEMU must truncate the file on open.
+@option{append} is optional, default value is off.
+
 @item -chardev pipe ,id=@var{id} ,path=@var{path}
 
 Create a two-way connection to the guest. The behaviour differs slightly between