plan9fox/sys/man/9/xalloc

82 lines
2 KiB
Plaintext
Raw Normal View History

.TH XALLOC 9
.SH NAME
xalloc, xallocz, xspanalloc, xfree, xsummary \- basic memory management
.SH SYNOPSIS
.ta \w'\fLvoid* 'u
.B
void* xalloc(ulong size)
.PP
.B
void* xallocz(ulong size, int clr)
.PP
.B
void* xspanalloc(ulong size, int align, ulong span)
.PP
.B
void xfree(void *p)
.PP
.B
void xsummary(void)
.SH DESCRIPTION
These are primitives used by higher-level memory allocators in the kernel,
such as
.IR malloc (9).
They are not intended for use directly by most kernel routines.
The main exceptions are routines that permanently allocate large structures,
or need the special alignment properties guaranteed by
.IR xspanalloc .
.PP
.I Xalloc
returns a pointer to a range of size bytes of memory. The memory will be zero filled and aligned on a 8 byte
.RB ( BY2V )
address. If the memory is not available,
.B xalloc
returns a null pointer.
.PP
.I Xmallocz
will clear the memory after allocation if
.I clr
is set to a value other than zero. Since it is used by
.IR xmalloc ,
the same diagnostics apply.
.PP
.I Xspanalloc
allocates memory given alignment and spanning constraints.
The block returned will contain
.I size
bytes, aligned on a boundary that is
.BI "0 mod" " align,"
in such a way that the memory in the block does not
span an address that is
.BI "0 mod" " span."
.I Xspanalloc
is intended for use
allocating hardware data structures (eg, page tables) or I/O buffers
that must satisfy specific alignment restrictions.
If
.I xspanalloc
cannot allocate memory to satisfy the given constraints, it will
.IR panic (9).
The technique it uses can sometimes cause memory to be wasted.
Consequently,
.I xspanalloc
should be used sparingly.
.PP
.I Xfree
frees the block of memory at
.IR p ,
which must be an address previously returned by
.I xalloc
(not
.IR xspanalloc ).
.PP
.I Xsummary
dumps memory allocation statistics to the console.
The output includes the total free space, the number of free holes,
and a summary of active holes.
Each line shows `address top size'.
.SH SOURCE
.B /sys/src/9/port/xalloc.c
.SH SEE ALSO
.IR malloc (9)