'\" te
.\" Copyright 2014 Nexenta Systems, Inc.  All rights reserved.
.\" Copyright 2022 Joyent, Inc.
.\"  Copyright 1989 AT&T
.\"  Copyright (c) 2006, Sun Microsystems, Inc.,  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH KMEM_ALLOC 9F "Nov 20, 2019"
.SH NAME
kmem_alloc, kmem_zalloc, kmem_free \- allocate kernel memory
.SH SYNOPSIS
.nf
#include <sys/types.h>
#include <sys/kmem.h>



\fBvoid *\fR\fBkmem_alloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR \fIflag\fR);
.fi

.LP
.nf
\fBvoid *\fR\fBkmem_zalloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR \fIflag\fR);
.fi

.LP
.nf
\fBvoid\fR \fBkmem_free\fR(\fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
.fi

.SH INTERFACE LEVEL
Architecture independent level 1 (DDI/DKI).
.SH PARAMETERS
.ne 2
.na
\fB\fIsize\fR\fR
.ad
.RS 8n
Number of bytes to allocate.
.RE

.sp
.ne 2
.na
\fB\fIflag\fR\fR
.ad
.RS 8n
Determines whether caller can sleep for memory. Possible flags are
\fBKM_SLEEP\fR to allow sleeping until memory is available, \fBKM_NOSLEEP\fR
to return \fINULL\fR if memory is not available even after some reclamation
attempts, and \fBKM_NOSLEEP_LAZY\fR to return \fINULL\fR without reclamation
attempts.  \fBKM_NOSLEEP_LAZY\fR is actually two flags combined:
(\fBKM_NOSLEEP\fR | \fBKM_NORMALPRI\fR), the latter flag indicating not to
attempt reclamation before giving up and returning NULL.  If any mention of
\fBKM_NOSLEEP\fR appears in this man page by itself, it applies equally to
\fBKM_NOSLEEP_LAZY\fR as well.
.RE

.sp
.ne 2
.na
\fB\fIbuf\fR\fR
.ad
.RS 8n
Pointer to allocated memory.
.RE

.SH DESCRIPTION
The \fBkmem_alloc()\fR function allocates \fIsize\fR bytes of kernel memory and
returns a pointer to the allocated memory. The allocated memory is at least
double-word aligned, so it can hold any C data structure. No greater alignment
can be assumed. \fIflag\fR determines whether the caller can sleep for memory.
\fBKM_SLEEP\fR allocations may sleep but are guaranteed to succeed.
\fBKM_NOSLEEP\fR and \fBKM_NOSLEEP_LAZY\fR allocations are guaranteed not to
sleep but may fail (return \fINULL\fR) if no memory is currently
available. \fBKM_NOSLEEP\fR will first attempt to aggressively reclaim memory
from otherwise unused blocks, while \fBKM_NOSLEEP_LAZY\fR will not attempt any
reclamation. The initial contents of memory allocated using
\fBkmem_alloc()\fR are random garbage.
.sp
.LP
The \fBkmem_zalloc()\fR function is like \fBkmem_alloc()\fR but returns
zero-filled memory.
.sp
.LP
The \fBkmem_free()\fR function frees previously allocated kernel memory. The
buffer address and size must exactly match the original allocation. Memory
cannot be returned piecemeal.
.SH RETURN VALUES
If successful, \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR return a pointer to
the allocated memory. If \fBKM_NOSLEEP\fR is set and memory cannot be
allocated without sleeping, \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR return
\fINULL\fR.
.SH CONTEXT
The \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR functions can be called from
interrupt context only if the \fBKM_NOSLEEP\fR flag is set. They can be
called from user context with any valid \fIflag\fR. The \fBkmem_free()\fR
function can be called from from user, interrupt, or kernel context.
.SH SEE ALSO
\fBcopyout\fR(9F), \fBfreerbuf\fR(9F), \fBgetrbuf\fR(9F)
.sp
.LP
\fIWriting Device Drivers\fR
.SH WARNINGS
Memory allocated using \fBkmem_alloc()\fR is not paged. Available memory is
therefore limited by the total physical memory on the system. It is also
limited by the available kernel virtual address space, which is often the more
restrictive constraint on large-memory configurations.
.sp
.LP
Excessive use of kernel memory is likely to affect overall system performance.
Overcommitment of kernel memory will cause the system to hang or panic.
.sp
.LP
Misuse of the kernel memory allocator, such as writing past the end of a
buffer, using a buffer after freeing it, freeing a buffer twice, or freeing a
null or invalid pointer, will corrupt the kernel heap and may cause the system
to corrupt data or panic.
.sp
.LP
The initial contents of memory allocated using \fBkmem_alloc()\fR are random
garbage. This random garbage may include secure kernel data. Therefore,
uninitialized kernel memory should be handled carefully. For example, never
\fBcopyout\fR(9F) a potentially uninitialized buffer.
.SH NOTES
\fBkmem_alloc(0\fR, \fIflag\fR\fB)\fR always returns \fINULL\fR, but
if \fBKM_SLEEP\fR is set, this behavior is considered to be deprecated;
the system may be configured to explicitly panic in this case in lieu
of returning \fINULL\fR.
\fBkmem_free(NULL, 0)\fR is legal, however.