1 '\" te
2 .\" Copyright 2014 Nexenta Systems, Inc. All rights reserved.
3 .\" Copyright 1989 AT&T
4 .\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved
5 .\" 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.
6 .\" 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.
7 .\" 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]
8 .TH KMEM_ALLOC 9F "Oct 22, 2014"
9 .SH NAME
10 kmem_alloc, kmem_zalloc, kmem_free \- allocate kernel memory
11 .SH SYNOPSIS
12 .LP
13 .nf
14 #include <sys/types.h>
15 #include <sys/kmem.h>
16
17
18
19 \fBvoid *\fR\fBkmem_alloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR \fIflag\fR);
20 .fi
21
22 .LP
23 .nf
24 \fBvoid *\fR\fBkmem_zalloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR \fIflag\fR);
25 .fi
26
27 .LP
28 .nf
29 \fBvoid\fR \fBkmem_free\fR(\fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
30 .fi
31
32 .SH INTERFACE LEVEL
33 .sp
34 .LP
35 Architecture independent level 1 (DDI/DKI).
36 .SH PARAMETERS
37 .sp
38 .ne 2
39 .na
40 \fB\fIsize\fR\fR
41 .ad
42 .RS 8n
43 Number of bytes to allocate.
44 .RE
45
46 .sp
47 .ne 2
48 .na
49 \fB\fIflag\fR\fR
50 .ad
51 .RS 8n
52 Determines whether caller can sleep for memory. Possible flags are
53 \fBKM_SLEEP\fR to allow sleeping until memory is available, or \fBKM_NOSLEEP\fR
54 to return \fINULL\fR immediately if memory is not available.
55 .RE
56
57 .sp
58 .ne 2
59 .na
60 \fB\fIbuf\fR\fR
61 .ad
62 .RS 8n
63 Pointer to allocated memory.
64 .RE
65
66 .SH DESCRIPTION
67 .sp
68 .LP
69 The \fBkmem_alloc()\fR function allocates \fIsize\fR bytes of kernel memory and
70 returns a pointer to the allocated memory. The allocated memory is at least
71 double-word aligned, so it can hold any C data structure. No greater alignment
72 can be assumed. \fIflag\fR determines whether the caller can sleep for memory.
73 \fBKM_SLEEP\fR allocations may sleep but are guaranteed to succeed.
74 \fBKM_NOSLEEP\fR allocations are guaranteed not to sleep but may fail (return
75 \fINULL\fR) if no memory is currently available. The initial contents of memory
76 allocated using \fBkmem_alloc()\fR are random garbage.
77 .sp
78 .LP
79 The \fBkmem_zalloc()\fR function is like \fBkmem_alloc()\fR but returns
80 zero-filled memory.
81 .sp
82 .LP
83 The \fBkmem_free()\fR function frees previously allocated kernel memory. The
84 buffer address and size must exactly match the original allocation. Memory
85 cannot be returned piecemeal.
86 .SH RETURN VALUES
87 .sp
88 .LP
89 If successful, \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR return a pointer to
90 the allocated memory. If \fBKM_NOSLEEP\fR is set and memory cannot be allocated
91 without sleeping, \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR return \fINULL\fR.
92 .SH CONTEXT
93 .sp
94 .LP
95 The \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR functions can be called from
96 interrupt context only if the \fBKM_NOSLEEP\fR flag is set. They can be called
97 from user context with any valid \fIflag\fR. The \fBkmem_free()\fR function can
98 be called from from user, interrupt, or kernel context.
99 .SH SEE ALSO
100 .sp
101 .LP
102 \fBcopyout\fR(9F), \fBfreerbuf\fR(9F), \fBgetrbuf\fR(9F)
103 .sp
104 .LP
105 \fIWriting Device Drivers\fR
106 .SH WARNINGS
107 .sp
108 .LP
109 Memory allocated using \fBkmem_alloc()\fR is not paged. Available memory is
110 therefore limited by the total physical memory on the system. It is also
111 limited by the available kernel virtual address space, which is often the more
112 restrictive constraint on large-memory configurations.
113 .sp
114 .LP
115 Excessive use of kernel memory is likely to affect overall system performance.
116 Overcommitment of kernel memory will cause the system to hang or panic.
117 .sp
118 .LP
119 Misuse of the kernel memory allocator, such as writing past the end of a
120 buffer, using a buffer after freeing it, freeing a buffer twice, or freeing a
121 null or invalid pointer, will corrupt the kernel heap and may cause the system
122 to corrupt data or panic.
123 .sp
124 .LP
125 The initial contents of memory allocated using \fBkmem_alloc()\fR are random
126 garbage. This random garbage may include secure kernel data. Therefore,
127 uninitialized kernel memory should be handled carefully. For example, never
128 \fBcopyout\fR(9F) a potentially uninitialized buffer.
129 .SH NOTES
130 .sp
131 .LP
132 \fBkmem_alloc(0\fR, \fIflag\fR\fB)\fR always returns \fINULL\fR.
133 \fBkmem_free(NULL, 0)\fR is legal.
|
1 '\" te
2 .\" Copyright 2014 Nexenta Systems, Inc. All rights reserved.
3 .\" Copyright 1989 AT&T
4 .\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved
5 .\" 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.
6 .\" 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.
7 .\" 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]
8 .TH KMEM_ALLOC 9F "Nov 20, 2019"
9 .SH NAME
10 kmem_alloc, kmem_zalloc, kmem_free \- allocate kernel memory
11 .SH SYNOPSIS
12 .nf
13 #include <sys/types.h>
14 #include <sys/kmem.h>
15
16
17
18 \fBvoid *\fR\fBkmem_alloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR \fIflag\fR);
19 .fi
20
21 .LP
22 .nf
23 \fBvoid *\fR\fBkmem_zalloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR \fIflag\fR);
24 .fi
25
26 .LP
27 .nf
28 \fBvoid\fR \fBkmem_free\fR(\fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
29 .fi
30
31 .SH INTERFACE LEVEL
32 Architecture independent level 1 (DDI/DKI).
33 .SH PARAMETERS
34 .ne 2
35 .na
36 \fB\fIsize\fR\fR
37 .ad
38 .RS 8n
39 Number of bytes to allocate.
40 .RE
41
42 .sp
43 .ne 2
44 .na
45 \fB\fIflag\fR\fR
46 .ad
47 .RS 8n
48 Determines whether caller can sleep for memory. Possible flags are
49 \fBKM_SLEEP\fR to allow sleeping until memory is available, or \fBKM_NOSLEEP\fR
50 to return \fINULL\fR immediately if memory is not available.
51 .RE
52
53 .sp
54 .ne 2
55 .na
56 \fB\fIbuf\fR\fR
57 .ad
58 .RS 8n
59 Pointer to allocated memory.
60 .RE
61
62 .SH DESCRIPTION
63 The \fBkmem_alloc()\fR function allocates \fIsize\fR bytes of kernel memory and
64 returns a pointer to the allocated memory. The allocated memory is at least
65 double-word aligned, so it can hold any C data structure. No greater alignment
66 can be assumed. \fIflag\fR determines whether the caller can sleep for memory.
67 \fBKM_SLEEP\fR allocations may sleep but are guaranteed to succeed.
68 \fBKM_NOSLEEP\fR allocations are guaranteed not to sleep but may fail (return
69 \fINULL\fR) if no memory is currently available. The initial contents of memory
70 allocated using \fBkmem_alloc()\fR are random garbage.
71 .sp
72 .LP
73 The \fBkmem_zalloc()\fR function is like \fBkmem_alloc()\fR but returns
74 zero-filled memory.
75 .sp
76 .LP
77 The \fBkmem_free()\fR function frees previously allocated kernel memory. The
78 buffer address and size must exactly match the original allocation. Memory
79 cannot be returned piecemeal.
80 .SH RETURN VALUES
81 If successful, \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR return a pointer to
82 the allocated memory. If \fBKM_NOSLEEP\fR is set and memory cannot be allocated
83 without sleeping, \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR return \fINULL\fR.
84 .SH CONTEXT
85 The \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR functions can be called from
86 interrupt context only if the \fBKM_NOSLEEP\fR flag is set. They can be called
87 from user context with any valid \fIflag\fR. The \fBkmem_free()\fR function can
88 be called from from user, interrupt, or kernel context.
89 .SH SEE ALSO
90 \fBcopyout\fR(9F), \fBfreerbuf\fR(9F), \fBgetrbuf\fR(9F)
91 .sp
92 .LP
93 \fIWriting Device Drivers\fR
94 .SH WARNINGS
95 Memory allocated using \fBkmem_alloc()\fR is not paged. Available memory is
96 therefore limited by the total physical memory on the system. It is also
97 limited by the available kernel virtual address space, which is often the more
98 restrictive constraint on large-memory configurations.
99 .sp
100 .LP
101 Excessive use of kernel memory is likely to affect overall system performance.
102 Overcommitment of kernel memory will cause the system to hang or panic.
103 .sp
104 .LP
105 Misuse of the kernel memory allocator, such as writing past the end of a
106 buffer, using a buffer after freeing it, freeing a buffer twice, or freeing a
107 null or invalid pointer, will corrupt the kernel heap and may cause the system
108 to corrupt data or panic.
109 .sp
110 .LP
111 The initial contents of memory allocated using \fBkmem_alloc()\fR are random
112 garbage. This random garbage may include secure kernel data. Therefore,
113 uninitialized kernel memory should be handled carefully. For example, never
114 \fBcopyout\fR(9F) a potentially uninitialized buffer.
115 .SH NOTES
116 \fBkmem_alloc(0\fR, \fIflag\fR\fB)\fR always returns \fINULL\fR, but
117 if \fBKM_SLEEP\fR is set, this behavior is considered to be deprecated;
118 the system may be configured to explicitly panic in this case in lieu
119 of returning \fINULL\fR.
120 \fBkmem_free(NULL, 0)\fR is legal, however.
|