The info page for open_memstream() should advise that the caller needs to free() the buffer.
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.
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
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.
Created attachment 802 [details] Explicitly document that buffer allocated must be freed.
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) > 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
ah yes, back to grammar school for me - I'll fix tomorrow and submit to the mailing list
Created attachment 803 [details] Explicitly document that buffer allocated must be freed. Submitted to libc-alpha.
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
It appears that this has been fixed (the last comment is a checkin; closing as FIXED.)