Add PGTYPESchar_free() to avoid cross-module problems on Windows.

On Windows, it is sometimes important for corresponding malloc() and
free() calls to be made from the same DLL, since some build options can
result in multiple allocators being active at the same time.  For that
reason we already provided PQfreemem().  This commit adds a similar
function for freeing string results allocated by the pgtypes library.

Author: Takayuki Tsunakawa
Reviewed-by: Kyotaro Horiguchi
Discussion: https://postgr.es/m/0A3221C70F24FB45833433255569204D1F8AD5D6%40G01JPEXMBYT05

1 files changed, 20 insertions, 4 deletions

diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml
index 8379f186993..a83a13b9a96 100644
--- a/doc/src/sgml/ecpg.sgml
+++ b/doc/src/sgml/ecpg.sgml
@@ -1919,11 +1919,23 @@ EXEC SQL SELECT started, duration INTO :ts1, :iv1 FROM datetbl WHERE d=:date1;
 PGTYPEStimestamp_add_interval(&ts1, &iv1, &tsout);
 out = PGTYPEStimestamp_to_asc(&tsout);
 printf("Started + duration: %s\n", out);
-free(out);
+PGTYPESchar_free(out);
 ]]>
 </programlisting>
   </para>
 
+  <sect2 id="ecpg-pgtypes-cstrings">
+   <title>Character Strings</title>
+   <para>
+   Some functions such as <function>PGTYPESnumeric_to_asc</function> return
+   a pointer to a freshly allocated character string. These results should be
+   freed with <function>PGTYPESchar_free</function> instead of
+   <function>free</function>. (This is important only on Windows, where
+   memory allocation and release sometimes need to be done by the same
+   library.)
+   </para>
+  </sect2>
+
   <sect2 id="ecpg-pgtypes-numeric">
    <title>The numeric Type</title>
    <para>
@@ -1997,6 +2009,7 @@ char *PGTYPESnumeric_to_asc(numeric *num, int dscale);
 </synopsis>
        The numeric value will be printed with <literal>dscale</literal> decimal
        digits, with rounding applied if necessary.
+       The result must be freed with <function>PGTYPESchar_free()</function>.
       </para>
      </listitem>
     </varlistentry>
@@ -2384,9 +2397,10 @@ date PGTYPESdate_from_asc(char *str, char **endptr);
 <synopsis>
 char *PGTYPESdate_to_asc(date dDate);
 </synopsis>
-        The function receives the date <literal>dDate</> as its only parameter.
-        It will output the date in the form <literal>1999-01-18</>, i.e., in the
-        <literal>YYYY-MM-DD</> format.
+        The function receives the date <literal>dDate</literal> as its only parameter.
+        It will output the date in the form <literal>1999-01-18</literal>, i.e., in the
+        <literal>YYYY-MM-DD</literal> format.
+        The result must be freed with <function>PGTYPESchar_free()</function>.
        </para>
       </listitem>
      </varlistentry>
@@ -2809,6 +2823,7 @@ char *PGTYPEStimestamp_to_asc(timestamp tstamp);
         The function receives the timestamp <literal>tstamp</> as
         its only argument and returns an allocated string that contains the
         textual representation of the timestamp.
+        The result must be freed with <function>PGTYPESchar_free()</function>.
        </para>
       </listitem>
      </varlistentry>
@@ -3317,6 +3332,7 @@ char *PGTYPESinterval_to_asc(interval *span);
         The function converts the interval variable that <literal>span</>
         points to into a C char*. The output looks like this example:
         <literal>@ 1 day 12 hours 59 mins 10 secs</literal>.
+        The result must be freed with <function>PGTYPESchar_free()</function>.
        </para>
       </listitem>
      </varlistentry>