</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### MACRO g_new ##### -->
<para>
Allocates @n_structs elements of type @struct_type.
The returned pointer is cast to a pointer to the given type.
-If @count is 0 it returns %NULL.
+If @n_structs is 0 it returns %NULL.
+</para>
+<para>
+Since the returned pointer is already casted to the right type,
+it is normally unnecessary to cast it explicitly, and doing
+so might hide memory allocation errors.
</para>
@struct_type: the type of the elements to allocate.
<para>
Allocates @n_structs elements of type @struct_type, initialized to 0's.
The returned pointer is cast to a pointer to the given type.
-If @count is 0 it returns %NULL.
+If @n_structs is 0 it returns %NULL.
+</para>
+<para>
+Since the returned pointer is already casted to the right type,
+it is normally unnecessary to cast it explicitly, and doing
+so might hide memory allocation errors.
</para>
@struct_type: the type of the elements to allocate.
<!-- ##### MACRO g_renew ##### -->
<para>
Reallocates the memory pointed to by @mem, so that it now has space for
-@n_struct elements of type @struct_type. It returns the new address of
+@n_structs elements of type @struct_type. It returns the new address of
the memory, which may have been moved.
</para>
@Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type.
+<!-- ##### MACRO g_try_new ##### -->
+<para>
+Attempts to allocate @n_structs elements of type @struct_type, and returns
+%NULL on failure. Contrast with g_new(), which aborts the program on failure.
+The returned pointer is cast to a pointer to the given type.
+If @n_structs is 0 it returns %NULL.
+</para>
+
+@struct_type: the type of the elements to allocate.
+@n_structs: the number of elements to allocate.
+@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
+@Since: 2.8
+
+
+<!-- ##### MACRO g_try_new0 ##### -->
+<para>
+Attempts to allocate @n_structs elements of type @struct_type, initialized
+to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts
+the program on failure.
+The returned pointer is cast to a pointer to the given type.
+If @n_counts is 0 it returns %NULL.
+</para>
+
+@struct_type: the type of the elements to allocate.
+@n_structs: the number of elements to allocate.
+@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
+@Since: 2.8
+
+
+<!-- ##### MACRO g_try_renew ##### -->
+<para>
+Attempts to reallocate the memory pointed to by @mem, so that it now has
+space for @n_structs elements of type @struct_type, and returns %NULL on
+failure. Contrast with g_renew(), which aborts the program on failure.
+It returns the new address of the memory, which may have been moved.
+</para>
+
+@struct_type: the type of the elements to allocate.
+@mem: the currently allocated memory.
+@n_structs: the number of elements to allocate.
+@Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type.
+@Since: 2.8
+
+
<!-- ##### FUNCTION g_malloc ##### -->
<para>
Allocates @n_bytes bytes of memory.
@Returns: the allocated memory, or %NULL.
+<!-- ##### FUNCTION g_try_malloc0 ##### -->
+<para>
+Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on
+failure. Contrast with g_malloc0(), which aborts the program on failure.
+</para>
+
+@n_bytes: number of bytes to allocate.
+@Returns: the allocated memory, or %NULL.
+@Since: 2.8
+
+
<!-- ##### FUNCTION g_try_realloc ##### -->
<para>
Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
<!-- ##### MACRO g_alloca ##### -->
<para>
Allocates @size bytes on the stack; these bytes will be freed when the current
-stack frame is cleaned up.
+stack frame is cleaned up. This macro essentially just wraps the
+<function>alloca()</function> function present on most UNIX variants.
+Thus it provides the same advantages and pitfalls as <function>alloca()</function>:
+<variablelist>
+ <varlistentry><term></term><listitem><para>
+ + <function>alloca()</function> is very fast, as on most systems it's implemented by just adjusting
+ the stack pointer register.
+ </para></listitem></varlistentry>
+ <varlistentry><term></term><listitem><para>
+ + It doesn't cause any memory fragmentation, within its scope, separate <function>alloca()</function>
+ blocks just build up and are released together at function end.
+ </para></listitem></varlistentry>
+ <varlistentry><term></term><listitem><para>
+ - Allocation sizes have to fit into the current stack frame. For instance in a
+ threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
+ so be sparse with <function>alloca()</function> uses.
+ </para></listitem></varlistentry>
+ <varlistentry><term></term><listitem><para>
+ - Allocation failure due to insufficient stack space is not indicated with a %NULL
+ return like e.g. with <function>malloc()</function>. Instead, most systems probably handle it the same
+ way as out of stack space situations from infinite function recursion, i.e.
+ with a segmentation fault.
+ </para></listitem></varlistentry>
+ <varlistentry><term></term><listitem><para>
+ - Special care has to be taken when mixing <function>alloca()</function> with GNU C variable sized arrays.
+ Stack space allocated with <function>alloca()</function> in the same scope as a variable sized array
+ will be freed together with the variable sized array upon exit of that scope, and
+ not upon exit of the enclosing function scope.
+ </para></listitem></varlistentry>
+</variablelist>
+
</para>
-@size: number of bytes to allocate.
+@size: number of bytes to allocate.
+@Returns: space for @size bytes, allocated on the stack
-<!-- ##### MACRO g_memmove ##### -->
+<!-- ##### MACRO g_newa ##### -->
<para>
-Copies a block of memory @n bytes long, from @s to @d.
-The source and destination areas may overlap.
+Wraps g_alloca() in a more typesafe manner.
</para>
+
+@struct_type: Type of memory chunks to be allocated
+@n_structs: Number of chunks to be allocated
+@Returns: Pointer to stack space for @n_structs chunks of type @struct_type
+
+
+<!-- ##### MACRO g_memmove ##### -->
<para>
-In order to use this function, you must include <filename>string.h</filename>
-yourself, because this macro will typically simply resolve
-to <function>memmove()</function> and GLib does not include <filename>string.h</filename> for you.
+
</para>
-@d: the destination address to copy the bytes to.
-@s: the source address to copy the bytes from.
-@n: the number of bytes to copy.
+@dest:
+@src:
+@len:
<!-- ##### FUNCTION g_memdup ##### -->
@mem: the memory to copy.
@byte_size: the number of bytes to copy.
-@Returns: a pointer to the newly allocated copy of the memory, or %NULL if @mem
+@Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
is %NULL.
<!-- ##### FUNCTION g_mem_set_vtable ##### -->
<para>
Sets the #GMemVTable to use for memory allocation. You can use this to provide
-custom memory allocation routines. THIS FUNCTION MUST BE CALLED BEFORE USING ANY
-OTHER GLIB FUNCTIONS. The @vtable only needs to provide <function>malloc()</function>, <function>realloc()</function>, and <function>free()</function>
+custom memory allocation routines. <emphasis>This function must be called before using any other GLib functions.</emphasis> The @vtable only needs to provide <function>malloc()</function>, <function>realloc()</function>, and <function>free()</function>
functions; GLib can provide default implementations of the others. The <function>malloc()</function>
and <function>realloc()</function> implementations should return %NULL on failure, GLib will handle
error-checking for you. @vtable is copied, so need not persist after this
</para>
+
projects / platform / upstream / glib.git / blobdiff