1
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
5
<title>Memory Allocation</title>
6
<meta name="generator" content="DocBook XSL Stylesheets V1.72.0">
7
<link rel="start" href="index.html" title="GLib Reference Manual">
8
<link rel="up" href="glib-core.html" title="GLib Core Application Support">
9
<link rel="prev" href="glib-Dynamic-Loading-of-Modules.html" title="Dynamic Loading of Modules">
10
<link rel="next" href="glib-IO-Channels.html" title="IO Channels">
11
<meta name="generator" content="GTK-Doc V1.7 (XML mode)">
12
<link rel="stylesheet" href="style.css" type="text/css">
13
<link rel="chapter" href="glib.html" title="GLib Overview">
14
<link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals">
15
<link rel="chapter" href="glib-core.html" title="GLib Core Application Support">
16
<link rel="chapter" href="glib-utilities.html" title="GLib Utilities">
17
<link rel="chapter" href="glib-data-types.html" title="GLib Data Types">
18
<link rel="chapter" href="tools.html" title="GLib Tools">
19
<link rel="index" href="ix01.html" title="Index">
20
<link rel="index" href="ix02.html" title="Index of deprecated symbols">
21
<link rel="index" href="ix03.html" title="Index of new symbols in 2.2">
22
<link rel="index" href="ix04.html" title="Index of new symbols in 2.4">
23
<link rel="index" href="ix05.html" title="Index of new symbols in 2.6">
24
<link rel="index" href="ix06.html" title="Index of new symbols in 2.8">
25
<link rel="index" href="ix07.html" title="Index of new symbols in 2.10">
26
<link rel="index" href="ix08.html" title="Index of new symbols in 2.12">
28
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
29
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
31
<td><a accesskey="p" href="glib-Dynamic-Loading-of-Modules.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
32
<td><a accesskey="u" href="glib-core.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
33
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
34
<th width="100%" align="center">GLib Reference Manual</th>
35
<td><a accesskey="n" href="glib-IO-Channels.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
37
<tr><td colspan="5" class="shortcuts"><nobr><a href="#id2784961" class="shortcut">Top</a>
39
<a href="#id2785338" class="shortcut">Description</a></nobr></td></tr>
41
<div class="refentry" lang="en">
42
<a name="glib-Memory-Allocation"></a><div class="titlepage"></div>
43
<div class="refnamediv"><table width="100%"><tr>
46
<a name="id2784961"></a><span class="refentrytitle">Memory Allocation</span>
48
<p>Memory Allocation — general memory-handling.</p>
50
<td valign="top" align="right"></td>
52
<div class="refsynopsisdiv">
54
<pre class="synopsis">
56
#include <glib.h>
59
#define <a href="glib-Memory-Allocation.html#g-new">g_new</a> (struct_type, n_structs)
60
#define <a href="glib-Memory-Allocation.html#g-new0">g_new0</a> (struct_type, n_structs)
61
#define <a href="glib-Memory-Allocation.html#g-renew">g_renew</a> (struct_type, mem, n_structs)
62
#define <a href="glib-Memory-Allocation.html#g-try-new">g_try_new</a> (struct_type, n_structs)
63
#define <a href="glib-Memory-Allocation.html#g-try-new0">g_try_new0</a> (struct_type, n_structs)
64
#define <a href="glib-Memory-Allocation.html#g-try-renew">g_try_renew</a> (struct_type, mem, n_structs)
66
<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Memory-Allocation.html#g-malloc">g_malloc</a> (<a href="glib-Basic-Types.html#gulong">gulong</a> n_bytes);
67
<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Memory-Allocation.html#g-malloc0">g_malloc0</a> (<a href="glib-Basic-Types.html#gulong">gulong</a> n_bytes);
68
<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Memory-Allocation.html#g-realloc">g_realloc</a> (<a href="glib-Basic-Types.html#gpointer">gpointer</a> mem,
69
<a href="glib-Basic-Types.html#gulong">gulong</a> n_bytes);
70
<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Memory-Allocation.html#g-try-malloc">g_try_malloc</a> (<a href="glib-Basic-Types.html#gulong">gulong</a> n_bytes);
71
<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Memory-Allocation.html#g-try-malloc0">g_try_malloc0</a> (<a href="glib-Basic-Types.html#gulong">gulong</a> n_bytes);
72
<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Memory-Allocation.html#g-try-realloc">g_try_realloc</a> (<a href="glib-Basic-Types.html#gpointer">gpointer</a> mem,
73
<a href="glib-Basic-Types.html#gulong">gulong</a> n_bytes);
75
void <a href="glib-Memory-Allocation.html#g-free">g_free</a> (<a href="glib-Basic-Types.html#gpointer">gpointer</a> mem);
76
extern gboolean <a href="glib-Memory-Allocation.html#g-mem-gc-friendly">g_mem_gc_friendly</a>;
78
#define <a href="glib-Memory-Allocation.html#g-alloca">g_alloca</a> (size)
79
#define <a href="glib-Memory-Allocation.html#g-newa">g_newa</a> (struct_type, n_structs)
81
#define <a href="glib-Memory-Allocation.html#g-memmove">g_memmove</a> (dest,src,len)
82
<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Memory-Allocation.html#g-memdup">g_memdup</a> (<a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> mem,
83
<a href="glib-Basic-Types.html#guint">guint</a> byte_size);
85
<a href="glib-Memory-Allocation.html#GMemVTable">GMemVTable</a>;
86
void <a href="glib-Memory-Allocation.html#g-mem-set-vtable">g_mem_set_vtable</a> (<a href="glib-Memory-Allocation.html#GMemVTable">GMemVTable</a> *vtable);
87
<a href="glib-Basic-Types.html#gboolean">gboolean</a> <a href="glib-Memory-Allocation.html#g-mem-is-system-malloc">g_mem_is_system_malloc</a> (void);
89
extern GMemVTable *<a href="glib-Memory-Allocation.html#glib-mem-profiler-table">glib_mem_profiler_table</a>;
90
void <a href="glib-Memory-Allocation.html#g-mem-profile">g_mem_profile</a> (void);
93
<div class="refsect1" lang="en">
94
<a name="id2785338"></a><h2>Description</h2>
96
These functions provide support for allocating and freeing memory.
98
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
99
<h3 class="title">Note</h3>
101
If any call to allocate memory fails, the application is terminated.
102
This also means that there is no need to check if the call succeeded.
106
<div class="refsect1" lang="en">
107
<a name="id2785363"></a><h2>Details</h2>
108
<div class="refsect2" lang="en">
109
<a name="id2785373"></a><h3>
110
<a name="g-new"></a>g_new()</h3>
111
<a class="indexterm" name="id2785386"></a><pre class="programlisting">#define g_new(struct_type, n_structs)</pre>
113
Allocates <em class="parameter"><code>n_structs</code></em> elements of type <em class="parameter"><code>struct_type</code></em>.
114
The returned pointer is cast to a pointer to the given type.
115
If <em class="parameter"><code>n_structs</code></em> is 0 it returns <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
118
Since the returned pointer is already casted to the right type,
119
it is normally unnecessary to cast it explicitly, and doing
120
so might hide memory allocation errors.
122
<div class="variablelist"><table border="0">
123
<col align="left" valign="top">
126
<td><span class="term"><em class="parameter"><code>struct_type</code></em> :</span></td>
127
<td>the type of the elements to allocate.
131
<td><span class="term"><em class="parameter"><code>n_structs</code></em> :</span></td>
132
<td>the number of elements to allocate.
136
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
137
<td>a pointer to the allocated memory, cast to a pointer to <em class="parameter"><code>struct_type</code></em>.
146
<div class="refsect2" lang="en">
147
<a name="id2785487"></a><h3>
148
<a name="g-new0"></a>g_new0()</h3>
149
<a class="indexterm" name="id2785500"></a><pre class="programlisting">#define g_new0(struct_type, n_structs)</pre>
151
Allocates <em class="parameter"><code>n_structs</code></em> elements of type <em class="parameter"><code>struct_type</code></em>, initialized to 0's.
152
The returned pointer is cast to a pointer to the given type.
153
If <em class="parameter"><code>n_structs</code></em> is 0 it returns <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
156
Since the returned pointer is already casted to the right type,
157
it is normally unnecessary to cast it explicitly, and doing
158
so might hide memory allocation errors.
160
<div class="variablelist"><table border="0">
161
<col align="left" valign="top">
164
<td><span class="term"><em class="parameter"><code>struct_type</code></em> :</span></td>
165
<td>the type of the elements to allocate.
169
<td><span class="term"><em class="parameter"><code>n_structs</code></em> :</span></td>
170
<td>the number of elements to allocate.
174
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
175
<td>a pointer to the allocated memory, cast to a pointer to <em class="parameter"><code>struct_type</code></em>.
184
<div class="refsect2" lang="en">
185
<a name="id2785601"></a><h3>
186
<a name="g-renew"></a>g_renew()</h3>
187
<a class="indexterm" name="id2785613"></a><pre class="programlisting">#define g_renew(struct_type, mem, n_structs)</pre>
189
Reallocates the memory pointed to by <em class="parameter"><code>mem</code></em>, so that it now has space for
190
<em class="parameter"><code>n_structs</code></em> elements of type <em class="parameter"><code>struct_type</code></em>. It returns the new address of
191
the memory, which may have been moved.
193
<div class="variablelist"><table border="0">
194
<col align="left" valign="top">
197
<td><span class="term"><em class="parameter"><code>struct_type</code></em> :</span></td>
198
<td>the type of the elements to allocate.
202
<td><span class="term"><em class="parameter"><code>mem</code></em> :</span></td>
203
<td>the currently allocated memory.
207
<td><span class="term"><em class="parameter"><code>n_structs</code></em> :</span></td>
208
<td>the number of elements to allocate.
212
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
213
<td>a pointer to the new allocated memory, cast to a pointer to <em class="parameter"><code>struct_type</code></em>.
222
<div class="refsect2" lang="en">
223
<a name="id2785714"></a><h3>
224
<a name="g-try-new"></a>g_try_new()</h3>
225
<a class="indexterm" name="id2785728"></a><pre class="programlisting">#define g_try_new(struct_type, n_structs)</pre>
227
Attempts to allocate <em class="parameter"><code>n_structs</code></em> elements of type <em class="parameter"><code>struct_type</code></em>, and returns
228
<a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on failure. Contrast with <a href="glib-Memory-Allocation.html#g-new"><code class="function">g_new()</code></a>, which aborts the program on failure.
229
The returned pointer is cast to a pointer to the given type.
230
If <em class="parameter"><code>n_structs</code></em> is 0 it returns <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
232
<div class="variablelist"><table border="0">
233
<col align="left" valign="top">
236
<td><span class="term"><em class="parameter"><code>struct_type</code></em> :</span></td>
237
<td>the type of the elements to allocate.
241
<td><span class="term"><em class="parameter"><code>n_structs</code></em> :</span></td>
242
<td>the number of elements to allocate.
246
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
247
<td>a pointer to the allocated memory, cast to a pointer to <em class="parameter"><code>struct_type</code></em>.
252
<p class="since">Since 2.8
258
<div class="refsect2" lang="en">
259
<a name="id2785852"></a><h3>
260
<a name="g-try-new0"></a>g_try_new0()</h3>
261
<a class="indexterm" name="id2785867"></a><pre class="programlisting">#define g_try_new0(struct_type, n_structs)</pre>
263
Attempts to allocate <em class="parameter"><code>n_structs</code></em> elements of type <em class="parameter"><code>struct_type</code></em>, initialized
264
to 0's, and returns <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on failure. Contrast with <a href="glib-Memory-Allocation.html#g-new0"><code class="function">g_new0()</code></a>, which aborts
265
the program on failure.
266
The returned pointer is cast to a pointer to the given type.
267
If <em class="parameter"><code>n_counts</code></em> is 0 it returns <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
269
<div class="variablelist"><table border="0">
270
<col align="left" valign="top">
273
<td><span class="term"><em class="parameter"><code>struct_type</code></em> :</span></td>
274
<td>the type of the elements to allocate.
278
<td><span class="term"><em class="parameter"><code>n_structs</code></em> :</span></td>
279
<td>the number of elements to allocate.
283
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
284
<td>a pointer to the allocated memory, cast to a pointer to <em class="parameter"><code>struct_type</code></em>.
289
<p class="since">Since 2.8
295
<div class="refsect2" lang="en">
296
<a name="id2785991"></a><h3>
297
<a name="g-try-renew"></a>g_try_renew()</h3>
298
<a class="indexterm" name="id2786005"></a><pre class="programlisting">#define g_try_renew(struct_type, mem, n_structs)</pre>
300
Attempts to reallocate the memory pointed to by <em class="parameter"><code>mem</code></em>, so that it now has
301
space for <em class="parameter"><code>n_structs</code></em> elements of type <em class="parameter"><code>struct_type</code></em>, and returns <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on
302
failure. Contrast with <a href="glib-Memory-Allocation.html#g-renew"><code class="function">g_renew()</code></a>, which aborts the program on failure.
303
It returns the new address of the memory, which may have been moved.
305
<div class="variablelist"><table border="0">
306
<col align="left" valign="top">
309
<td><span class="term"><em class="parameter"><code>struct_type</code></em> :</span></td>
310
<td>the type of the elements to allocate.
314
<td><span class="term"><em class="parameter"><code>mem</code></em> :</span></td>
315
<td>the currently allocated memory.
319
<td><span class="term"><em class="parameter"><code>n_structs</code></em> :</span></td>
320
<td>the number of elements to allocate.
324
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
325
<td>a pointer to the new allocated memory, cast to a pointer to <em class="parameter"><code>struct_type</code></em>.
330
<p class="since">Since 2.8
336
<div class="refsect2" lang="en">
337
<a name="id2786134"></a><h3>
338
<a name="g-malloc"></a>g_malloc ()</h3>
339
<a class="indexterm" name="id2786146"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gpointer">gpointer</a> g_malloc (<a href="glib-Basic-Types.html#gulong">gulong</a> n_bytes);</pre>
341
Allocates <em class="parameter"><code>n_bytes</code></em> bytes of memory.
342
If <em class="parameter"><code>n_bytes</code></em> is 0 it returns <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
344
<div class="variablelist"><table border="0">
345
<col align="left" valign="top">
348
<td><span class="term"><em class="parameter"><code>n_bytes</code></em> :</span></td>
349
<td>the number of bytes to allocate.
353
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
354
<td>a pointer to the allocated memory.
363
<div class="refsect2" lang="en">
364
<a name="id2786226"></a><h3>
365
<a name="g-malloc0"></a>g_malloc0 ()</h3>
366
<a class="indexterm" name="id2786239"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gpointer">gpointer</a> g_malloc0 (<a href="glib-Basic-Types.html#gulong">gulong</a> n_bytes);</pre>
368
Allocates <em class="parameter"><code>n_bytes</code></em> bytes of memory, initialized to 0's.
369
If <em class="parameter"><code>n_bytes</code></em> is 0 it returns <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
371
<div class="variablelist"><table border="0">
372
<col align="left" valign="top">
375
<td><span class="term"><em class="parameter"><code>n_bytes</code></em> :</span></td>
376
<td>the number of bytes to allocate.
380
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
381
<td>a pointer to the allocated memory.
390
<div class="refsect2" lang="en">
391
<a name="id2786319"></a><h3>
392
<a name="g-realloc"></a>g_realloc ()</h3>
393
<a class="indexterm" name="id2786332"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gpointer">gpointer</a> g_realloc (<a href="glib-Basic-Types.html#gpointer">gpointer</a> mem,
394
<a href="glib-Basic-Types.html#gulong">gulong</a> n_bytes);</pre>
396
Reallocates the memory pointed to by <em class="parameter"><code>mem</code></em>, so that it now has space for
397
<em class="parameter"><code>n_bytes</code></em> bytes of memory. It returns the new address of the memory, which may
398
have been moved. <em class="parameter"><code>mem</code></em> may be <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, in which case it's considered to
399
have zero-length. <em class="parameter"><code>n_bytes</code></em> may be 0, in which case <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> will be returned.
401
<div class="variablelist"><table border="0">
402
<col align="left" valign="top">
405
<td><span class="term"><em class="parameter"><code>mem</code></em> :</span></td>
406
<td>the memory to reallocate.
410
<td><span class="term"><em class="parameter"><code>n_bytes</code></em> :</span></td>
411
<td>new size of the memory in bytes.
415
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
416
<td>the new address of the allocated memory.
425
<div class="refsect2" lang="en">
426
<a name="id2786459"></a><h3>
427
<a name="g-try-malloc"></a>g_try_malloc ()</h3>
428
<a class="indexterm" name="id2786472"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gpointer">gpointer</a> g_try_malloc (<a href="glib-Basic-Types.html#gulong">gulong</a> n_bytes);</pre>
430
Attempts to allocate <em class="parameter"><code>n_bytes</code></em>, and returns <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on failure.
431
Contrast with <a href="glib-Memory-Allocation.html#g-malloc"><code class="function">g_malloc()</code></a>, which aborts the program on failure.
433
<div class="variablelist"><table border="0">
434
<col align="left" valign="top">
437
<td><span class="term"><em class="parameter"><code>n_bytes</code></em> :</span></td>
438
<td>number of bytes to allocate.
442
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
443
<td>the allocated memory, or <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
452
<div class="refsect2" lang="en">
453
<a name="id2786567"></a><h3>
454
<a name="g-try-malloc0"></a>g_try_malloc0 ()</h3>
455
<a class="indexterm" name="id2786582"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gpointer">gpointer</a> g_try_malloc0 (<a href="glib-Basic-Types.html#gulong">gulong</a> n_bytes);</pre>
457
Attempts to allocate <em class="parameter"><code>n_bytes</code></em>, initialized to 0's, and returns <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on
458
failure. Contrast with <a href="glib-Memory-Allocation.html#g-malloc0"><code class="function">g_malloc0()</code></a>, which aborts the program on failure.
460
<div class="variablelist"><table border="0">
461
<col align="left" valign="top">
464
<td><span class="term"><em class="parameter"><code>n_bytes</code></em> :</span></td>
465
<td>number of bytes to allocate.
469
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
470
<td>the allocated memory, or <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
475
<p class="since">Since 2.8
481
<div class="refsect2" lang="en">
482
<a name="id2786685"></a><h3>
483
<a name="g-try-realloc"></a>g_try_realloc ()</h3>
484
<a class="indexterm" name="id2786698"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gpointer">gpointer</a> g_try_realloc (<a href="glib-Basic-Types.html#gpointer">gpointer</a> mem,
485
<a href="glib-Basic-Types.html#gulong">gulong</a> n_bytes);</pre>
487
Attempts to realloc <em class="parameter"><code>mem</code></em> to a new size, <em class="parameter"><code>n_bytes</code></em>, and returns <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>
488
on failure. Contrast with <a href="glib-Memory-Allocation.html#g-realloc"><code class="function">g_realloc()</code></a>, which aborts the program
489
on failure. If <em class="parameter"><code>mem</code></em> is <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, behaves the same as <a href="glib-Memory-Allocation.html#g-try-malloc"><code class="function">g_try_malloc()</code></a>.
491
<div class="variablelist"><table border="0">
492
<col align="left" valign="top">
495
<td><span class="term"><em class="parameter"><code>mem</code></em> :</span></td>
496
<td>previously-allocated memory, or <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
500
<td><span class="term"><em class="parameter"><code>n_bytes</code></em> :</span></td>
501
<td>number of bytes to allocate.
505
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
506
<td>the allocated memory, or <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
515
<div class="refsect2" lang="en">
516
<a name="id2786857"></a><h3>
517
<a name="g-free"></a>g_free ()</h3>
518
<a class="indexterm" name="id2786869"></a><pre class="programlisting">void g_free (<a href="glib-Basic-Types.html#gpointer">gpointer</a> mem);</pre>
520
Frees the memory pointed to by <em class="parameter"><code>mem</code></em>.
521
If <em class="parameter"><code>mem</code></em> is <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> it simply returns.
523
<div class="variablelist"><table border="0">
524
<col align="left" valign="top">
526
<td><span class="term"><em class="parameter"><code>mem</code></em> :</span></td>
527
<td>the memory to free.
535
<div class="refsect2" lang="en">
536
<a name="id2786938"></a><h3>
537
<a name="g-mem-gc-friendly"></a>g_mem_gc_friendly</h3>
538
<a class="indexterm" name="id2786951"></a><pre class="programlisting">extern gboolean g_mem_gc_friendly;
541
This variable is <a href="glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the <code class="envar">G_DEBUG</code> environment variable
542
includes the key <a href="glib-running.html#G_DEBUG" title="G_DEBUG">gc-friendly</a>.
546
<div class="refsect2" lang="en">
547
<a name="id2786990"></a><h3>
548
<a name="g-alloca"></a>g_alloca()</h3>
549
<a class="indexterm" name="id2787002"></a><pre class="programlisting">#define g_alloca(size)</pre>
551
Allocates <em class="parameter"><code>size</code></em> bytes on the stack; these bytes will be freed when the current
552
stack frame is cleaned up. This macro essentially just wraps the
553
<code class="function"><code class="function">alloca()</code></code> function present on most UNIX variants.
554
Thus it provides the same advantages and pitfalls as <code class="function"><code class="function">alloca()</code></code>:
556
<div class="variablelist"><table border="0">
557
<col align="left" valign="top">
560
<td><span class="term"></span></td>
562
+ <code class="function"><code class="function">alloca()</code></code> is very fast, as on most systems it's implemented by just adjusting
563
the stack pointer register.
567
<td><span class="term"></span></td>
569
+ It doesn't cause any memory fragmentation, within its scope, separate <code class="function"><code class="function">alloca()</code></code>
570
blocks just build up and are released together at function end.
574
<td><span class="term"></span></td>
576
- Allocation sizes have to fit into the current stack frame. For instance in a
577
threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
578
so be sparse with <code class="function"><code class="function">alloca()</code></code> uses.
582
<td><span class="term"></span></td>
584
- Allocation failure due to insufficient stack space is not indicated with a <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>
585
return like e.g. with <code class="function"><code class="function">malloc()</code></code>. Instead, most systems probably handle it the same
586
way as out of stack space situations from infinite function recursion, i.e.
587
with a segmentation fault.
591
<td><span class="term"></span></td>
593
- Special care has to be taken when mixing <code class="function"><code class="function">alloca()</code></code> with GNU C variable sized arrays.
594
Stack space allocated with <code class="function"><code class="function">alloca()</code></code> in the same scope as a variable sized array
595
will be freed together with the variable sized array upon exit of that scope, and
596
not upon exit of the enclosing function scope.
604
<div class="variablelist"><table border="0">
605
<col align="left" valign="top">
608
<td><span class="term"><em class="parameter"><code>size</code></em> :</span></td>
609
<td> number of bytes to allocate.
613
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
614
<td>space for <em class="parameter"><code>size</code></em> bytes, allocated on the stack
623
<div class="refsect2" lang="en">
624
<a name="id2787241"></a><h3>
625
<a name="g-newa"></a>g_newa()</h3>
626
<a class="indexterm" name="id2787253"></a><pre class="programlisting">#define g_newa(struct_type, n_structs)</pre>
628
Wraps <a href="glib-Memory-Allocation.html#g-alloca"><code class="function">g_alloca()</code></a> in a more typesafe manner.
630
<div class="variablelist"><table border="0">
631
<col align="left" valign="top">
634
<td><span class="term"><em class="parameter"><code>struct_type</code></em> :</span></td>
635
<td>Type of memory chunks to be allocated
639
<td><span class="term"><em class="parameter"><code>n_structs</code></em> :</span></td>
640
<td> Number of chunks to be allocated
644
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
645
<td> Pointer to stack space for <em class="parameter"><code>n_structs</code></em> chunks of type <em class="parameter"><code>struct_type</code></em>
654
<div class="refsect2" lang="en">
655
<a name="id2787334"></a><h3>
656
<a name="g-memmove"></a>g_memmove()</h3>
657
<a class="indexterm" name="id2787347"></a><pre class="programlisting">#define g_memmove(dest,src,len)</pre>
659
Copies a block of memory <em class="parameter"><code>len</code></em> bytes long, from <em class="parameter"><code>src</code></em> to <em class="parameter"><code>dest</code></em>.
660
The source and destination areas may overlap.
663
In order to use this function, you must include
664
<code class="filename">string.h</code> yourself, because this macro will
665
typically simply resolve to <code class="function">memmove()</code> and GLib does not include
666
<code class="filename">string.h</code> for you.</p>
670
<div class="variablelist"><table border="0">
671
<col align="left" valign="top">
674
<td><span class="term"><em class="parameter"><code>dest</code></em> :</span></td>
675
<td> the destination address to copy the bytes to.
679
<td><span class="term"><em class="parameter"><code>src</code></em> :</span></td>
680
<td> the source address to copy the bytes from.
684
<td><span class="term"><em class="parameter"><code>len</code></em> :</span></td>
685
<td> the number of bytes to copy.
692
<div class="refsect2" lang="en">
693
<a name="id2787459"></a><h3>
694
<a name="g-memdup"></a>g_memdup ()</h3>
695
<a class="indexterm" name="id2787471"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gpointer">gpointer</a> g_memdup (<a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> mem,
696
<a href="glib-Basic-Types.html#guint">guint</a> byte_size);</pre>
698
Allocates <em class="parameter"><code>byte_size</code></em> bytes of memory, and copies <em class="parameter"><code>byte_size</code></em> bytes into it
699
from <em class="parameter"><code>mem</code></em>. If <em class="parameter"><code>mem</code></em> is <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> it returns <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
701
<div class="variablelist"><table border="0">
702
<col align="left" valign="top">
705
<td><span class="term"><em class="parameter"><code>mem</code></em> :</span></td>
706
<td>the memory to copy.
710
<td><span class="term"><em class="parameter"><code>byte_size</code></em> :</span></td>
711
<td>the number of bytes to copy.
715
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
716
<td>a pointer to the newly-allocated copy of the memory, or <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if <em class="parameter"><code>mem</code></em>
717
is <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
726
<div class="refsect2" lang="en">
727
<a name="id2787622"></a><h3>
728
<a name="GMemVTable"></a>GMemVTable</h3>
729
<a class="indexterm" name="id2787635"></a><pre class="programlisting">typedef struct {
730
gpointer (*malloc) (gsize n_bytes);
731
gpointer (*realloc) (gpointer mem,
733
void (*free) (gpointer mem);
734
/* optional; set to NULL if not used ! */
735
gpointer (*calloc) (gsize n_blocks,
736
gsize n_block_bytes);
737
gpointer (*try_malloc) (gsize n_bytes);
738
gpointer (*try_realloc) (gpointer mem,
743
A set of functions used to perform memory allocation. The same <a href="glib-Memory-Allocation.html#GMemVTable"><span class="type">GMemVTable</span></a> must
744
be used for all allocations in the same program; a call to <a href="glib-Memory-Allocation.html#g-mem-set-vtable"><code class="function">g_mem_set_vtable()</code></a>,
745
if it exists, should be prior to any use of GLib.
747
<div class="variablelist"><table border="0">
748
<col align="left" valign="top">
751
<td><span class="term"><em class="structfield"><code>malloc</code></em> ()</span></td>
752
<td>function to use for allocating memory.
756
<td><span class="term"><em class="structfield"><code>realloc</code></em> ()</span></td>
757
<td>function to use for reallocating memory.
761
<td><span class="term"><em class="structfield"><code>free</code></em> ()</span></td>
762
<td>function to use to free memory.
766
<td><span class="term"><em class="structfield"><code>calloc</code></em> ()</span></td>
767
<td>function to use for allocating zero-filled memory.
771
<td><span class="term"><em class="structfield"><code>try_malloc</code></em> ()</span></td>
772
<td>function to use for allocating memory without a default error handler.
776
<td><span class="term"><em class="structfield"><code>try_realloc</code></em> ()</span></td>
777
<td>function to use for reallocating memory without a default error handler.
785
<div class="refsect2" lang="en">
786
<a name="id2787767"></a><h3>
787
<a name="g-mem-set-vtable"></a>g_mem_set_vtable ()</h3>
788
<a class="indexterm" name="id2787780"></a><pre class="programlisting">void g_mem_set_vtable (<a href="glib-Memory-Allocation.html#GMemVTable">GMemVTable</a> *vtable);</pre>
790
Sets the <a href="glib-Memory-Allocation.html#GMemVTable"><span class="type">GMemVTable</span></a> to use for memory allocation. You can use this to provide
791
custom memory allocation routines. <span class="emphasis"><em>This function must be called before using any other GLib functions.</em></span> The <em class="parameter"><code>vtable</code></em> only needs to provide <code class="function"><code class="function">malloc()</code></code>, <code class="function"><code class="function">realloc()</code></code>, and <code class="function"><code class="function">free()</code></code>
792
functions; GLib can provide default implementations of the others. The <code class="function"><code class="function">malloc()</code></code>
793
and <code class="function"><code class="function">realloc()</code></code> implementations should return <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on failure, GLib will handle
794
error-checking for you. <em class="parameter"><code>vtable</code></em> is copied, so need not persist after this
795
function has been called.
797
<div class="variablelist"><table border="0">
798
<col align="left" valign="top">
800
<td><span class="term"><em class="parameter"><code>vtable</code></em> :</span></td>
801
<td>table of memory allocation routines.
809
<div class="refsect2" lang="en">
810
<a name="id2787938"></a><h3>
811
<a name="g-mem-is-system-malloc"></a>g_mem_is_system_malloc ()</h3>
812
<a class="indexterm" name="id2787951"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gboolean">gboolean</a> g_mem_is_system_malloc (void);</pre>
814
Checks whether the allocator used by <a href="glib-Memory-Allocation.html#g-malloc"><code class="function">g_malloc()</code></a> is the system's
815
malloc implementation. If it returns <a href="glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> memory allocated with
816
<code class="function">malloc()</code> can be used interchangeable with memory allocated using <a href="glib-Memory-Allocation.html#g-malloc"><code class="function">g_malloc()</code></a>.
817
This function is useful for avoiding an extra copy of allocated memory returned
818
by a non-GLib-based API.
821
A different allocator can be set using <a href="glib-Memory-Allocation.html#g-mem-set-vtable"><code class="function">g_mem_set_vtable()</code></a>.</p>
825
<div class="variablelist"><table border="0">
826
<col align="left" valign="top">
828
<td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
829
<td> if <a href="glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, <code class="function">malloc()</code> and <a href="glib-Memory-Allocation.html#g-malloc"><code class="function">g_malloc()</code></a> can be mixed.
835
<div class="refsect2" lang="en">
836
<a name="id2788081"></a><h3>
837
<a name="glib-mem-profiler-table"></a>glib_mem_profiler_table</h3>
838
<a class="indexterm" name="id2788094"></a><pre class="programlisting">extern GMemVTable *glib_mem_profiler_table;
841
A <a href="glib-Memory-Allocation.html#GMemVTable"><span class="type">GMemVTable</span></a> containing profiling variants of the memory
842
allocation functions. Use them together with <a href="glib-Memory-Allocation.html#g-mem-profile"><code class="function">g_mem_profile()</code></a>
843
in order to get information about the memory allocation pattern
848
<div class="refsect2" lang="en">
849
<a name="id2788131"></a><h3>
850
<a name="g-mem-profile"></a>g_mem_profile ()</h3>
851
<a class="indexterm" name="id2788144"></a><pre class="programlisting">void g_mem_profile (void);</pre>
853
Outputs a summary of memory usage.
856
It outputs the frequency of allocations of different sizes,
857
the total number of bytes which have been allocated,
858
the total number of bytes which have been freed,
859
and the difference between the previous two values, i.e. the number of bytes
863
Note that this function will not output anything unless you have
864
previously installed the <a href="glib-Memory-Allocation.html#glib-mem-profiler-table"><span class="type">glib_mem_profiler_table</span></a> with <a href="glib-Memory-Allocation.html#g-mem-set-vtable"><code class="function">g_mem_set_vtable()</code></a>.
added
removed
docs/reference/glib/html/glib-Memory-Allocation.html
