<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head> <link rel="STYLESHEET" href="api.css" type='text/css' /> <link rel="SHORTCUT ICON" href="../icons/pyfav.gif" /> <link rel='start' href='../index.html' title='Python Documentation Index' /> <link rel="first" href="api.html" title='Python/C API Reference Manual' /> <link rel='contents' href='contents.html' title="Contents" /> <link rel='index' href='genindex.html' title='Index' /> <link rel='last' href='about.html' title='About this document...' /> <link rel='help' href='about.html' title='About this document...' /> <LINK rel="next" href="memoryExamples.html"> <LINK rel="prev" href="memoryOverview.html"> <LINK rel="parent" href="memory.html"> <LINK rel="next" href="memoryExamples.html"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <meta name='aesop' content='information' /> <META name="description" content="Memory Interface "> <META name="keywords" content="api"> <META name="resource-type" content="document"> <META name="distribution" content="global"> <title>9.2 Memory Interface </title> </head> <body> <DIV CLASS="navigation"> <div id='top-navigation-panel'> <table align="center" width="100%" cellpadding="0" cellspacing="2"> <tr> <td class='online-navigation'><a rel="prev" title="9.1 Overview" href="memoryOverview.html"><img src='../icons/previous.png' border='0' height='32' alt='Previous Page' width='32' /></A></td> <td class='online-navigation'><a rel="parent" title="9. Memory Management" href="memory.html"><img src='../icons/up.png' border='0' height='32' alt='Up One Level' width='32' /></A></td> <td class='online-navigation'><a rel="next" title="9.3 Examples" href="memoryExamples.html"><img src='../icons/next.png' border='0' height='32' alt='Next Page' width='32' /></A></td> <td align="center" width="100%">Python/C API Reference Manual</td> <td class='online-navigation'><a rel="contents" title="Table of Contents" href="contents.html"><img src='../icons/contents.png' border='0' height='32' alt='Contents' width='32' /></A></td> <td class='online-navigation'><img src='../icons/blank.png' border='0' height='32' alt='' width='32' /></td> <td class='online-navigation'><a rel="index" title="Index" href="genindex.html"><img src='../icons/index.png' border='0' height='32' alt='Index' width='32' /></A></td> </tr></table> <div class='online-navigation'> <b class="navlabel">Previous:</b> <a class="sectref" rel="prev" href="memoryOverview.html">9.1 Overview</A> <b class="navlabel">Up:</b> <a class="sectref" rel="parent" href="memory.html">9. Memory Management</A> <b class="navlabel">Next:</b> <a class="sectref" rel="next" href="memoryExamples.html">9.3 Examples</A> </div> <hr /></div> </DIV> <!--End of Navigation Panel--> <H1><A NAME="SECTION0011200000000000000000"><!--x--></A><A NAME="memoryInterface"><!--z--></A> <BR> 9.2 Memory Interface </H1> <P> The following function sets, modeled after the ANSI C standard, but specifying behavior when requesting zero bytes, are available for allocating and releasing memory from the Python heap: <P> <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void* <b><tt id='l2h-798' class="cfunction">PyMem_Malloc</tt></b>(</nobr></td><td>size_t <var>n</var>)</td></tr></table></dt> <dd> Allocates <var>n</var> bytes and returns a pointer of type <tt class="ctype">void*</tt> to the allocated memory, or <tt class="constant">NULL</tt> if the request fails. Requesting zero bytes returns a distinct non-<tt class="constant">NULL</tt> pointer if possible, as if <tt class="cfunction">PyMem_Malloc(1)</tt> had been called instead. The memory will not have been initialized in any way. </dd></dl> <P> <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void* <b><tt id='l2h-799' class="cfunction">PyMem_Realloc</tt></b>(</nobr></td><td>void *<var>p</var>, size_t <var>n</var>)</td></tr></table></dt> <dd> Resizes the memory block pointed to by <var>p</var> to <var>n</var> bytes. The contents will be unchanged to the minimum of the old and the new sizes. If <var>p</var> is <tt class="constant">NULL</tt>, the call is equivalent to <tt class="cfunction">PyMem_Malloc(<var>n</var>)</tt>; else if <var>n</var> is equal to zero, the memory block is resized but is not freed, and the returned pointer is non-<tt class="constant">NULL</tt>. Unless <var>p</var> is <tt class="constant">NULL</tt>, it must have been returned by a previous call to <tt class="cfunction">PyMem_Malloc()</tt> or <tt class="cfunction">PyMem_Realloc()</tt>. </dd></dl> <P> <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-800' class="cfunction">PyMem_Free</tt></b>(</nobr></td><td>void *<var>p</var>)</td></tr></table></dt> <dd> Frees the memory block pointed to by <var>p</var>, which must have been returned by a previous call to <tt class="cfunction">PyMem_Malloc()</tt> or <tt class="cfunction">PyMem_Realloc()</tt>. Otherwise, or if <tt class="cfunction">PyMem_Free(p)</tt> has been called before, undefined behavior occurs. If <var>p</var> is <tt class="constant">NULL</tt>, no operation is performed. </dd></dl> <P> The following type-oriented macros are provided for convenience. Note that <var>TYPE</var> refers to any C type. <P> <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr><var>TYPE</var>* <b><tt id='l2h-801' class="cfunction">PyMem_New</tt></b>(</nobr></td><td>TYPE, size_t <var>n</var>)</td></tr></table></dt> <dd> Same as <tt class="cfunction">PyMem_Malloc()</tt>, but allocates <code>(<var>n</var> * sizeof(<var>TYPE</var>))</code> bytes of memory. Returns a pointer cast to <tt class="ctype"><var>TYPE</var>*</tt>. The memory will not have been initialized in any way. </dd></dl> <P> <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr><var>TYPE</var>* <b><tt id='l2h-802' class="cfunction">PyMem_Resize</tt></b>(</nobr></td><td>void *<var>p</var>, TYPE, size_t <var>n</var>)</td></tr></table></dt> <dd> Same as <tt class="cfunction">PyMem_Realloc()</tt>, but the memory block is resized to <code>(<var>n</var> * sizeof(<var>TYPE</var>))</code> bytes. Returns a pointer cast to <tt class="ctype"><var>TYPE</var>*</tt>. </dd></dl> <P> <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-803' class="cfunction">PyMem_Del</tt></b>(</nobr></td><td>void *<var>p</var>)</td></tr></table></dt> <dd> Same as <tt class="cfunction">PyMem_Free()</tt>. </dd></dl> <P> In addition, the following macro sets are provided for calling the Python memory allocator directly, without involving the C API functions listed above. However, note that their use does not preserve binary compatibility accross Python versions and is therefore deprecated in extension modules. <P> <tt class="cfunction">PyMem_MALLOC()</tt>, <tt class="cfunction">PyMem_REALLOC()</tt>, <tt class="cfunction">PyMem_FREE()</tt>. <P> <tt class="cfunction">PyMem_NEW()</tt>, <tt class="cfunction">PyMem_RESIZE()</tt>, <tt class="cfunction">PyMem_DEL()</tt>. <P> <DIV CLASS="navigation"> <div class='online-navigation'><hr /> <table align="center" width="100%" cellpadding="0" cellspacing="2"> <tr> <td class='online-navigation'><a rel="prev" title="9.1 Overview" rel="prev" title="9.1 Overview" href="memoryOverview.html"><img src='../icons/previous.png' border='0' height='32' alt='Previous Page' width='32' /></A></td> <td class='online-navigation'><a rel="parent" title="9. Memory Management" rel="parent" title="9. Memory Management" href="memory.html"><img src='../icons/up.png' border='0' height='32' alt='Up One Level' width='32' /></A></td> <td class='online-navigation'><a rel="next" title="9.3 Examples" rel="next" title="9.3 Examples" href="memoryExamples.html"><img src='../icons/next.png' border='0' height='32' alt='Next Page' width='32' /></A></td> <td align="center" width="100%">Python/C API Reference Manual</td> <td class='online-navigation'><a rel="contents" title="Table of Contents" rel="contents" title="Table of Contents" href="contents.html"><img src='../icons/contents.png' border='0' height='32' alt='Contents' width='32' /></A></td> <td class='online-navigation'><img src='../icons/blank.png' border='0' height='32' alt='' width='32' /></td> <td class='online-navigation'><a rel="index" title="Index" rel="index" title="Index" href="genindex.html"><img src='../icons/index.png' border='0' height='32' alt='Index' width='32' /></A></td> </tr></table> <div class='online-navigation'> <b class="navlabel">Previous:</b> <a class="sectref" rel="prev" href="memoryOverview.html">9.1 Overview</A> <b class="navlabel">Up:</b> <a class="sectref" rel="parent" href="memory.html">9. Memory Management</A> <b class="navlabel">Next:</b> <a class="sectref" rel="next" href="memoryExamples.html">9.3 Examples</A> </div> </div> <hr /> <span class="release-info">Release 2.3.4, documentation updated on May 20, 2004.</span> </DIV> <!--End of Navigation Panel--> <ADDRESS> See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. </ADDRESS> </BODY> </HTML>
