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.
100 lines
1.8 KiB
Groff
100 lines
1.8 KiB
Groff
.TH BIN 3
|
|
.SH NAME
|
|
binalloc, bingrow, binfree \- grouped memory allocation
|
|
.SH SYNOPSIS
|
|
.B #include <u.h>
|
|
.br
|
|
.B #include <libc.h>
|
|
.br
|
|
.B #include <bin.h>
|
|
.PP
|
|
.ta \w'\fLvoid* 'u
|
|
.PP
|
|
.B
|
|
typedef struct Bin Bin;
|
|
.PP
|
|
.B
|
|
void *binalloc(Bin **bp, ulong size, int clr);
|
|
.PP
|
|
.B
|
|
void *bingrow(Bin **bp, void *op, ulong osize,
|
|
.br
|
|
.B
|
|
ulong size, int clr);
|
|
.PP
|
|
.B
|
|
void binfree(Bin **bp);
|
|
.SH DESCRIPTION
|
|
These routines provide simple grouped memory allocation and deallocation.
|
|
Items allocated with
|
|
.I binalloc
|
|
are added to the
|
|
.I Bin
|
|
pointed to by
|
|
.IR bp .
|
|
All items in a bin may be freed with one call to
|
|
.IR binfree ;
|
|
there is no way to free a single item.
|
|
.PP
|
|
.I Binalloc
|
|
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 binalloc
|
|
will have the same value.
|
|
The call
|
|
.B binalloc(0)
|
|
returns a valid pointer rather than null.
|
|
If
|
|
.I clr
|
|
is non-zero, the allocated memory is set to 0;
|
|
otherwise, the contents are undefined.
|
|
.PP
|
|
.I Bingrow
|
|
is used to extend the size of a block of memory returned by
|
|
.IR binalloc .
|
|
.I Bp
|
|
must point to the same bin group used to allocate the original block,
|
|
and
|
|
.I osize
|
|
must be the last size used to allocate or grow the block.
|
|
A pointer to a block of at least
|
|
.I size
|
|
bytes is returned, with the same contents in the first
|
|
.I osize
|
|
locations.
|
|
If
|
|
.I clr
|
|
is non-zero, the remaining bytes are set to 0,
|
|
and are undefined otherwise.
|
|
If
|
|
.I op
|
|
is
|
|
.BR nil ,
|
|
it and
|
|
.I osize
|
|
are ignored, and the result is the same as calling
|
|
.IR binalloc .
|
|
.PP
|
|
.I Binalloc
|
|
and
|
|
.I bingrow
|
|
allocate large chunks of memory using
|
|
.MR malloc 3
|
|
and return pieces of these chunks.
|
|
The chunks are
|
|
.IR free 'd
|
|
upon a call to
|
|
.IR binfree .
|
|
.SH SOURCE
|
|
.B \*9/src/libbin
|
|
.SH SEE ALSO
|
|
.MR malloc 3
|
|
.SH DIAGNOSTICS
|
|
.I binalloc
|
|
and
|
|
.I bingrow
|
|
return 0 if there is no available memory.
|