10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
186 lines
3.6 KiB
Groff
186 lines
3.6 KiB
Groff
.TH MALLOC 3
|
|
.SH NAME
|
|
malloc, mallocz, free, realloc, calloc, setmalloctag, setrealloctag, getmalloctag, getrealloctag \- memory allocator
|
|
.SH SYNOPSIS
|
|
.B #include <u.h>
|
|
.br
|
|
.B #include <libc.h>
|
|
.PP
|
|
.ta \w'\fLvoid* 'u
|
|
.B
|
|
void* malloc(ulong size)
|
|
.PP
|
|
.B
|
|
void* mallocz(ulong size, int clr)
|
|
.PP
|
|
.B
|
|
void free(void *ptr)
|
|
.PP
|
|
.B
|
|
void* realloc(void *ptr, ulong size)
|
|
.PP
|
|
.B
|
|
void* calloc(ulong nelem, ulong elsize)
|
|
.PP
|
|
.B
|
|
void setmalloctag(void *ptr, ulong tag)
|
|
.PP
|
|
.B
|
|
ulong getmalloctag(void *ptr)
|
|
.PP
|
|
.B
|
|
void setrealloctag(void *ptr, ulong tag)
|
|
.PP
|
|
.B
|
|
ulong getrealloctag(void *ptr)
|
|
.SH DESCRIPTION
|
|
.I Malloc
|
|
and
|
|
.I free
|
|
provide a simple memory allocation package.
|
|
.I Malloc
|
|
returns a pointer to a new block of at least
|
|
.I size
|
|
bytes.
|
|
The block is suitably aligned for storage of any type of object.
|
|
No two active pointers from
|
|
.I malloc
|
|
will have the same value.
|
|
The call
|
|
.B malloc(0)
|
|
returns a valid pointer rather than null.
|
|
.PP
|
|
The argument to
|
|
.I free
|
|
is a pointer to a block previously allocated by
|
|
.IR malloc ;
|
|
this space is made available for further allocation.
|
|
It is legal to free a null pointer; the effect is a no-op.
|
|
The contents of the space returned by
|
|
.I malloc
|
|
are undefined.
|
|
.I Mallocz
|
|
behaves as
|
|
.IR malloc ,
|
|
except that if
|
|
.I clr
|
|
is non-zero, the memory returned will be zeroed.
|
|
.PP
|
|
.I Realloc
|
|
changes the size of the block pointed to by
|
|
.I ptr
|
|
to
|
|
.I size
|
|
bytes and returns a pointer to the (possibly moved)
|
|
block.
|
|
The contents will be unchanged up to the
|
|
lesser of the new and old sizes.
|
|
.I Realloc
|
|
takes on special meanings when one or both arguments are zero:
|
|
.TP
|
|
.B "realloc(0,\ size)
|
|
means
|
|
.LR malloc(size) ;
|
|
returns a pointer to the newly-allocated memory
|
|
.TP
|
|
.B "realloc(ptr,\ 0)
|
|
means
|
|
.LR free(ptr) ;
|
|
returns null
|
|
.TP
|
|
.B "realloc(0,\ 0)
|
|
no-op; returns null
|
|
.PD
|
|
.PP
|
|
.I Calloc
|
|
allocates space for
|
|
an array of
|
|
.I nelem
|
|
elements of size
|
|
.IR elsize .
|
|
The space is initialized to zeros.
|
|
.I Free
|
|
frees such a block.
|
|
.PP
|
|
The memory allocator on Plan 9 maintains two word-sized fields
|
|
associated with each block, the ``malloc tag'' and the ``realloc tag''.
|
|
By convention, the malloc tag is the PC that allocated the block,
|
|
and the realloc tag the PC that last reallocated the block.
|
|
These may be set or examined with
|
|
.IR setmalloctag ,
|
|
.IR getmalloctag ,
|
|
.IR setrealloctag ,
|
|
and
|
|
.IR getrealloctag .
|
|
When allocating blocks directly with
|
|
.I malloc
|
|
and
|
|
.IR realloc ,
|
|
these tags will be set properly.
|
|
If a custom allocator wrapper is used,
|
|
the allocator wrapper can set the tags
|
|
itself (usually by passing the result of
|
|
.IR getcallerpc (3)
|
|
to
|
|
.IR setmalloctag )
|
|
to provide more useful information about
|
|
the source of allocation.
|
|
.SH SOURCE
|
|
.B \*9/src/lib9/malloc.c
|
|
.br
|
|
.B \*9/src/lib9/malloctag.c
|
|
.SH SEE ALSO
|
|
.I trump
|
|
(in
|
|
.MR acid 1 ),
|
|
.MR getcallerpc 3
|
|
.SH DIAGNOSTICS
|
|
.I Malloc, realloc
|
|
and
|
|
.I calloc
|
|
return 0 if there is no available memory.
|
|
.I Errstr
|
|
is likely to be set.
|
|
If the allocated blocks have no malloc or realloc tags,
|
|
.I getmalloctag
|
|
and
|
|
.I getrealloctag
|
|
return
|
|
.BR ~0 .
|
|
.PP
|
|
The
|
|
.I trump
|
|
library for
|
|
.I acid
|
|
can be used to obtain traces of malloc execution; see
|
|
.MR acid 1 .
|
|
.SH BUGS
|
|
The different specification of
|
|
.I calloc
|
|
is bizarre.
|
|
.PP
|
|
User errors can corrupt the storage arena.
|
|
The most common gaffes are (1) freeing an already freed block,
|
|
(2) storing beyond the bounds of an allocated block, and (3)
|
|
freeing data that was not obtained from the allocator.
|
|
When
|
|
.I malloc
|
|
and
|
|
.I free
|
|
detect such corruption, they abort.
|
|
.PP
|
|
To avoid name conflicts with the system versions of these functions,
|
|
.IR malloc ,
|
|
.IR realloc ,
|
|
.IR calloc ,
|
|
and
|
|
.I free
|
|
are preprocessor macros defined as
|
|
.IR p9malloc ,
|
|
.IR p9realloc ,
|
|
.IR p9calloc ,
|
|
and
|
|
.IR p9free ;
|
|
see
|
|
.MR intro 3 .
|