1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
|
<h1 id="firstHeading" class="firstHeading">free</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">void free( void *ptr );</pre>
</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Deallocates the space previously allocated by <code><a href="malloc" title="c/memory/malloc">malloc()</a></code>, <code><a href="calloc" title="c/memory/calloc">calloc()</a></code><span class="t-rev-inl t-since-c11"><span>, <code>aligned_alloc()</code>,</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> or <code><a href="realloc" title="c/memory/realloc">realloc()</a></code>.</p>
<p>If <code>ptr</code> is a null pointer, the function does nothing.</p>
<p>The behavior is undefined if the value of <code>ptr</code> does not equal a value returned earlier by <code><a href="malloc" title="c/memory/malloc">malloc()</a></code>, <code><a href="calloc" title="c/memory/calloc">calloc()</a></code>, <code><a href="realloc" title="c/memory/realloc">realloc()</a></code><span class="t-rev-inl t-since-c11"><span>, or <code>aligned_alloc()</code></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span>.</p>
<p>The behavior is undefined if the memory area referred to by <code>ptr</code> has already been deallocated, that is, <code>free()</code><span class="t-rev-inl t-since-c23"><span>, <code>free_sized()</code>, <code>free_aligned_sized()</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, or <code><a href="realloc" title="c/memory/realloc">realloc()</a></code> has already been called with <code>ptr</code> as the argument and no calls to <code><a href="malloc" title="c/memory/malloc">malloc()</a></code>, <code><a href="calloc" title="c/memory/calloc">calloc()</a></code>, <code><a href="realloc" title="c/memory/realloc">realloc()</a></code><span class="t-rev-inl t-since-c11"><span>, or <code>aligned_alloc()</code></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> resulted in a pointer equal to <code>ptr</code> afterwards.</p>
<p>The behavior is undefined if after <code>free()</code> returns, an access is made through the pointer <code>ptr</code> (unless another allocation function happened to result in a pointer value equal to <code>ptr</code>).</p>
<table class="t-rev-begin"> <tr class="t-rev t-since-c11">
<td> <p><code>free</code> is thread-safe: it behaves as though only accessing the memory locations visible through its argument, and not any static storage.</p>
<p>A call to <code>free</code> that deallocates a region of memory <i>synchronizes-with</i> a call to any subsequent allocation function that allocates the same or a part of the same region of memory. This synchronization occurs after any access to the memory by the deallocating function and before any access to the memory by the allocation function. There is a single total order of all allocation and deallocation functions operating on each particular region of memory.</p>
</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td>
</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ptr </td> <td> - </td> <td> pointer to the memory to deallocate </td>
</tr>
</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p>
<h3 id="Notes"> Notes</h3> <p>The function accepts (and does nothing with) the null pointer to reduce the amount of special-casing. Whether allocation succeeds or not, the pointer returned by an allocation function can be passed to <code>free()</code>.</p>
<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdlib.h>
int main(void)
{
int *p1 = malloc(10*sizeof *p1);
free(p1); // every allocated pointer must be freed
int *p2 = calloc(10, sizeof *p2);
int *p3 = realloc(p2, 1000*sizeof *p3);
if(p3) // p3 not null means p2 was freed by realloc
free(p3);
else // p3 null means p2 was not freed
free(p2);
}</pre></div> </div> <h3 id="References"> References</h3> <ul>
<li> C23 standard (ISO/IEC 9899:2023): </li>
<ul><li> 7.24.3.3 The free function </li></ul>
<li> C17 standard (ISO/IEC 9899:2018): </li>
<ul><li> 7.22.3.3 The free function (p: 254) </li></ul>
<li> C11 standard (ISO/IEC 9899:2011): </li>
<ul><li> 7.22.3.3 The free function (p: 348) </li></ul>
<li> C99 standard (ISO/IEC 9899:1999): </li>
<ul><li> 7.20.3.2 The free function (p: 313) </li></ul>
<li> C89/C90 standard (ISO/IEC 9899:1990): </li>
<ul><li> 4.10.3.2 The free function </li></ul>
</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="malloc" title="c/memory/malloc"> <span class="t-lines"><span>malloc</span></span></a></div> </td> <td> allocates memory <br> <span class="t-mark">(function)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><a href="free_sized" title="c/memory/free sized"> <span class="t-lines"><span>free_sized</span></span></a></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> deallocates previously allocated sized memory <br> <span class="t-mark">(function)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><a href="free_aligned_sized" title="c/memory/free aligned sized"> <span class="t-lines"><span>free_aligned_sized</span></span></a></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> deallocates previously allocated sized and aligned memory <br> <span class="t-mark">(function)</span> </td>
</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/memory/c/free" title="cpp/memory/c/free">C++ documentation</a></span> for <code>free</code> </td>
</tr> </table> <div class="_attribution">
<p class="_attribution-p">
© cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br>
<a href="https://en.cppreference.com/w/c/memory/free" class="_attribution-link">https://en.cppreference.com/w/c/memory/free</a>
</p>
</div>
|
