Subject: Freeing resources and internals.txt

From: Frans Meijer <[email-masked]>
Date: Thu, 14 Oct 2004 23:44:31 +0200 (CEST)

It is not entirely clear to me if resources allocated and returned by
library functions such as mail_fetch_structure should be freed using the
mail_free* functions, or that the c-client libs take care of those
(attached to mail_close perhaps)?

The documentation in docs/internal.txt concerning the structures used
seems 'out of sync' with the actual declarations of structures in
mail.h. Or should I be using other documentation?

-- 
------------------------------------------------------------------
 For information about this mailing list, and its archives, see: 
 http://www.washington.edu/imap/c-client-list.html
------------------------------------------------------------------

---

From: Mark Crispin <[email-masked]>
Date: Thu, 14 Oct 2004 15:17:15 -0700 (Pacific Daylight Time)

> (attached to mail_close perhaps)?

No, you do not (MUST NOT) free any resource returned by any mail_?????() 
functions.  These resources are cached on the stream and are freed when 
the stream closes.

You are, however, required to free resources that you created via:
 	fs_get()
 	cpystr(), cpytxt(), textcpy(), textcpystring(), textcpyoffstring()
 	rfc822_base64(), rfc822_binary(), rfc822_qprint(), rfc822_8bit()
 	utf8_text(), utf8_cstext(), utf8_cstocstext(), utf8_mime2text()

Note that in the case of the utf8_????() functions, you must check to see 
if the returned value is the same as the source, since these will not 
create a new copy if no conversions need to be done and instead will just 
return the argument.

-- Mark --

http://staff.washington.edu/mrc
Science does not emerge from voting, party politics, or public debate.
Si vis pacem, para bellum.

---

From: Frans Meijer <[email-masked]>
Date: Sun, 17 Oct 2004 00:25:12 +0200 (CEST)

> functions.  These resources are cached on the stream and are freed when

Ok. Thanks for clearing that up.

> create a new copy if no conversions need to be done and instead will just

Thanks for the warning. That could be tricky if you feed it something
that is supposed to be freed by the library.