Re: [PATCH] getline.3: wfix.

enh
2022-08-02T21:17:41Z

ack. i've fixed all the other instances of `.I "foo"` in that file too...

Date: Fri, 29 Jul 2022 13:13:10 -0700
Subject: [PATCH] getline.3: wfix.

Clarify in the RETURN VALUE section that it's necessary to free the
buffer, since at least one person missed this up at the start of the
DESCRIPTION.

Signed-off-by: Elliott Hughes <enh@google.com>
---
man3/getline.3 | 21 +++++++++++++--------
1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/man3/getline.3 b/man3/getline.3
index 8b7357825..cb9e5b049 100644
--- a/man3/getline.3
+++ b/man3/getline.3
@@ -36,12 +36,12 @@ Feature Test Macro Requirements for glibc (see
.BR getline ()
reads an entire line from \fIstream\fP,
storing the address of the buffer containing the text into
-.IR "*lineptr" .
+.IR *lineptr .
The buffer is null-terminated and includes the newline character, if
one was found.
.PP
If
-.I "*lineptr"
+.I *lineptr
is set to NULL before the call, then
.BR getline ()
will allocate a buffer for storing the line.
@@ -52,26 +52,26 @@ failed.
.PP
Alternatively, before calling
.BR getline (),
-.I "*lineptr"
+.I *lineptr
can contain a pointer to a
.BR malloc (3)\-allocated
buffer
-.I "*n"
+.I *n
bytes in size.
If the buffer is not large enough to hold the line,
.BR getline ()
resizes it with
.BR realloc (3),
updating
-.I "*lineptr"
+.I *lineptr
and
-.I "*n"
+.I *n
as necessary.
.PP
In either case, on a successful call,
-.I "*lineptr"
+.I *lineptr
and
-.I "*n"
+.I *n
will be updated to reflect the buffer address and allocated size respectively.
.PP
.BR getdelim ()
@@ -99,6 +99,11 @@ condition).
In the event of a failure,
.I errno
is set to indicate the error.
+.PP
+If
+.I *lineptr
+was set to NULL before the call, then the buffer should be freed by the
+user program even on failure.
.SH ERRORS
.TP
.B EINVAL
--
2.37.1.455.g008518b4e5-goog

On Mon, Aug 1, 2022 at 5:54 AM Alejandro Colomar <alx.manpages@gmail.com> wrote:
>
> Hi enh,
>
> On 7/29/22 22:22, enh wrote:
> > Clarify in the RETURN VALUE section that it's necessary to free the
> > buffer, since at least one person missed this up at the start of the
> > DESCRIPTION.
> >
> > Signed-off-by: Elliott Hughes <enh@google.com>
> > ---
> > man3/getline.3 | 4 ++++
> > 1 file changed, 4 insertions(+)
> >
> > diff --git a/man3/getline.3 b/man3/getline.3
> > index 8b7357825..bad30956c 100644
> > --- a/man3/getline.3
> > +++ b/man3/getline.3
> > @@ -99,6 +99,10 @@ condition).
> > In the event of a failure,
> > .I errno
> > is set to indicate the error.
>
> .PP
>
> Since the added text has nothing to do with the previous, let's separate
> them into separate paragraphs.
>
> > +If
> > +.I "*lineptr"
>
> As Branden said, please remove the unnecessary quotes.
>
> > +was set to NULL before the call, then the buffer should be freed by the
> > +user program even on failure.
> > .SH ERRORS
> > .TP
> > .B EINVAL
>
> Cheers,
>
> Alex
>
> --
> Alejandro Colomar
> <http://www.alejandro-colomar.es/>