memory.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<refentry id="glib-Memory-Allocation">
<refmeta>
<refentrytitle>Memory Allocation</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Memory Allocation</refname><refpurpose>general memory-handling.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


#define     <link linkend="g-new">g_new</link>                           (struct_type, n_structs)
#define     <link linkend="g-new0">g_new0</link>                          (struct_type, n_structs)
#define     <link linkend="g-renew">g_renew</link>                         (struct_type, mem, n_structs)

<link linkend="gpointer">gpointer</link>    <link linkend="g-malloc">g_malloc</link>                        (<link linkend="gulong">gulong</link> n_bytes);
<link linkend="gpointer">gpointer</link>    <link linkend="g-malloc0">g_malloc0</link>                       (<link linkend="gulong">gulong</link> n_bytes);
<link linkend="gpointer">gpointer</link>    <link linkend="g-realloc">g_realloc</link>                       (<link linkend="gpointer">gpointer</link> mem,
                                             <link linkend="gulong">gulong</link> n_bytes);
<link linkend="gpointer">gpointer</link>    <link linkend="g-try-malloc">g_try_malloc</link>                    (<link linkend="gulong">gulong</link> n_bytes);
<link linkend="gpointer">gpointer</link>    <link linkend="g-try-realloc">g_try_realloc</link>                   (<link linkend="gpointer">gpointer</link> mem,
                                             <link linkend="gulong">gulong</link> n_bytes);

void        <link linkend="g-free">g_free</link>                          (<link linkend="gpointer">gpointer</link> mem);

#define     <link linkend="g-alloca">g_alloca</link>                        (size)
#define     <link linkend="g-newa">g_newa</link>                          (struct_type, n_structs)

#define     <link linkend="g-memmove">g_memmove</link>                       (d,s,n)
<link linkend="gpointer">gpointer</link>    <link linkend="g-memdup">g_memdup</link>                        (<link linkend="gconstpointer">gconstpointer</link> mem,
                                             <link linkend="guint">guint</link> byte_size);

struct      <link linkend="GMemVTable">GMemVTable</link>;
void        <link linkend="g-mem-set-vtable">g_mem_set_vtable</link>                (<link linkend="GMemVTable">GMemVTable</link> *vtable);
<link linkend="gboolean">gboolean</link>    <link linkend="g-mem-is-system-malloc">g_mem_is_system_malloc</link>          (void);

extern      GMemVTable	*<link linkend="glib-mem-profiler-table">glib_mem_profiler_table</link>;
void        <link linkend="g-mem-profile">g_mem_profile</link>                   (void);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
These functions provide support for allocating and freeing memory.
</para>
<note>
<para>
If any call to allocate memory fails, the application is terminated.
This also means that there is no need to check if the call succeeded.
</para>
</note>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="g-new">g_new()</title>
<programlisting>#define     g_new(struct_type, n_structs)</programlisting>
<para>
Allocates <parameter>n_structs</parameter> elements of type <parameter>struct_type</parameter>.
The returned pointer is cast to a pointer to the given type.
If <parameter>count</parameter> is 0 it returns <literal>NULL</literal>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>struct_type</parameter>&nbsp;:</entry>
<entry>the type of the elements to allocate.
</entry></row>
<row><entry align="right"><parameter>n_structs</parameter>&nbsp;:</entry>
<entry>the number of elements to allocate.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a pointer to the allocated memory, cast to a pointer to <parameter>struct_type</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-new0">g_new0()</title>
<programlisting>#define     g_new0(struct_type, n_structs)</programlisting>
<para>
Allocates <parameter>n_structs</parameter> elements of type <parameter>struct_type</parameter>, initialized to 0's.
The returned pointer is cast to a pointer to the given type.
If <parameter>count</parameter> is 0 it returns <literal>NULL</literal>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>struct_type</parameter>&nbsp;:</entry>
<entry>the type of the elements to allocate.
</entry></row>
<row><entry align="right"><parameter>n_structs</parameter>&nbsp;:</entry>
<entry>the number of elements to allocate.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a pointer to the allocated memory, cast to a pointer to <parameter>struct_type</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-renew">g_renew()</title>
<programlisting>#define     g_renew(struct_type, mem, n_structs)</programlisting>
<para>
Reallocates the memory pointed to by <parameter>mem</parameter>, so that it now has space for
<parameter>n_struct</parameter> elements of type <parameter>struct_type</parameter>. It returns the new address of 
the memory, which may have been moved.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>struct_type</parameter>&nbsp;:</entry>
<entry>the type of the elements to allocate.
</entry></row>
<row><entry align="right"><parameter>mem</parameter>&nbsp;:</entry>
<entry>the currently allocated memory.
</entry></row>
<row><entry align="right"><parameter>n_structs</parameter>&nbsp;:</entry>
<entry>the number of elements to allocate.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a pointer to the new allocated memory, cast to a pointer to <parameter>struct_type</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-malloc">g_malloc ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    g_malloc                        (<link linkend="gulong">gulong</link> n_bytes);</programlisting>
<para>
Allocates <parameter>n_bytes</parameter> bytes of memory.
If <parameter>n_bytes</parameter> is 0 it returns <literal>NULL</literal>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>n_bytes</parameter>&nbsp;:</entry>
<entry>the number of bytes to allocate.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a pointer to the allocated memory.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-malloc0">g_malloc0 ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    g_malloc0                       (<link linkend="gulong">gulong</link> n_bytes);</programlisting>
<para>
Allocates <parameter>n_bytes</parameter> bytes of memory, initialized to 0's.
If <parameter>n_bytes</parameter> is 0 it returns <literal>NULL</literal>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>n_bytes</parameter>&nbsp;:</entry>
<entry>the number of bytes to allocate.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a pointer to the allocated memory.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-realloc">g_realloc ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    g_realloc                       (<link linkend="gpointer">gpointer</link> mem,
                                             <link linkend="gulong">gulong</link> n_bytes);</programlisting>
<para>
Reallocates the memory pointed to by <parameter>mem</parameter>, so that it now has space for
<parameter>n_bytes</parameter> bytes of memory. It returns the new address of the memory, which may
have been moved. <parameter>mem</parameter> may be <literal>NULL</literal>, in which case it's considered to 
have zero-length. <parameter>n_bytes</parameter> may be 0, in which case <literal>NULL</literal> will be returned.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>mem</parameter>&nbsp;:</entry>
<entry>the memory to reallocate.
</entry></row>
<row><entry align="right"><parameter>n_bytes</parameter>&nbsp;:</entry>
<entry>new size of the memory in bytes.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new address of the allocated memory.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-try-malloc">g_try_malloc ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    g_try_malloc                    (<link linkend="gulong">gulong</link> n_bytes);</programlisting>
<para>
Attempts to allocate <parameter>n_bytes</parameter>, and returns <literal>NULL</literal> on failure. 
Contrast with <link linkend="g-malloc">g_malloc</link>(), which aborts the program on failure.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>n_bytes</parameter>&nbsp;:</entry>
<entry>number of bytes to allocate.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the allocated memory, or <literal>NULL</literal>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-try-realloc">g_try_realloc ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    g_try_realloc                   (<link linkend="gpointer">gpointer</link> mem,
                                             <link linkend="gulong">gulong</link> n_bytes);</programlisting>
<para>
Attempts to realloc <parameter>mem</parameter> to a new size, <parameter>n_bytes</parameter>, and returns <literal>NULL</literal>
on failure. Contrast with <link linkend="g-realloc">g_realloc</link>(), which aborts the program
on failure. If <parameter>mem</parameter> is <literal>NULL</literal>, behaves the same as <link linkend="g-try-malloc">g_try_malloc</link>().
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>mem</parameter>&nbsp;:</entry>
<entry>previously-allocated memory, or <literal>NULL</literal>.
</entry></row>
<row><entry align="right"><parameter>n_bytes</parameter>&nbsp;:</entry>
<entry>number of bytes to allocate.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the allocated memory, or <literal>NULL</literal>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-free">g_free ()</title>
<programlisting>void        g_free                          (<link linkend="gpointer">gpointer</link> mem);</programlisting>
<para>
Frees the memory pointed to by <parameter>mem</parameter>.
If <parameter>mem</parameter> is <literal>NULL</literal> it simply returns.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>mem</parameter>&nbsp;:</entry>
<entry>the memory to free.


</entry></row>
</tbody></tgroup></informaltable></refsect2>