Re: [XEN PATCH v2 3/3] libxl: Update the documentation of libxl_xen_console_read_line()

[Javi Merino <javi.merino@xxxxxxxxx>]

On Tue, Aug 27, 2024 at 03:26:09PM GMT, Anthony PERARD wrote:
> On Fri, Aug 23, 2024 at 06:05:05PM +0100, Javi Merino wrote:
> > Despite its name, libxl_xen_console_read_line() does not read a line,
> > it fills the buffer with as many characters as fit.  Update the
> > documentation to reflect the real behaviour of the function.  Rename
> > line_r to avoid confusion since it is a pointer to an array of
> > characters.
> > 
> > Signed-off-by: Javi Merino <javi.merino@xxxxxxxxx>
> > ---
> >  tools/libs/light/libxl_console.c | 22 ++++++++++++----------
> >  1 file changed, 12 insertions(+), 10 deletions(-)
> > 
> > diff --git a/tools/libs/light/libxl_console.c 
> > b/tools/libs/light/libxl_console.c
> > index f42f6a51ee6f..652897e4ef6d 100644
> > --- a/tools/libs/light/libxl_console.c
> > +++ b/tools/libs/light/libxl_console.c
> > @@ -789,17 +789,19 @@ libxl_xen_console_reader *
> >      return cr;
> >  }
> >  
> > -/* return values:                                          *line_r
> > - *   1          success, whole line obtained from buffer    non-0
> > - *   0          no more lines available right now           0
> > - *   negative   error code ERROR_*                          0
> > - * On success *line_r is updated to point to a nul-terminated
> > +/* Copy part of the console ring into a buffer
> > + *
> > + * Return values:
> > + *   1: Success, the buffer obtained from the console ring an
> > + *   0: No more lines available right now
> > + *   -ERROR_* on error
> > + *
> > + * On success, *line_r is updated to point to a nul-terminated
> >   * string which is valid until the next call on the same console
> > - * reader.  The libxl caller may overwrite parts of the string
> > - * if it wishes. */
> > + * reader. */
> >  int libxl_xen_console_read_line(libxl_ctx *ctx,
> >                                  libxl_xen_console_reader *cr,
> > -                                char **line_r)
> > +                                char **buff)
> 
> You may want to update "tools/include/libxl.h" as well.

Sure, I will change this in "tools/include/libxl.h".

> I don't know why
> this comments is here instead of in the public header. At least there's
> some documentation I guess.

Cheers,
Javi