Doc fixes around "current monitor" printing

[PATCH 3/3] qemu-print: Document qemu_fprintf(), qemu_vfprintf() failure

Posted by Markus Armbruster 3 weeks, 5 days ago

These functions fail when @stream is null and the current monitor
isn't HMP.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 util/qemu-print.c | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/util/qemu-print.c b/util/qemu-print.c
index 4a30cd1a8e..bbf8c1823e 100644
--- a/util/qemu-print.c
+++ b/util/qemu-print.c
@@ -45,6 +45,7 @@ int qemu_printf(const char *fmt, ...)
 /*
  * Print like vfprintf()
  * Print to @stream if non-null, else to current monitor.
+ * Beware: the latter fails unless we have one and it is HMP.
  */
 int qemu_vfprintf(FILE *stream, const char *fmt, va_list ap)
 {
@@ -57,6 +58,7 @@ int qemu_vfprintf(FILE *stream, const char *fmt, va_list ap)
 /*
  * Print like fprintf().
  * Print to @stream if non-null, else to current monitor.
+ * Beware: the latter fails unless we have one and it is HMP.
  */
 int qemu_fprintf(FILE *stream, const char *fmt, ...)
 {
-- 
2.52.0

Re: [PATCH 3/3] qemu-print: Document qemu_fprintf(), qemu_vfprintf() failure

Posted by Daniel P. Berrangé 3 weeks, 5 days ago

On Wed, Jan 14, 2026 at 01:47:13PM +0100, Markus Armbruster wrote:
> These functions fail when @stream is null and the current monitor
> isn't HMP.
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  util/qemu-print.c | 2 ++
>  1 file changed, 2 insertions(+)
> 
> diff --git a/util/qemu-print.c b/util/qemu-print.c
> index 4a30cd1a8e..bbf8c1823e 100644
> --- a/util/qemu-print.c
> +++ b/util/qemu-print.c
> @@ -45,6 +45,7 @@ int qemu_printf(const char *fmt, ...)
>  /*
>   * Print like vfprintf()
>   * Print to @stream if non-null, else to current monitor.
> + * Beware: the latter fails unless we have one and it is HMP.

This leaves me curious what 'fails' means. In this case no
output is printed and the func returns -1.

How about we rephrase to match the other method docs better

 * Print to current HMP monitor if we have one, else to @stream
   if non-null, else returns -1


>   */
>  int qemu_vfprintf(FILE *stream, const char *fmt, va_list ap)
>  {
> @@ -57,6 +58,7 @@ int qemu_vfprintf(FILE *stream, const char *fmt, va_list ap)
>  /*
>   * Print like fprintf().
>   * Print to @stream if non-null, else to current monitor.
> + * Beware: the latter fails unless we have one and it is HMP.
>   */
>  int qemu_fprintf(FILE *stream, const char *fmt, ...)
>  {
> -- 
> 2.52.0
> 

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH 3/3] qemu-print: Document qemu_fprintf(), qemu_vfprintf() failure

Posted by Daniel P. Berrangé 3 weeks, 5 days ago

On Wed, Jan 14, 2026 at 12:58:15PM +0000, Daniel P. Berrangé wrote:
> On Wed, Jan 14, 2026 at 01:47:13PM +0100, Markus Armbruster wrote:
> > These functions fail when @stream is null and the current monitor
> > isn't HMP.
> > 
> > Signed-off-by: Markus Armbruster <armbru@redhat.com>
> > ---
> >  util/qemu-print.c | 2 ++
> >  1 file changed, 2 insertions(+)
> > 
> > diff --git a/util/qemu-print.c b/util/qemu-print.c
> > index 4a30cd1a8e..bbf8c1823e 100644
> > --- a/util/qemu-print.c
> > +++ b/util/qemu-print.c
> > @@ -45,6 +45,7 @@ int qemu_printf(const char *fmt, ...)
> >  /*
> >   * Print like vfprintf()
> >   * Print to @stream if non-null, else to current monitor.
> > + * Beware: the latter fails unless we have one and it is HMP.
> 
> This leaves me curious what 'fails' means. In this case no
> output is printed and the func returns -1.
> 
> How about we rephrase to match the other method docs better
> 
>  * Print to current HMP monitor if we have one, else to @stream
>    if non-null, else returns -1

Opps, no, wrong semantics.

  * Print to @stream if non-null, else to current HMP monitor if
    we have one, else returns -1

> 
> 
> >   */
> >  int qemu_vfprintf(FILE *stream, const char *fmt, va_list ap)
> >  {
> > @@ -57,6 +58,7 @@ int qemu_vfprintf(FILE *stream, const char *fmt, va_list ap)
> >  /*
> >   * Print like fprintf().
> >   * Print to @stream if non-null, else to current monitor.
> > + * Beware: the latter fails unless we have one and it is HMP.
> >   */
> >  int qemu_fprintf(FILE *stream, const char *fmt, ...)
> >  {
> > -- 
> > 2.52.0
> > 
> 
> With regards,
> Daniel
> -- 
> |: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
> |: https://libvirt.org         -o-            https://fstop138.berrange.com :|
> |: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|
> 
> 

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH 3/3] qemu-print: Document qemu_fprintf(), qemu_vfprintf() failure

Posted by Markus Armbruster 3 weeks, 5 days ago

Daniel P. Berrangé <berrange@redhat.com> writes:

> On Wed, Jan 14, 2026 at 12:58:15PM +0000, Daniel P. Berrangé wrote:
>> On Wed, Jan 14, 2026 at 01:47:13PM +0100, Markus Armbruster wrote:
>> > These functions fail when @stream is null and the current monitor
>> > isn't HMP.
>> > 
>> > Signed-off-by: Markus Armbruster <armbru@redhat.com>
>> > ---
>> >  util/qemu-print.c | 2 ++
>> >  1 file changed, 2 insertions(+)
>> > 
>> > diff --git a/util/qemu-print.c b/util/qemu-print.c
>> > index 4a30cd1a8e..bbf8c1823e 100644
>> > --- a/util/qemu-print.c
>> > +++ b/util/qemu-print.c
>> > @@ -45,6 +45,7 @@ int qemu_printf(const char *fmt, ...)
>> >  /*
>> >   * Print like vfprintf()
>> >   * Print to @stream if non-null, else to current monitor.
>> > + * Beware: the latter fails unless we have one and it is HMP.
>> 
>> This leaves me curious what 'fails' means. In this case no
>> output is printed and the func returns -1.
>> 
>> How about we rephrase to match the other method docs better
>> 
>>  * Print to current HMP monitor if we have one, else to @stream
>>    if non-null, else returns -1
>
> Opps, no, wrong semantics.
>
>   * Print to @stream if non-null, else to current HMP monitor if
>     we have one, else returns -1

Yes, that's better.  What about:

    * Print to @stream if non-null, else to current HMP monitor if we
    * have one, else fail without printing anything.
    * Return number of characters printed on success, negative value on
    * error.

>> >   */
>> >  int qemu_vfprintf(FILE *stream, const char *fmt, va_list ap)
>> >  {
>> > @@ -57,6 +58,7 @@ int qemu_vfprintf(FILE *stream, const char *fmt, va_list ap)
>> >  /*
>> >   * Print like fprintf().
>> >   * Print to @stream if non-null, else to current monitor.
>> > + * Beware: the latter fails unless we have one and it is HMP.
>> >   */
>> >  int qemu_fprintf(FILE *stream, const char *fmt, ...)
>> >  {
>> > -- 
>> > 2.52.0
>> > 
>> 
>> With regards,
>> Daniel
>> -- 
>> |: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
>> |: https://libvirt.org         -o-            https://fstop138.berrange.com :|
>> |: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|
>> 
>> 
>
> With regards,
> Daniel

Re: [PATCH 3/3] qemu-print: Document qemu_fprintf(), qemu_vfprintf() failure

Posted by Daniel P. Berrangé 3 weeks, 5 days ago

On Wed, Jan 14, 2026 at 02:22:33PM +0100, Markus Armbruster wrote:
> Daniel P. Berrangé <berrange@redhat.com> writes:
> 
> > On Wed, Jan 14, 2026 at 12:58:15PM +0000, Daniel P. Berrangé wrote:
> >> On Wed, Jan 14, 2026 at 01:47:13PM +0100, Markus Armbruster wrote:
> >> > These functions fail when @stream is null and the current monitor
> >> > isn't HMP.
> >> > 
> >> > Signed-off-by: Markus Armbruster <armbru@redhat.com>
> >> > ---
> >> >  util/qemu-print.c | 2 ++
> >> >  1 file changed, 2 insertions(+)
> >> > 
> >> > diff --git a/util/qemu-print.c b/util/qemu-print.c
> >> > index 4a30cd1a8e..bbf8c1823e 100644
> >> > --- a/util/qemu-print.c
> >> > +++ b/util/qemu-print.c
> >> > @@ -45,6 +45,7 @@ int qemu_printf(const char *fmt, ...)
> >> >  /*
> >> >   * Print like vfprintf()
> >> >   * Print to @stream if non-null, else to current monitor.
> >> > + * Beware: the latter fails unless we have one and it is HMP.
> >> 
> >> This leaves me curious what 'fails' means. In this case no
> >> output is printed and the func returns -1.
> >> 
> >> How about we rephrase to match the other method docs better
> >> 
> >>  * Print to current HMP monitor if we have one, else to @stream
> >>    if non-null, else returns -1
> >
> > Opps, no, wrong semantics.
> >
> >   * Print to @stream if non-null, else to current HMP monitor if
> >     we have one, else returns -1
> 
> Yes, that's better.  What about:
> 
>     * Print to @stream if non-null, else to current HMP monitor if we
>     * have one, else fail without printing anything.
>     * Return number of characters printed on success, negative value on
>     * error.

Works for me, I'll incorporate it when adding these patches to my series.

> 
> >> >   */
> >> >  int qemu_vfprintf(FILE *stream, const char *fmt, va_list ap)
> >> >  {
> >> > @@ -57,6 +58,7 @@ int qemu_vfprintf(FILE *stream, const char *fmt, va_list ap)
> >> >  /*
> >> >   * Print like fprintf().
> >> >   * Print to @stream if non-null, else to current monitor.
> >> > + * Beware: the latter fails unless we have one and it is HMP.
> >> >   */
> >> >  int qemu_fprintf(FILE *stream, const char *fmt, ...)
> >> >  {
> >> > -- 
> >> > 2.52.0

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|