[Bug manual/1997] New: opern_memstream() buffer should be freed

[Bug manual/1997] New: opern_memstream() buffer should be freed

[michael dot kerrisk at gmx dot net]

The info page for open_memstream() should advise that the caller 
needs to free() the buffer.

-- 
           Summary: opern_memstream() buffer should be freed
           Product: glibc
           Version: 2.3.5
            Status: NEW
          Severity: normal
          Priority: P2
         Component: manual
        AssignedTo: roland at gnu dot org
        ReportedBy: michael dot kerrisk at gmx dot net
                CC: glibc-bugs at sources dot redhat dot com


http://sourceware.org/bugzilla/show_bug.cgi?id=1997

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug manual/1997] opern_memstream() buffer should be freed

[decimal at us dot ibm dot com]

------- Additional Comments From decimal at us dot ibm dot com  2005-12-12 19:52 -------
I took a look in the linux man pages and in the glibc manual and I found that
while the man page for strdup(3) does say

       The  strdup()  function  returns  a  pointer to a new string which is a
       duplicate of the string s.  Memory for the new string is obtained  with
       malloc(3), and can be freed with free(3).

the glibc manual info entry for strdup() says

This function copies the null-terminated string s into a newly allocated string.
The string is allocated using malloc; see Unconstrained Allocation. If malloc
cannot allocate space for the new string, strdup returns a null pointer.
Otherwise it returns a pointer to the new string.

The section on Unconstrained Allocation includes a section "Freeing after
Malloc" which discusses free().

The current section in the glibc manual on open_memstream() says

This function opens a stream for writing to a buffer. The buffer is allocated
dynamically (as with malloc; see Unconstrained Allocation) and grown as necessary.

So is it really necessary to explicitly mention free() next to every function
which uses malloc()? I'm asking to see if anyone else has a strong opinion.

-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=1997

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug manual/1997] opern_memstream() buffer should be freed

[michael dot kerrisk at gmx dot net]

------- Additional Comments From michael dot kerrisk at gmx dot net  2005-12-13 09:05 -------
Subject: Re:  opern_memstream() buffer should be freed

> Von: "decimal at us dot ibm dot com" <sourceware-bugzilla@sourceware.org>

> I took a look in the linux man pages and in the glibc manual and I found
> that while the man page for strdup(3) does say
> 
>   The  strdup()  function  returns  a  pointer to a new string which is a
>   duplicate of the string s.  Memory for the new string is obtained with
>   malloc(3), and can be freed with free(3).
> 
> the glibc manual info entry for strdup() says
> 
> This function copies the null-terminated string s into a newly allocated
> string.
> The string is allocated using malloc; see Unconstrained Allocation. If
> malloc
> cannot allocate space for the new string, strdup returns a null pointer.
> Otherwise it returns a pointer to the new string.
> 
> The section on Unconstrained Allocation includes a section "Freeing after
> Malloc" which discusses free().
> 
> The current section in the glibc manual on open_memstream() says
> 
> This function opens a stream for writing to a buffer. The buffer is
> allocated
> dynamically (as with malloc; see Unconstrained Allocation) and grown as
> necessary.
> 
> So is it really necessary to explicitly mention free() next to every
> function
> which uses malloc()? I'm asking to see if anyone else has a strong
> opinion.

Being the Linux manual page maintainer (but I didn't write that 
strdup(2)) text, I'm inclined to the view that it is useful
to mention free() when describing these interfaces. It is just 
too easy to create memory leaks in C: giving people more direct 
hints (instead of suggesting a hyperlink in the doc, in which it
only becomes clear that free() is needed after quite a bit of 
reading) alerts people to the issue.  

There is a second reason for doing this in the case of 
open_memstream(): the interface is non-standard.  I can determine
from any number of places (my own knowledge, the SUSv3 spec, 
manual pages on various systems) that glibc's strdup() must be 
followed with a free().  However, those sources of information
are not available for open_memstream().

I realise there are differences on documentation philosophy for 
"info" and the manual pages, but I do think an explicit mention of 
free() could be valuable here (and perhaps in a few other places).

Cheers,

Michael



-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=1997

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug manual/1997] opern_memstream() buffer should be freed

[decimal at us dot ibm dot com]

------- Additional Comments From decimal at us dot ibm dot com  2005-12-13 19:29 -------
Thanks for the feedback Michael. I too realize there are different philosophies.
I'm too new in glibc land to know what the philosphy is here for the manual
which is why I asked; so I could learn. I'll also submit a patch resolving the
issue and see how that goes.

-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=1997

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug manual/1997] opern_memstream() buffer should be freed

[decimal at us dot ibm dot com]

------- Additional Comments From decimal at us dot ibm dot com  2005-12-13 22:06 -------
Created an attachment (id=802)
 --> (http://sourceware.org/bugzilla/attachment.cgi?id=802&action=view)
Explicitly document that buffer allocated must be freed.


-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=1997

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug manual/1997] opern_memstream() buffer should be freed

[michael dot kerrisk at gmx dot net]

------- Additional Comments From michael dot kerrisk at gmx dot net  2005-12-13 22:40 -------
Subject: Re:  opern_memstream() buffer should be freed

> 
> ------- Additional Comments From decimal at us dot ibm dot com  2005-12-13
> 22:06 ------- Created an attachment (id=802)
 --> (http://sourceware.org/bugzilla/attachment.cgi?id=802&action=view)
>  --> (http://sourceware.org/bugzilla/attachment.cgi?id=802&action=view)
> Explicitly document that buffer allocated must be freed.

Thanks for proposing this patch.

There is a small typo in the patch: s/functions/function/

Cheers,

Michael


-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=1997

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug manual/1997] opern_memstream() buffer should be freed

[decimal at us dot ibm dot com]

------- Additional Comments From decimal at us dot ibm dot com  2005-12-13 22:47 -------
ah yes, back to grammar school for me - I'll fix tomorrow and submit to the
mailing list

-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=1997

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug manual/1997] opern_memstream() buffer should be freed

[decimal at us dot ibm dot com]

------- Additional Comments From decimal at us dot ibm dot com  2005-12-14 21:30 -------
Created an attachment (id=803)
 --> (http://sourceware.org/bugzilla/attachment.cgi?id=803&action=view)
Explicitly document that buffer allocated must be freed.

Submitted to libc-alpha.

-- 
           What    |Removed                     |Added
----------------------------------------------------------------------------
 Attachment #802 is|0                           |1
           obsolete|                            |


http://sourceware.org/bugzilla/show_bug.cgi?id=1997

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug manual/1997] open_memstream() buffer should be freed

[decimal at us dot ibm dot com]

-- 
           What    |Removed                     |Added
----------------------------------------------------------------------------
            Summary|opern_memstream() buffer    |open_memstream() buffer
                   |should be freed             |should be freed


http://sourceware.org/bugzilla/show_bug.cgi?id=1997

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug manual/1997] open_memstream() buffer should be freed

[cvs-commit at gcc dot gnu dot org]

------- Additional Comments From cvs-commit at gcc dot gnu dot org  2005-12-15 22:30 -------
Subject: Bug 1997

CVSROOT:	/cvs/glibc
Module name:	libc
Changes by:	roland@sources.redhat.com	2005-12-15 22:30:34

Modified files:
	manual         : stdio.texi 

Log message:
	2005-12-15  Roland McGrath  <roland@redhat.com>
	
	[BZ #1997]
	* manual/stdio.texi (String Streams): For open_memstream, elaborate a
	little on malloc reference.

Patches:
http://sources.redhat.com/cgi-bin/cvsweb.cgi/libc/manual/stdio.texi.diff?cvsroot=glibc&r1=1.134&r2=1.135



-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=1997

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

[Bug manual/1997] open_memstream() buffer should be freed

[jessw at netwood dot net]

------- Additional Comments From jessw at netwood dot net  2006-11-13 05:15 -------
It appears that this has been fixed (the last comment is a checkin; closing as
FIXED.)

-- 
           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
         Resolution|                            |FIXED


http://sourceware.org/bugzilla/show_bug.cgi?id=1997

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.