</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
<!-- ##### MACRO g_new ##### -->
<para>
-Allocates @count elements of type @type.
+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>
-@type: the type of the elements to allocate.
-@count: the number of elements to allocate.
-@Returns: a pointer to the allocated memory, cast to a pointer to @type.
+@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.
<!-- ##### MACRO g_new0 ##### -->
<para>
-Allocates @count elements of type @type, initialized to 0's.
+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>
-@type: the type of the elements to allocate.
-@count: the number of elements to allocate.
-@Returns: a pointer to the allocated memory, cast to a pointer to @type.
+@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.
<!-- ##### MACRO g_renew ##### -->
<para>
Reallocates the memory pointed to by @mem, so that it now has space for
-@count elements of type @type. It returns the new address of the memory,
-which may have been moved.
+@n_structs elements of type @struct_type. It returns the new address of
+the memory, which may have been moved.
</para>
-@type: the type of the elements to allocate.
+@struct_type: the type of the elements to allocate.
@mem: the currently allocated memory.
-@count: the number of elements to allocate.
-@Returns: a pointer to the new allocated memory, cast to a pointer to @type.
+@n_structs: the number of elements to allocate.
+@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 @size bytes of memory.
-If @size is 0 it returns NULL.
+Allocates @n_bytes bytes of memory.
+If @n_bytes is 0 it returns %NULL.
</para>
-@size: the number of bytes to allocate.
+@n_bytes: the number of bytes to allocate.
@Returns: a pointer to the allocated memory.
<!-- ##### FUNCTION g_malloc0 ##### -->
<para>
-Allocates @size bytes of memory, initialized to 0's.
-If @size is 0 it returns NULL.
+Allocates @n_bytes bytes of memory, initialized to 0's.
+If @n_bytes is 0 it returns %NULL.
</para>
-@size: the number of bytes to allocate.
+@n_bytes: the number of bytes to allocate.
@Returns: a pointer to the allocated memory.
<!-- ##### FUNCTION g_realloc ##### -->
<para>
Reallocates the memory pointed to by @mem, so that it now has space for
-@size bytes of memory. It returns the new address of the memory, which may
-have been moved.
+@n_bytes bytes of memory. It returns the new address of the memory, which may
+have been moved. @mem may be %NULL, in which case it's considered to
+have zero-length. @n_bytes may be 0, in which case %NULL will be returned.
</para>
@mem: the memory to reallocate.
-@size: the new size of the allocated memory, in bytes.
+@n_bytes: new size of the memory in bytes.
@Returns: the new address of the allocated memory.
+<!-- ##### FUNCTION g_try_malloc ##### -->
+<para>
+Attempts to allocate @n_bytes, and returns %NULL on failure.
+Contrast with g_malloc(), which aborts the program on failure.
+</para>
+
+@n_bytes: number of bytes to allocate.
+@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
+on failure. Contrast with g_realloc(), which aborts the program
+on failure. If @mem is %NULL, behaves the same as g_try_malloc().
+</para>
+
+@mem: previously-allocated memory, or %NULL.
+@n_bytes: number of bytes to allocate.
+@Returns: the allocated memory, or %NULL.
+
+
<!-- ##### FUNCTION g_free ##### -->
<para>
Frees the memory pointed to by @mem.
-If @mem is NULL it simply returns.
+If @mem is %NULL it simply returns.
</para>
@mem: the memory to free.
-<!-- ##### MACRO g_memmove ##### -->
+<!-- ##### MACRO g_alloca ##### -->
<para>
-Copies a block of memory @n bytes long, from @s to @d.
-The source and destination areas may overlap.
+Allocates @size bytes on the stack; these bytes will be freed when the current
+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>
-<note>
+
+@size: number of bytes to allocate.
+@Returns: space for @size bytes, allocated on the stack
+
+
+<!-- ##### MACRO g_newa ##### -->
<para>
-On architectures where memmove() is not available, this function is implemented
-using bcopy(), which may not be able to handle overlapping areas.
+Wraps g_alloca() in a more typesafe manner.
</para>
-</note>
-@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.
+@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>
+
+</para>
+
+@dest:
+@src:
+@len:
<!-- ##### FUNCTION g_memdup ##### -->
<para>
Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
-from @mem. If @mem is NULL it returns NULL.
+from @mem. If @mem is %NULL it returns %NULL.
</para>
@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
-is NULL.
+@Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
+is %NULL.
+
+
+<!-- ##### STRUCT GMemVTable ##### -->
+<para>
+A set of functions used to perform memory allocation. The same #GMemVTable must
+be used for all allocations in the same program; a call to g_mem_set_vtable(),
+if it exists, should be prior to any use of GLib.
+</para>
+
+@malloc: function to use for allocating memory.
+@realloc: function to use for reallocating memory.
+@free: function to use to free memory.
+@calloc: function to use for allocating zero-filled memory.
+@try_malloc: function to use for allocating memory without a default error handler.
+@try_realloc: function to use for reallocating memory without a default error handler.
+
+<!-- ##### FUNCTION g_mem_set_vtable ##### -->
+<para>
+Sets the #GMemVTable to use for memory allocation. You can use this to provide
+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
+function has been called.
+</para>
+
+@vtable: table of memory allocation routines.
+
+
+<!-- ##### FUNCTION g_mem_is_system_malloc ##### -->
+<para>
+
+</para>
+
+@Returns:
+
+
+<!-- ##### VARIABLE glib_mem_profiler_table ##### -->
+<para>
+A #GMemVTable containing profiling variants of the memory
+allocation functions. Use them together with g_mem_profile()
+in order to get information about the memory allocation pattern
+of your program.
+</para>
<!-- ##### FUNCTION g_mem_profile ##### -->
<para>
Outputs a summary of memory usage.
-To use this function you must configure glib with the flag
-'--enable-mem-profile=yes' before compiling.
</para>
<para>
It outputs the frequency of allocations of different sizes,
and the difference between the previous two values, i.e. the number of bytes
still in use.
</para>
-
-
-
-<!-- ##### FUNCTION g_mem_check ##### -->
<para>
-Checks if the given memory has already been freed. If it has it outputs
-a warning message.
-To use this function you must configure glib with the flag
-'--enable-mem-check=yes' before compiling.
+Note that this function will not output anything unless you have
+previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
</para>
-@mem: the memory to check.
projects / platform / upstream / glib.git / blobdiff