| <html lang="en"> | |
| <head> | |
| <title>malloc - Untitled</title> | |
| <meta http-equiv="Content-Type" content="text/html"> | |
| <meta name="description" content="Untitled"> | |
| <meta name="generator" content="makeinfo 4.13"> | |
| <link title="Top" rel="start" href="index.html#Top"> | |
| <link rel="up" href="Stdlib.html#Stdlib" title="Stdlib"> | |
| <link rel="prev" href="lldiv.html#lldiv" title="lldiv"> | |
| <link rel="next" href="mallinfo.html#mallinfo" title="mallinfo"> | |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> | |
| <meta http-equiv="Content-Style-Type" content="text/css"> | |
| <style type="text/css"><!-- | |
| pre.display { font-family:inherit } | |
| pre.format { font-family:inherit } | |
| pre.smalldisplay { font-family:inherit; font-size:smaller } | |
| pre.smallformat { font-family:inherit; font-size:smaller } | |
| pre.smallexample { font-size:smaller } | |
| pre.smalllisp { font-size:smaller } | |
| span.sc { font-variant:small-caps } | |
| span.roman { font-family:serif; font-weight:normal; } | |
| span.sansserif { font-family:sans-serif; font-weight:normal; } | |
| --></style> | |
| </head> | |
| <body> | |
| <div class="node"> | |
| <a name="malloc"></a> | |
| <p> | |
| Next: <a rel="next" accesskey="n" href="mallinfo.html#mallinfo">mallinfo</a>, | |
| Previous: <a rel="previous" accesskey="p" href="lldiv.html#lldiv">lldiv</a>, | |
| Up: <a rel="up" accesskey="u" href="Stdlib.html#Stdlib">Stdlib</a> | |
| <hr> | |
| </div> | |
| <h3 class="section">2.23 <code>malloc</code>, <code>realloc</code>, <code>free</code>—manage memory</h3> | |
| <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> | |
| <pre class="example"> #include <stdlib.h> | |
| void *malloc(size_t <var>nbytes</var>); | |
| void *realloc(void *<var>aptr</var>, size_t <var>nbytes</var>); | |
| void *reallocf(void *<var>aptr</var>, size_t <var>nbytes</var>); | |
| void free(void *<var>aptr</var>); | |
| void *memalign(size_t <var>align</var>, size_t <var>nbytes</var>); | |
| size_t malloc_usable_size(void *<var>aptr</var>); | |
| void *_malloc_r(void *<var>reent</var>, size_t <var>nbytes</var>); | |
| void *_realloc_r(void *<var>reent</var>, | |
| void *<var>aptr</var>, size_t <var>nbytes</var>); | |
| void *_reallocf_r(void *<var>reent</var>, | |
| void *<var>aptr</var>, size_t <var>nbytes</var>); | |
| void _free_r(void *<var>reent</var>, void *<var>aptr</var>); | |
| void *_memalign_r(void *<var>reent</var>, | |
| size_t <var>align</var>, size_t <var>nbytes</var>); | |
| size_t _malloc_usable_size_r(void *<var>reent</var>, void *<var>aptr</var>); | |
| </pre> | |
| <p><strong>Description</strong><br> | |
| These functions manage a pool of system memory. | |
| <p>Use <code>malloc</code> to request allocation of an object with at least | |
| <var>nbytes</var> bytes of storage available. If the space is available, | |
| <code>malloc</code> returns a pointer to a newly allocated block as its result. | |
| <p>If you already have a block of storage allocated by <code>malloc</code>, but | |
| you no longer need all the space allocated to it, you can make it | |
| smaller by calling <code>realloc</code> with both the object pointer and the | |
| new desired size as arguments. <code>realloc</code> guarantees that the | |
| contents of the smaller object match the beginning of the original object. | |
| <p>Similarly, if you need more space for an object, use <code>realloc</code> to | |
| request the larger size; again, <code>realloc</code> guarantees that the | |
| beginning of the new, larger object matches the contents of the | |
| original object. | |
| <p>When you no longer need an object originally allocated by <code>malloc</code> | |
| or <code>realloc</code> (or the related function <code>calloc</code>), return it to the | |
| memory storage pool by calling <code>free</code> with the address of the object | |
| as the argument. You can also use <code>realloc</code> for this purpose by | |
| calling it with <code>0</code> as the <var>nbytes</var> argument. | |
| <p>The <code>reallocf</code> function behaves just like <code>realloc</code> except if the | |
| function is required to allocate new storage and this fails. In this | |
| case <code>reallocf</code> will free the original object passed in whereas | |
| <code>realloc</code> will not. | |
| <p>The <code>memalign</code> function returns a block of size <var>nbytes</var> aligned | |
| to a <var>align</var> boundary. The <var>align</var> argument must be a power of | |
| two. | |
| <p>The <code>malloc_usable_size</code> function takes a pointer to a block | |
| allocated by <code>malloc</code>. It returns the amount of space that is | |
| available in the block. This may or may not be more than the size | |
| requested from <code>malloc</code>, due to alignment or minimum size | |
| constraints. | |
| <p>The alternate functions <code>_malloc_r</code>, <code>_realloc_r</code>, <code>_reallocf_r</code>, | |
| <code>_free_r</code>, <code>_memalign_r</code>, and <code>_malloc_usable_size_r</code> are reentrant | |
| versions. The extra argument <var>reent</var> is a pointer to a reentrancy structure. | |
| <p>If you have multiple threads of execution which may call any of these | |
| routines, or if any of these routines may be called reentrantly, then | |
| you must provide implementations of the <code>__malloc_lock</code> and | |
| <code>__malloc_unlock</code> functions for your system. See the documentation | |
| for those functions. | |
| <p>These functions operate by calling the function <code>_sbrk_r</code> or | |
| <code>sbrk</code>, which allocates space. You may need to provide one of these | |
| functions for your system. <code>_sbrk_r</code> is called with a positive | |
| value to allocate more space, and with a negative value to release | |
| previously allocated space if it is no longer required. | |
| See <a href="Stubs.html#Stubs">Stubs</a>. | |
| <p><br> | |
| <strong>Returns</strong><br> | |
| <code>malloc</code> returns a pointer to the newly allocated space, if | |
| successful; otherwise it returns <code>NULL</code>. If your application needs | |
| to generate empty objects, you may use <code>malloc(0)</code> for this purpose. | |
| <p><code>realloc</code> returns a pointer to the new block of memory, or <code>NULL</code> | |
| if a new block could not be allocated. <code>NULL</code> is also the result | |
| when you use `<code>realloc(</code><var>aptr</var><code>,0)</code>' (which has the same effect as | |
| `<code>free(</code><var>aptr</var><code>)</code>'). You should always check the result of | |
| <code>realloc</code>; successful reallocation is not guaranteed even when | |
| you request a smaller object. | |
| <p><code>free</code> does not return a result. | |
| <p><code>memalign</code> returns a pointer to the newly allocated space. | |
| <p><code>malloc_usable_size</code> returns the usable size. | |
| <p><br> | |
| <strong>Portability</strong><br> | |
| <code>malloc</code>, <code>realloc</code>, and <code>free</code> are specified by the ANSI C | |
| standard, but other conforming implementations of <code>malloc</code> may | |
| behave differently when <var>nbytes</var> is zero. | |
| <p><code>memalign</code> is part of SVR4. | |
| <p><code>malloc_usable_size</code> is not portable. | |
| <p>Supporting OS subroutines required: <code>sbrk</code>. | |
| <br> | |
| </body></html> | |