1<!-- ##### SECTION Title ##### --> 2Memory Allocation 3 4<!-- ##### SECTION Short_Description ##### --> 5general memory-handling 6 7<!-- ##### SECTION Long_Description ##### --> 8<para> 9These functions provide support for allocating and freeing memory. 10</para> 11 12<note> 13<para> 14If any call to allocate memory fails, the application is terminated. 15This also means that there is no need to check if the call succeeded. 16</para> 17</note> 18 19<note> 20<para> 21It's important to match g_malloc() with g_free(), plain malloc() with free(), 22and (if you're using C++) new with delete and new[] with delete[]. Otherwise 23bad things can happen, since these allocators may use different memory 24pools (and new/delete call constructors and destructors). See also 25g_mem_set_vtable(). 26</para> 27</note> 28 29<!-- ##### SECTION See_Also ##### --> 30<para> 31 32</para> 33 34<!-- ##### SECTION Stability_Level ##### --> 35 36 37<!-- ##### MACRO g_new ##### --> 38<para> 39Allocates @n_structs elements of type @struct_type. 40The returned pointer is cast to a pointer to the given type. 41If @n_structs is 0 it returns %NULL. 42</para> 43<para> 44Since the returned pointer is already casted to the right type, 45it is normally unnecessary to cast it explicitly, and doing 46so might hide memory allocation errors. 47</para> 48 49@struct_type: the type of the elements to allocate 50@n_structs: the number of elements to allocate 51@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type 52 53 54<!-- ##### MACRO g_new0 ##### --> 55<para> 56Allocates @n_structs elements of type @struct_type, initialized to 0's. 57The returned pointer is cast to a pointer to the given type. 58If @n_structs is 0 it returns %NULL. 59</para> 60<para> 61Since the returned pointer is already casted to the right type, 62it is normally unnecessary to cast it explicitly, and doing 63so might hide memory allocation errors. 64</para> 65 66@struct_type: the type of the elements to allocate. 67@n_structs: the number of elements to allocate. 68@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type. 69 70 71<!-- ##### MACRO g_renew ##### --> 72<para> 73Reallocates the memory pointed to by @mem, so that it now has space for 74@n_structs elements of type @struct_type. It returns the new address of 75the memory, which may have been moved. 76</para> 77 78@struct_type: the type of the elements to allocate 79@mem: the currently allocated memory 80@n_structs: the number of elements to allocate 81@Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type 82 83 84<!-- ##### MACRO g_try_new ##### --> 85<para> 86Attempts to allocate @n_structs elements of type @struct_type, and returns 87%NULL on failure. Contrast with g_new(), which aborts the program on failure. 88The returned pointer is cast to a pointer to the given type. 89If @n_structs is 0 it returns %NULL. 90</para> 91 92@struct_type: the type of the elements to allocate 93@n_structs: the number of elements to allocate 94@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type 95@Since: 2.8 96 97 98<!-- ##### MACRO g_try_new0 ##### --> 99<para> 100Attempts to allocate @n_structs elements of type @struct_type, initialized 101to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts 102the program on failure. 103The returned pointer is cast to a pointer to the given type. 104The function returns %NULL when @n_structs is 0. 105</para> 106 107@struct_type: the type of the elements to allocate 108@n_structs: the number of elements to allocate 109@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type 110@Since: 2.8 111 112 113<!-- ##### MACRO g_try_renew ##### --> 114<para> 115Attempts to reallocate the memory pointed to by @mem, so that it now has 116space for @n_structs elements of type @struct_type, and returns %NULL on 117failure. Contrast with g_renew(), which aborts the program on failure. 118It returns the new address of the memory, which may have been moved. 119</para> 120 121@struct_type: the type of the elements to allocate 122@mem: the currently allocated memory 123@n_structs: the number of elements to allocate 124@Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type 125@Since: 2.8 126 127 128<!-- ##### FUNCTION g_malloc ##### --> 129<para> 130Allocates @n_bytes bytes of memory. 131If @n_bytes is 0 it returns %NULL. 132</para> 133 134@n_bytes: the number of bytes to allocate 135@Returns: a pointer to the allocated memory 136 137 138<!-- ##### FUNCTION g_malloc0 ##### --> 139<para> 140Allocates @n_bytes bytes of memory, initialized to 0's. 141If @n_bytes is 0 it returns %NULL. 142</para> 143 144@n_bytes: the number of bytes to allocate 145@Returns: a pointer to the allocated memory 146 147 148<!-- ##### FUNCTION g_realloc ##### --> 149<para> 150Reallocates the memory pointed to by @mem, so that it now has space for 151@n_bytes bytes of memory. It returns the new address of the memory, which may 152have been moved. @mem may be %NULL, in which case it's considered to 153have zero-length. @n_bytes may be 0, in which case %NULL will be returned 154and @mem will be freed unless it is %NULL. 155</para> 156 157@mem: the memory to reallocate 158@n_bytes: new size of the memory in bytes 159@Returns: the new address of the allocated memory 160 161 162<!-- ##### FUNCTION g_try_malloc ##### --> 163<para> 164Attempts to allocate @n_bytes, and returns %NULL on failure. 165Contrast with g_malloc(), which aborts the program on failure. 166</para> 167 168@n_bytes: number of bytes to allocate. 169@Returns: the allocated memory, or %NULL. 170 171 172<!-- ##### FUNCTION g_try_malloc0 ##### --> 173<para> 174Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on 175failure. Contrast with g_malloc0(), which aborts the program on failure. 176</para> 177 178@n_bytes: number of bytes to allocate 179@Returns: the allocated memory, or %NULL 180@Since: 2.8 181 182 183<!-- ##### FUNCTION g_try_realloc ##### --> 184<para> 185Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL 186on failure. Contrast with g_realloc(), which aborts the program 187on failure. If @mem is %NULL, behaves the same as g_try_malloc(). 188</para> 189 190@mem: previously-allocated memory, or %NULL. 191@n_bytes: number of bytes to allocate. 192@Returns: the allocated memory, or %NULL. 193 194 195<!-- ##### FUNCTION g_free ##### --> 196<para> 197Frees the memory pointed to by @mem. 198If @mem is %NULL it simply returns. 199</para> 200 201@mem: the memory to free 202 203 204<!-- ##### VARIABLE g_mem_gc_friendly ##### --> 205<para> 206This variable is %TRUE if the <envar>G_DEBUG</envar> environment variable 207includes the key <link linkend="G_DEBUG">gc-friendly</link>. 208</para> 209 210 211<!-- ##### MACRO g_alloca ##### --> 212<para> 213Allocates @size bytes on the stack; these bytes will be freed when the current 214stack frame is cleaned up. This macro essentially just wraps the alloca() 215function present on most UNIX variants. 216Thus it provides the same advantages and pitfalls as alloca(): 217<variablelist> 218 <varlistentry><term></term><listitem><para> 219 + alloca() is very fast, as on most systems it's implemented by just adjusting 220 the stack pointer register. 221 </para></listitem></varlistentry> 222 <varlistentry><term></term><listitem><para> 223 + It doesn't cause any memory fragmentation, within its scope, separate alloca() 224 blocks just build up and are released together at function end. 225 </para></listitem></varlistentry> 226 <varlistentry><term></term><listitem><para> 227 - Allocation sizes have to fit into the current stack frame. For instance in a 228 threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes, 229 so be sparse with alloca() uses. 230 </para></listitem></varlistentry> 231 <varlistentry><term></term><listitem><para> 232 - Allocation failure due to insufficient stack space is not indicated with a %NULL 233 return like e.g. with malloc(). Instead, most systems probably handle it the same 234 way as out of stack space situations from infinite function recursion, i.e. 235 with a segmentation fault. 236 </para></listitem></varlistentry> 237 <varlistentry><term></term><listitem><para> 238 - Special care has to be taken when mixing alloca() with GNU C variable sized arrays. 239 Stack space allocated with alloca() in the same scope as a variable sized array 240 will be freed together with the variable sized array upon exit of that scope, and 241 not upon exit of the enclosing function scope. 242 </para></listitem></varlistentry> 243</variablelist> 244 245</para> 246 247@size: number of bytes to allocate. 248@Returns: space for @size bytes, allocated on the stack 249 250 251<!-- ##### MACRO g_newa ##### --> 252<para> 253Wraps g_alloca() in a more typesafe manner. 254</para> 255 256@struct_type: Type of memory chunks to be allocated 257@n_structs: Number of chunks to be allocated 258@Returns: Pointer to stack space for @n_structs chunks of type @struct_type 259 260 261<!-- ##### MACRO g_memmove ##### --> 262<para> 263 264</para> 265 266@dest: 267@src: 268@len: 269 270 271<!-- ##### FUNCTION g_memdup ##### --> 272<para> 273Allocates @byte_size bytes of memory, and copies @byte_size bytes into it 274from @mem. If @mem is %NULL it returns %NULL. 275</para> 276 277@mem: the memory to copy. 278@byte_size: the number of bytes to copy. 279@Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem 280is %NULL. 281 282 283<!-- ##### STRUCT GMemVTable ##### --> 284<para> 285A set of functions used to perform memory allocation. The same #GMemVTable must 286be used for all allocations in the same program; a call to g_mem_set_vtable(), 287if it exists, should be prior to any use of GLib. 288</para> 289 290@malloc: function to use for allocating memory. 291@realloc: function to use for reallocating memory. 292@free: function to use to free memory. 293@calloc: function to use for allocating zero-filled memory. 294@try_malloc: function to use for allocating memory without a default error handler. 295@try_realloc: function to use for reallocating memory without a default error handler. 296 297<!-- ##### FUNCTION g_mem_set_vtable ##### --> 298<para> 299Sets the #GMemVTable to use for memory allocation. You can use this to provide 300custom memory allocation routines. <emphasis>This function must be called 301before using any other GLib functions.</emphasis> The @vtable only needs to 302provide malloc(), realloc(), and free() functions; GLib can provide default 303implementations of the others. The malloc() and realloc() implementations 304should return %NULL on failure, GLib will handle error-checking for you. 305@vtable is copied, so need not persist after this function has been called. 306</para> 307 308@vtable: table of memory allocation routines. 309 310 311<!-- ##### FUNCTION g_mem_is_system_malloc ##### --> 312<para> 313 314</para> 315 316@Returns: 317 318 319<!-- ##### VARIABLE glib_mem_profiler_table ##### --> 320<para> 321A #GMemVTable containing profiling variants of the memory 322allocation functions. Use them together with g_mem_profile() 323in order to get information about the memory allocation pattern 324of your program. 325</para> 326 327 328<!-- ##### FUNCTION g_mem_profile ##### --> 329<para> 330Outputs a summary of memory usage. 331</para> 332<para> 333It outputs the frequency of allocations of different sizes, 334the total number of bytes which have been allocated, 335the total number of bytes which have been freed, 336and the difference between the previous two values, i.e. the number of bytes 337still in use. 338</para> 339<para> 340Note that this function will not output anything unless you have 341previously installed the #glib_mem_profiler_table with g_mem_set_vtable(). 342</para> 343 344 345 346