diff options
Diffstat (limited to 'static/freebsd/man9/malloc.9 4.html')
| -rw-r--r-- | static/freebsd/man9/malloc.9 4.html | 332 |
1 files changed, 0 insertions, 332 deletions
diff --git a/static/freebsd/man9/malloc.9 4.html b/static/freebsd/man9/malloc.9 4.html deleted file mode 100644 index 2676cb88..00000000 --- a/static/freebsd/man9/malloc.9 4.html +++ /dev/null @@ -1,332 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">MALLOC(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">MALLOC(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">malloc</code>, - <code class="Nm">mallocarray</code>, <code class="Nm">free</code>, - <code class="Nm">zfree</code>, <code class="Nm">realloc</code>, - <code class="Nm">reallocf</code>, - <code class="Nm">malloc_usable_size</code>, - <code class="Nm">malloc_aligned</code>, <code class="Nm">malloc_exec</code>, - <code class="Nm">MALLOC_DECLARE</code>, - <code class="Nm">MALLOC_DEFINE</code>, - <code class="Nm">malloc_domainset</code>, - <code class="Nm">malloc_domainset_aligned</code>, - <code class="Nm">malloc_domainset_exec</code>, - <code class="Nm">mallocarray_domainset</code> — - <span class="Nd">kernel memory management routines</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/types.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/malloc.h</a>></code></p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">malloc</code>(<var class="Fa" style="white-space: nowrap;">size_t - size</var>, <var class="Fa" style="white-space: nowrap;">struct malloc_type - *type</var>, <var class="Fa" style="white-space: nowrap;">int - flags</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">mallocarray</code>(<var class="Fa" style="white-space: nowrap;">size_t - nmemb</var>, <var class="Fa" style="white-space: nowrap;">size_t size</var>, - <var class="Fa" style="white-space: nowrap;">struct malloc_type *type</var>, - <var class="Fa" style="white-space: nowrap;">int flags</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">free</code>(<var class="Fa" style="white-space: nowrap;">void - *addr</var>, <var class="Fa" style="white-space: nowrap;">struct malloc_type - *type</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">zfree</code>(<var class="Fa" style="white-space: nowrap;">void - *addr</var>, <var class="Fa" style="white-space: nowrap;">struct malloc_type - *type</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">realloc</code>(<var class="Fa" style="white-space: nowrap;">void - *addr</var>, <var class="Fa" style="white-space: nowrap;">size_t size</var>, - <var class="Fa" style="white-space: nowrap;">struct malloc_type *type</var>, - <var class="Fa" style="white-space: nowrap;">int flags</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">reallocf</code>(<var class="Fa" style="white-space: nowrap;">void - *addr</var>, <var class="Fa" style="white-space: nowrap;">size_t size</var>, - <var class="Fa" style="white-space: nowrap;">struct malloc_type *type</var>, - <var class="Fa" style="white-space: nowrap;">int flags</var>);</p> -<p class="Pp"><var class="Ft">size_t</var> - <br/> - <code class="Fn">malloc_usable_size</code>(<var class="Fa" style="white-space: nowrap;">const - void *addr</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">malloc_aligned</code>(<var class="Fa">size_t size</var>, - <var class="Fa">size_t align</var>, <var class="Fa">struct malloc_type - *type</var>, <var class="Fa">int flags</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">malloc_exec</code>(<var class="Fa" style="white-space: nowrap;">size_t - size</var>, <var class="Fa" style="white-space: nowrap;">struct malloc_type - *type</var>, <var class="Fa" style="white-space: nowrap;">int - flags</var>);</p> -<p class="Pp"><code class="Fn">MALLOC_DECLARE</code>(<var class="Fa" style="white-space: nowrap;">type</var>);</p> -<p class="Pp"><code class="In">#include - <<a class="In">sys/param.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/malloc.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/kernel.h</a>></code></p> -<p class="Pp"><code class="Fn">MALLOC_DEFINE</code>(<var class="Fa" style="white-space: nowrap;">type</var>, - <var class="Fa" style="white-space: nowrap;">shortdesc</var>, - <var class="Fa" style="white-space: nowrap;">longdesc</var>);</p> -<p class="Pp"><code class="In">#include - <<a class="In">sys/param.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/domainset.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/malloc.h</a>></code></p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">malloc_domainset</code>(<var class="Fa" style="white-space: nowrap;">size_t - size</var>, <var class="Fa" style="white-space: nowrap;">struct malloc_type - *type</var>, <var class="Fa" style="white-space: nowrap;">struct domainset - *ds</var>, <var class="Fa" style="white-space: nowrap;">int - flags</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">malloc_domainset_aligned</code>(<var class="Fa">size_t - size</var>, <var class="Fa">size_t align</var>, <var class="Fa">struct - malloc_type *type</var>, <var class="Fa">struct domainset *ds</var>, - <var class="Fa">int flags</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">malloc_domainset_exec</code>(<var class="Fa" style="white-space: nowrap;">size_t - size</var>, <var class="Fa" style="white-space: nowrap;">struct malloc_type - *type</var>, <var class="Fa" style="white-space: nowrap;">struct domainset - *ds</var>, <var class="Fa" style="white-space: nowrap;">int - flags</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">mallocarray_domainset</code>(<var class="Fa" style="white-space: nowrap;">size_t - nmemb</var>, <var class="Fa" style="white-space: nowrap;">size_t size</var>, - <var class="Fa" style="white-space: nowrap;">struct malloc_type *type</var>, - <var class="Fa" style="white-space: nowrap;">struct domainset *ds</var>, - <var class="Fa" style="white-space: nowrap;">int flags</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The - <a class="permalink" href="#malloc"><code class="Fn" id="malloc">malloc</code></a>() - function allocates uninitialized memory in kernel address space for an - object whose size is specified by <var class="Fa">size</var>.</p> -<p class="Pp" id="malloc_domainset">The - <a class="permalink" href="#malloc_domainset"><code class="Fn">malloc_domainset</code></a>() - variant allocates memory from a specific <a class="Xr">numa(4)</a> domain - using the specified domain selection policy. See - <a class="Xr">domainset(9)</a> for some example policies.</p> -<p class="Pp" id="malloc_aligned">The - <a class="permalink" href="#malloc_aligned"><code class="Fn">malloc_aligned</code></a>() - and - <a class="permalink" href="#malloc_domainset_aligned"><code class="Fn" id="malloc_domainset_aligned">malloc_domainset_aligned</code></a>() - variants return allocations aligned as specified by - <var class="Fa">align</var>, which must be non-zero, a power of two, and - less than or equal to the page size.</p> -<p class="Pp" id="malloc_exec">Both - <a class="permalink" href="#malloc_exec"><code class="Fn">malloc_exec</code></a>() - and - <a class="permalink" href="#malloc_domainset_exec"><code class="Fn" id="malloc_domainset_exec">malloc_domainset_exec</code></a>() - can be used to return executable memory. Not all platforms enforce a - distinction between executable and non-executable memory.</p> -<p class="Pp" id="mallocarray">The - <a class="permalink" href="#mallocarray"><code class="Fn">mallocarray</code></a>() - function allocates uninitialized memory in kernel address space for an array - of <var class="Fa">nmemb</var> entries whose size is specified by - <var class="Fa">size</var>.</p> -<p class="Pp" id="mallocarray_domainset">The - <a class="permalink" href="#mallocarray_domainset"><code class="Fn">mallocarray_domainset</code></a>() - variant allocates memory from a specific <a class="Xr">numa(4)</a> domain - using the specified domain selection policy. See - <a class="Xr">domainset(9)</a> for some example policies.</p> -<p class="Pp" id="free">The - <a class="permalink" href="#free"><code class="Fn">free</code></a>() - function releases memory at address <var class="Fa">addr</var> that was - previously allocated by <code class="Fn">malloc</code>() for re-use. The - memory is not zeroed. If <var class="Fa">addr</var> is - <code class="Dv">NULL</code>, then <code class="Fn">free</code>() does - nothing.</p> -<p class="Pp" id="free~2">Like - <a class="permalink" href="#free~2"><code class="Fn">free</code></a>(), the - <a class="permalink" href="#zfree"><code class="Fn" id="zfree">zfree</code></a>() - function releases memory at address <var class="Fa">addr</var> that was - previously allocated by <code class="Fn">malloc</code>() for re-use. - However, <code class="Fn">zfree</code>() will zero the memory before it is - released.</p> -<p class="Pp" id="realloc">The - <a class="permalink" href="#realloc"><code class="Fn">realloc</code></a>() - function changes the size of the previously allocated memory referenced by - <var class="Fa">addr</var> to <var class="Fa">size</var> bytes. The contents - of the memory are unchanged up to the lesser of the new and old sizes. Note - that the returned value may differ from <var class="Fa">addr</var>. If the - requested memory cannot be allocated, <code class="Dv">NULL</code> is - returned and the memory referenced by <var class="Fa">addr</var> is valid - and unchanged. If <var class="Fa">addr</var> is - <code class="Dv">NULL</code>, the <code class="Fn">realloc</code>() function - behaves identically to <code class="Fn">malloc</code>() for the specified - size.</p> -<p class="Pp" id="reallocf">The - <a class="permalink" href="#reallocf"><code class="Fn">reallocf</code></a>() - function is identical to <code class="Fn">realloc</code>() except that it - will free the passed pointer when the requested memory cannot be - allocated.</p> -<p class="Pp" id="malloc_usable_size">The - <a class="permalink" href="#malloc_usable_size"><code class="Fn">malloc_usable_size</code></a>() - function returns the usable size of the allocation pointed to by - <var class="Fa">addr</var>. The return value may be larger than the size - that was requested during allocation.</p> -<p class="Pp" id="malloc~2">Unlike its standard C library counterpart - (<a class="Xr">malloc(3)</a>), the kernel version takes two more arguments. - The <var class="Fa">flags</var> argument further qualifies - <a class="permalink" href="#malloc~2"><code class="Fn">malloc</code></a>()'s - operational characteristics as follows:</p> -<dl class="Bl-tag"> - <dt id="M_ZERO"><a class="permalink" href="#M_ZERO"><code class="Dv">M_ZERO</code></a></dt> - <dd>Causes the allocated memory to be set to all zeros.</dd> - <dt id="M_NODUMP"><a class="permalink" href="#M_NODUMP"><code class="Dv">M_NODUMP</code></a></dt> - <dd>For allocations greater than page size, causes the allocated memory to be - excluded from kernel core dumps.</dd> - <dt id="M_NOWAIT"><a class="permalink" href="#M_NOWAIT"><code class="Dv">M_NOWAIT</code></a></dt> - <dd>Causes <code class="Fn">malloc</code>(), - <code class="Fn">realloc</code>(), and <code class="Fn">reallocf</code>() - to return <code class="Dv">NULL</code> if the request cannot be - immediately fulfilled due to resource shortage. Note that - <code class="Dv">M_NOWAIT</code> is required when running in an interrupt - context.</dd> - <dt id="M_WAITOK"><a class="permalink" href="#M_WAITOK"><code class="Dv">M_WAITOK</code></a></dt> - <dd>Indicates that it is OK to wait for resources. If the request cannot be - immediately fulfilled, the current process is put to sleep to wait for - resources to be released by other processes. The - <code class="Fn">malloc</code>(), <code class="Fn">mallocarray</code>(), - <code class="Fn">realloc</code>(), and <code class="Fn">reallocf</code>() - functions cannot return <code class="Dv">NULL</code> if - <code class="Dv">M_WAITOK</code> is specified. If the multiplication of - <var class="Fa">nmemb</var> and <var class="Fa">size</var> would cause an - integer overflow, the <code class="Fn">mallocarray</code>() function - induces a panic.</dd> - <dt id="M_USE_RESERVE"><a class="permalink" href="#M_USE_RESERVE"><code class="Dv">M_USE_RESERVE</code></a></dt> - <dd>Indicates that the system can use its reserve of memory to satisfy the - request. This option should only be used in combination with - <code class="Dv">M_NOWAIT</code> when an allocation failure cannot be - tolerated by the caller without catastrophic effects on the system.</dd> - <dt id="M_NEVERFREED"><a class="permalink" href="#M_NEVERFREED"><code class="Dv">M_NEVERFREED</code></a></dt> - <dd>This is an internal flag used by the <a class="Xr">uma(9)</a> allocator - and should not be used in regular <code class="Fn">malloc</code>() - invocations. See the description of VM_ALLOC_NOFREE in - <a class="Xr">vm_page_alloc(9)</a> for more details.</dd> -</dl> -<p class="Pp">Exactly one of either <code class="Dv">M_WAITOK</code> or - <code class="Dv">M_NOWAIT</code> must be specified.</p> -<p class="Pp">The <var class="Fa">type</var> argument is used to perform - statistics on memory usage, and for basic sanity checks. It can be used to - identify multiple allocations. The statistics can be examined by - ‘vmstat -m’.</p> -<p class="Pp" id="MALLOC_DECLARE">A <var class="Fa">type</var> is defined using - <var class="Vt">struct malloc_type</var> via the - <a class="permalink" href="#MALLOC_DECLARE"><code class="Fn">MALLOC_DECLARE</code></a>() - and <code class="Fn">MALLOC_DEFINE</code>() macros.</p> -<div class="Bd Pp Bd-indent Li"> -<pre>/* sys/something/foo_extern.h */ - -MALLOC_DECLARE(M_FOOBUF); - -/* sys/something/foo_main.c */ - -MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); - -/* sys/something/foo_subr.c */ - -... -buf = malloc(sizeof(*buf), M_FOOBUF, M_NOWAIT); - -</pre> -</div> -<p class="Pp" id="MALLOC_DEFINE">In order to use - <a class="permalink" href="#MALLOC_DEFINE"><code class="Fn">MALLOC_DEFINE</code></a>(), - one must include - <code class="In"><<a class="In">sys/param.h</a>></code> (instead of - <code class="In"><<a class="In">sys/types.h</a>></code>) and - <code class="In"><<a class="In">sys/kernel.h</a>></code>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="CONTEXT"><a class="permalink" href="#CONTEXT">CONTEXT</a></h1> -<p class="Pp"><code class="Fn">malloc</code>(), - <code class="Fn">realloc</code>() and <code class="Fn">reallocf</code>() may - not be called from fast interrupts handlers. When called from threaded - interrupts, <var class="Fa">flags</var> must contain - <code class="Dv">M_NOWAIT</code>.</p> -<p class="Pp"><code class="Fn">malloc</code>(), - <code class="Fn">realloc</code>() and <code class="Fn">reallocf</code>() may - sleep when called with <code class="Dv">M_WAITOK</code>. - <code class="Fn">free</code>() never sleeps. However, - <code class="Fn">malloc</code>(), <code class="Fn">realloc</code>(), - <code class="Fn">reallocf</code>() and <code class="Fn">free</code>() may - not be called in a critical section or while holding a spin lock.</p> -<p class="Pp">Any calls to <code class="Fn">malloc</code>() (even with - <code class="Dv">M_NOWAIT</code>) or <code class="Fn">free</code>() when - holding a <a class="Xr">vnode(9)</a> interlock, will cause a LOR (Lock Order - Reversal) due to the intertwining of VM Objects and Vnodes.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="IMPLEMENTATION_NOTES"><a class="permalink" href="#IMPLEMENTATION_NOTES">IMPLEMENTATION - NOTES</a></h1> -<p class="Pp">The memory allocator allocates memory in chunks that have size a - power of two for requests up to the size of a page of memory. For larger - requests, one or more pages is allocated. While it should not be relied - upon, this information may be useful for optimizing the efficiency of memory - use.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN - VALUES</a></h1> -<p class="Pp">The <code class="Fn">malloc</code>(), - <code class="Fn">realloc</code>(), and <code class="Fn">reallocf</code>() - functions return a kernel virtual address that is suitably aligned for - storage of any type of object, or <code class="Dv">NULL</code> if the - request could not be satisfied (implying that - <code class="Dv">M_NOWAIT</code> was set).</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1> -<p class="Pp">A kernel compiled with the <code class="Dv">INVARIANTS</code> - configuration option attempts to detect memory corruption caused by such - things as writing outside the allocated area and imbalanced calls to the - <code class="Fn">malloc</code>() and <code class="Fn">free</code>() - functions. Failing consistency checks will cause a panic or a system console - message.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">numa(4)</a>, <a class="Xr">vmstat(8)</a>, - <a class="Xr">contigmalloc(9)</a>, <a class="Xr">domainset(9)</a>, - <a class="Xr">memguard(9)</a>, <a class="Xr">vnode(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp"><code class="Fn">zfree</code>() first appeared in - <span class="Ux">FreeBSD 13.0</span>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">August 4, 2024</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |