1<html lang="en"> 2<head> 3<title>malloc - Untitled</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Untitled"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Stdlib.html#Stdlib" title="Stdlib"> 9<link rel="prev" href="lldiv.html#lldiv" title="lldiv"> 10<link rel="next" href="mallinfo.html#mallinfo" title="mallinfo"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<meta http-equiv="Content-Style-Type" content="text/css"> 13<style type="text/css"><!-- 14 pre.display { font-family:inherit } 15 pre.format { font-family:inherit } 16 pre.smalldisplay { font-family:inherit; font-size:smaller } 17 pre.smallformat { font-family:inherit; font-size:smaller } 18 pre.smallexample { font-size:smaller } 19 pre.smalllisp { font-size:smaller } 20 span.sc { font-variant:small-caps } 21 span.roman { font-family:serif; font-weight:normal; } 22 span.sansserif { font-family:sans-serif; font-weight:normal; } 23--></style> 24<link rel="stylesheet" type="text/css" href="../cs.css"> 25</head> 26<body> 27<div class="node"> 28<a name="malloc"></a> 29<p> 30Next: <a rel="next" accesskey="n" href="mallinfo.html#mallinfo">mallinfo</a>, 31Previous: <a rel="previous" accesskey="p" href="lldiv.html#lldiv">lldiv</a>, 32Up: <a rel="up" accesskey="u" href="Stdlib.html#Stdlib">Stdlib</a> 33<hr> 34</div> 35 36<h3 class="section">2.23 <code>malloc</code>, <code>realloc</code>, <code>free</code>—manage memory</h3> 37 38<p><a name="index-malloc-37"></a><a name="index-realloc-38"></a><a name="index-reallocf-39"></a><a name="index-free-40"></a><a name="index-memalign-41"></a><a name="index-malloc_005fusable_005fsize-42"></a><a name="index-g_t_005fmalloc_005fr-43"></a><a name="index-g_t_005frealloc_005fr-44"></a><a name="index-g_t_005freallocf_005fr-45"></a><a name="index-g_t_005ffree_005fr-46"></a><a name="index-g_t_005fmemalign_005fr-47"></a><a name="index-g_t_005fmalloc_005fusable_005fsize_005fr-48"></a><strong>Synopsis</strong> 39<pre class="example"> #include <stdlib.h> 40 void *malloc(size_t <var>nbytes</var>); 41 void *realloc(void *<var>aptr</var>, size_t <var>nbytes</var>); 42 void *reallocf(void *<var>aptr</var>, size_t <var>nbytes</var>); 43 void free(void *<var>aptr</var>); 44 45 void *memalign(size_t <var>align</var>, size_t <var>nbytes</var>); 46 47 size_t malloc_usable_size(void *<var>aptr</var>); 48 49 void *_malloc_r(void *<var>reent</var>, size_t <var>nbytes</var>); 50 void *_realloc_r(void *<var>reent</var>, 51 void *<var>aptr</var>, size_t <var>nbytes</var>); 52 void *_reallocf_r(void *<var>reent</var>, 53 void *<var>aptr</var>, size_t <var>nbytes</var>); 54 void _free_r(void *<var>reent</var>, void *<var>aptr</var>); 55 56 void *_memalign_r(void *<var>reent</var>, 57 size_t <var>align</var>, size_t <var>nbytes</var>); 58 59 size_t _malloc_usable_size_r(void *<var>reent</var>, void *<var>aptr</var>); 60 61</pre> 62 <p><strong>Description</strong><br> 63These functions manage a pool of system memory. 64 65 <p>Use <code>malloc</code> to request allocation of an object with at least 66<var>nbytes</var> bytes of storage available. If the space is available, 67<code>malloc</code> returns a pointer to a newly allocated block as its result. 68 69 <p>If you already have a block of storage allocated by <code>malloc</code>, but 70you no longer need all the space allocated to it, you can make it 71smaller by calling <code>realloc</code> with both the object pointer and the 72new desired size as arguments. <code>realloc</code> guarantees that the 73contents of the smaller object match the beginning of the original object. 74 75 <p>Similarly, if you need more space for an object, use <code>realloc</code> to 76request the larger size; again, <code>realloc</code> guarantees that the 77beginning of the new, larger object matches the contents of the 78original object. 79 80 <p>When you no longer need an object originally allocated by <code>malloc</code> 81or <code>realloc</code> (or the related function <code>calloc</code>), return it to the 82memory storage pool by calling <code>free</code> with the address of the object 83as the argument. You can also use <code>realloc</code> for this purpose by 84calling it with <code>0</code> as the <var>nbytes</var> argument. 85 86 <p>The <code>reallocf</code> function behaves just like <code>realloc</code> except if the 87function is required to allocate new storage and this fails. In this 88case <code>reallocf</code> will free the original object passed in whereas 89<code>realloc</code> will not. 90 91 <p>The <code>memalign</code> function returns a block of size <var>nbytes</var> aligned 92to a <var>align</var> boundary. The <var>align</var> argument must be a power of 93two. 94 95 <p>The <code>malloc_usable_size</code> function takes a pointer to a block 96allocated by <code>malloc</code>. It returns the amount of space that is 97available in the block. This may or may not be more than the size 98requested from <code>malloc</code>, due to alignment or minimum size 99constraints. 100 101 <p>The alternate functions <code>_malloc_r</code>, <code>_realloc_r</code>, <code>_reallocf_r</code>, 102<code>_free_r</code>, <code>_memalign_r</code>, and <code>_malloc_usable_size_r</code> are reentrant 103versions. The extra argument <var>reent</var> is a pointer to a reentrancy structure. 104 105 <p>If you have multiple threads of execution which may call any of these 106routines, or if any of these routines may be called reentrantly, then 107you must provide implementations of the <code>__malloc_lock</code> and 108<code>__malloc_unlock</code> functions for your system. See the documentation 109for those functions. 110 111 <p>These functions operate by calling the function <code>_sbrk_r</code> or 112<code>sbrk</code>, which allocates space. You may need to provide one of these 113functions for your system. <code>_sbrk_r</code> is called with a positive 114value to allocate more space, and with a negative value to release 115previously allocated space if it is no longer required. 116See <a href="Stubs.html#Stubs">Stubs</a>. 117 118 <p><br> 119<strong>Returns</strong><br> 120<code>malloc</code> returns a pointer to the newly allocated space, if 121successful; otherwise it returns <code>NULL</code>. If your application needs 122to generate empty objects, you may use <code>malloc(0)</code> for this purpose. 123 124 <p><code>realloc</code> returns a pointer to the new block of memory, or <code>NULL</code> 125if a new block could not be allocated. <code>NULL</code> is also the result 126when you use `<code>realloc(</code><var>aptr</var><code>,0)</code>' (which has the same effect as 127`<code>free(</code><var>aptr</var><code>)</code>'). You should always check the result of 128<code>realloc</code>; successful reallocation is not guaranteed even when 129you request a smaller object. 130 131 <p><code>free</code> does not return a result. 132 133 <p><code>memalign</code> returns a pointer to the newly allocated space. 134 135 <p><code>malloc_usable_size</code> returns the usable size. 136 137 <p><br> 138<strong>Portability</strong><br> 139<code>malloc</code>, <code>realloc</code>, and <code>free</code> are specified by the ANSI C 140standard, but other conforming implementations of <code>malloc</code> may 141behave differently when <var>nbytes</var> is zero. 142 143 <p><code>memalign</code> is part of SVR4. 144 145 <p><code>malloc_usable_size</code> is not portable. 146 147 <p>Supporting OS subroutines required: <code>sbrk</code>. 148<br> 149 150 </body></html> 151 152