78 lines
2.7 KiB
Plaintext
78 lines
2.7 KiB
Plaintext
.if n .pH ddi.rm/d3/gen/kmem_zalloc @(#)kmem_zalloc 43.12 of 12/4/92
|
|
.\" Copyright 1992, 1991 UNIX System Laboratories, Inc.
|
|
.TH kmem_zalloc D3
|
|
.SH NAME
|
|
\f4kmem_zalloc\f1 \- allocate and clear space from kernel free memory
|
|
.IX "\f4kmem_zalloc\fP(D3)"
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.na
|
|
.ft 4
|
|
#include <sys/types.h>
|
|
#include <sys/kmem.h>
|
|
#include <sys/ddi.h>
|
|
.sp 0.4
|
|
void *kmem_zalloc(size_t \f2size\fP, int \f2flag\fP);
|
|
.ft 1
|
|
.ad
|
|
.fi
|
|
.SS Arguments
|
|
.RS 0
|
|
.IP "\f2size\f1" 10n
|
|
Number of bytes to allocate.
|
|
.IP "\f2flag\f1" 10n
|
|
Specifies whether the caller is willing to sleep waiting for memory,
|
|
also other flags accepted by \f4kmem_alloc\fP.
|
|
.RE
|
|
.SH DESCRIPTION
|
|
\f4kmem_zalloc\f1 allocates \f2size\f1 bytes of kernel
|
|
memory, clears the memory by filling it with zeros,
|
|
and returns a pointer to the allocated memory.
|
|
If \f2flag\f1 is set to \f4KM_SLEEP\f1, the caller will sleep
|
|
if necessary until the specified amount of memory is available.
|
|
If \f2flag\f1 is set to \f4KM_NOSLEEP\f1, the caller will not sleep,
|
|
but \f4kmem_zalloc\f1 will return \f4NULL\f1 if the specified amount
|
|
of memory is not immediately available.
|
|
.SS "Return Values"
|
|
Upon successful completion, \f4kmem_zalloc\f1 returns a pointer to the
|
|
allocated memory.
|
|
If \f4KM_NOSLEEP\f1 is specified and sufficient memory is not immediately
|
|
available, \f4kmem_zalloc\f1 returns a \f4NULL\f1 pointer.
|
|
If \f2size\f1 is set to \f40\f1, \f4kmem_zalloc\f1 returns \f4NULL\f1
|
|
regardless of the value of \f2flag\f1.
|
|
.SH USAGE
|
|
Kernel memory is a limited resource and should be used judiciously.
|
|
Memory allocated using \f4kmem_zalloc\f1 should be freed as soon as
|
|
possible.
|
|
Drivers should not use local freelists for memory or similar schemes
|
|
that cause the memory to be held for longer than necessary.
|
|
.P
|
|
Since holding memory allocated using \f4kmem_zalloc\f1 for extended periods
|
|
of time (e.g allocating memory at system startup and never freeing it)
|
|
can have an adverse effect on overall memory usage and system performance,
|
|
memory needed for such extended periods should be statically allocated whenever
|
|
possible.
|
|
.P
|
|
The address returned by a successful call to \f4kmem_zalloc\f1 is
|
|
word-aligned.
|
|
.SS Level
|
|
Initialization or Base if \f2flag\f1 is set to \f4KM_SLEEP\f1.
|
|
.P
|
|
Initialization, Base or Interrupt if \f2flag\f1 is set to \f4KM_NOSLEEP\f1.
|
|
.SS "Synchronization Constraints"
|
|
May sleep if \f2flag\f1 is set to \f4KM_SLEEP\f1.
|
|
.P
|
|
Driver-defined basic locks, read/write locks, and sleep locks
|
|
may be held across calls to this function
|
|
if \f2flag\f1 is \f4KM_NOSLEEP\f1,
|
|
but may not be held if \f2flag\f1 is \f4KM_SLEEP\f1.
|
|
.P
|
|
Driver-defined sleep locks
|
|
may be held across calls to this function
|
|
regardless of the value of \f2flag\f1.
|
|
.SH REFERENCES
|
|
.na
|
|
\f4kmem_alloc\fP(D3),
|
|
\f4kmem_free\fP(D3)
|
|
.ad
|