390 lines
9.7 KiB
Plaintext
390 lines
9.7 KiB
Plaintext
'\"macro stdmacro
|
|
.if n .pH g3x.malloc @(#)malloc 30.3 of 1/19/86
|
|
.nr X
|
|
.if \nX=0 .ds x} MALLOC 3X "Specialized Libraries" "\&"
|
|
.if \nX=1 .ds x} MALLOC 3X "Specialized Libraries"
|
|
.if \nX=2 .ds x} MALLOC 3X "" "\&"
|
|
.if \nX=3 .ds x} MALLOC "" "" "\&"
|
|
.TH \*(x}
|
|
.SH NAME
|
|
malloc, free, realloc, calloc, mallopt, mallinfo, mallocblksize, recalloc, memalign \- fast main memory allocator
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <sys/types.h>
|
|
.B #include <malloc.h>
|
|
.P
|
|
.B "void \(**malloc (size_t size);"
|
|
.PP
|
|
.B "void free (void \(**ptr);"
|
|
.PP
|
|
.B "void \(**realloc (void \(**ptr, size_t size);"
|
|
.PP
|
|
.B "void \(**calloc (size_t nelem, size_t elsize);"
|
|
.PP
|
|
.B "int mallopt (int cmd, int value);"
|
|
.PP
|
|
.B "struct mallinfo mallinfo(void);"
|
|
.PP
|
|
.B "size_t mallocblksize (void \(**ptr);"
|
|
.PP
|
|
.B "void \(**recalloc (void \(**ptr, size_t nelem, size_t elsize);"
|
|
.PP
|
|
.B "void \(**memalign (size_t align, size_t size);"
|
|
.SH DESCRIPTION
|
|
.B malloc\^
|
|
and
|
|
.B free\^
|
|
provide a simple general-purpose memory allocation package,
|
|
which is more flexible than the \f4malloc\fP(3c) package and, depending
|
|
on an application's usage, may provide better performance.
|
|
It is found in the library ``libmalloc.so'', and
|
|
is loaded if the option ``\f4\-lmalloc\fP'' is used
|
|
with
|
|
.BR cc (1)
|
|
or
|
|
.BR ld (1).
|
|
.PP
|
|
.B malloc\^
|
|
returns a pointer to a block of at least
|
|
.I size\^
|
|
bytes suitably aligned for any use.
|
|
.PP
|
|
The argument to
|
|
.B free\^
|
|
is a pointer to a block previously allocated by
|
|
.BR malloc ;
|
|
after
|
|
.B free\^
|
|
is performed this space is made available for further allocation,
|
|
and its contents are destroyed (see
|
|
.B mallopt\^
|
|
below for a way to change this behavior).
|
|
.PP
|
|
Undefined results will occur if the space
|
|
assigned by
|
|
.B malloc\^
|
|
is overrun or if some random number is handed to
|
|
.BR free .
|
|
It is always permitted to pass
|
|
.SM NULL
|
|
to
|
|
.BR free .
|
|
.PP
|
|
.B 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.
|
|
In the special case of a null
|
|
.IR ptr\^ ,
|
|
.B realloc
|
|
degenerates to
|
|
.BR malloc .
|
|
A zero
|
|
.I size
|
|
causes the passed block to be freed.
|
|
.PP
|
|
.B calloc\^
|
|
allocates space for an array of
|
|
.I nelem\^
|
|
elements of size
|
|
.IR elsize .
|
|
The space is initialized to zeros.
|
|
.PP
|
|
.B recalloc\^
|
|
combines
|
|
.B realloc
|
|
and
|
|
.BR calloc .
|
|
If the size of the block increases, any new bytes are initialized
|
|
to zero.
|
|
Note that for this to work properly, all allocations of
|
|
a given pointer must go through
|
|
.BR recalloc .
|
|
If the original pointer was allocated with either
|
|
.BR malloc ,
|
|
.BR calloc ,
|
|
or
|
|
.B realloc
|
|
some new bytes may not be set properly to zero.
|
|
.PP
|
|
.B memalign
|
|
allocates
|
|
\f2size\fP
|
|
bytes on a specified alignment boundary,
|
|
and returns a pointer to the allocated block.
|
|
The value of the returned address is guaranteed to be
|
|
an even multiple of
|
|
\f2align\fP.
|
|
Note: the value of
|
|
.I align
|
|
must be a multiple of a word (for 64 bit objects, a doubleword,)
|
|
and must be greater than
|
|
or equal to the size of a word, or, for 64 bit objects, the size
|
|
of a doubleword.
|
|
.PP
|
|
.B mallocblksize
|
|
returns the actual size of the block pointed to by
|
|
.IR ptr .
|
|
The returned size may be greater than the original requested size due
|
|
to padding and alignment.
|
|
.PP
|
|
.B mallopt\^
|
|
provides for control over the allocation algorithm.
|
|
The available values for
|
|
.I cmd\^
|
|
are:
|
|
.TP .90i
|
|
.SM M_MXFAST
|
|
Set
|
|
.IR maxfast
|
|
to
|
|
.IR value.
|
|
The algorithm allocates all blocks at or below the size
|
|
of
|
|
.IR maxfast
|
|
in large groups and then doles them out very quickly.
|
|
The default value for
|
|
.IR maxfast
|
|
is 28.
|
|
.TP
|
|
.SM M_NLBLKS
|
|
Set
|
|
.IR numlblks
|
|
to
|
|
.IR value .
|
|
The above mentioned ``large groups'' each contain
|
|
.I numlblks\^
|
|
blocks.
|
|
.I numlblks\^
|
|
must be greater than 0.
|
|
The default value for
|
|
.I numlblks\^
|
|
is 100.
|
|
.TP
|
|
.SM M_GRAIN
|
|
Set
|
|
.I grain\^
|
|
to
|
|
.IR value .
|
|
Requests less than or equal to
|
|
.I maxfast\^
|
|
will have the size of a pointer added to them and be rounded up to
|
|
the next multiple of
|
|
.IR grain .
|
|
.I value\^
|
|
will be rounded up to a multiple of the alignment size
|
|
(8 bytes for 32 bit programs, 16 bytes for 64 bit programs)
|
|
when
|
|
.I grain\^
|
|
is set.
|
|
.I grain\^
|
|
must be greater than 0.
|
|
The default value of
|
|
.I grain\^
|
|
is 8 for 32 bit programs, 16 for 64 bit programs.
|
|
.TP
|
|
.SM M_KEEP
|
|
Preserve data in a freed block until the next
|
|
.BR malloc ,
|
|
.BR realloc ,
|
|
or
|
|
.BR calloc .
|
|
This option is provided only for compatibility with older
|
|
versions of
|
|
.B malloc
|
|
and is not recommended.
|
|
.TP
|
|
.SM M_DEBUG
|
|
Turns debug checking on if
|
|
.I value
|
|
is not equal to 0, otherwise turns debug checking off.
|
|
When debugging is on, each call to
|
|
.B malloc
|
|
and
|
|
.B free
|
|
causes the entire malloc arena
|
|
to be scanned and checked for consistency.
|
|
This option may be invoked at any time.
|
|
Note that when debug checking is on, the performance of
|
|
.B malloc\^
|
|
is reduced considerably.
|
|
If corruption is detected in the arena, the checking code calls
|
|
.BR abort (3C).
|
|
This usually results in the calling process exiting and leaving a
|
|
.B core
|
|
file in its current directory.
|
|
.TP
|
|
.SM M_BLKSZ
|
|
When
|
|
.B malloc
|
|
requires additional space, it uses
|
|
.BR sbrk (2)
|
|
to allocate enough memory for the current
|
|
.B malloc
|
|
request rounded up to a minimum size (default is 8K).
|
|
The new size is set to
|
|
.I value
|
|
after it has been rounded up to the current block alignment.
|
|
.I value
|
|
must be at least 512 bytes.
|
|
If a lot of space is to be allocated,
|
|
setting the size larger can cut down on the system overhead.
|
|
This option may be invoked at any time.
|
|
.TP
|
|
.SM M_MXCHK
|
|
By default,
|
|
.B malloc
|
|
trades off time versus space - if anywhere in the arena there is a block
|
|
of the appropriate size,
|
|
.B malloc
|
|
will find and return it.
|
|
If the arena has become fragmented due to many
|
|
.B mallocs
|
|
and
|
|
.B frees,
|
|
it is possible that
|
|
.B malloc
|
|
will have to search through many blocks to find one of the appropriate size.
|
|
If the arena is severely fragmented, the average
|
|
.B malloc
|
|
time can be on the order of tens of milliseconds (as opposed to a normal
|
|
average of tens of microseconds).
|
|
This option allows the user to place a limit on the number of blocks that
|
|
.B malloc
|
|
will search through before allocating a new block of space from the system.
|
|
Small values (less than 50) can cause much more memory to be allocated.
|
|
Values around 100 (the default) cause very uniform response time,
|
|
with a small space penalty.
|
|
This option may be invoked at any time.
|
|
.TP
|
|
.SM M_FREEHD
|
|
When
|
|
.I value
|
|
is not zero,
|
|
.BR free ,
|
|
.BR recalloc ,
|
|
and
|
|
.B realloc
|
|
will place any freed memory in the front of the free list(s)
|
|
instead of at the end
|
|
(which is the default).
|
|
Some applications will benefit in processing speed and space
|
|
compaction by having freed memory placed at the beginning of the free list(s).
|
|
.TP
|
|
.SM M_CLRONFREE
|
|
With this option, all blocks that are freed are set to
|
|
.IR value .
|
|
This option may be set at any time, but there is no way to turn it off.
|
|
That part of the beginning of a freed block which is used for internal pointers
|
|
will of course not be set to
|
|
.IR value .
|
|
.PP
|
|
These values are defined in the <\f4malloc.h\fP>
|
|
header file.
|
|
.PP
|
|
.B mallopt
|
|
may be called repeatedly, but, for most commands,
|
|
may not be called after the first small block is allocated.
|
|
.PP
|
|
.B mallinfo\^
|
|
provides instrumentation describing space usage.
|
|
It returns the structure (defined in <\f4malloc.h\fP>):
|
|
.PP
|
|
.ds HZ :::::int:keepcost;::::
|
|
.nf
|
|
struct mallinfo {
|
|
int arena; \h'|\w'\*(HZ'u'/\(** total space in arena \(**/
|
|
int ordblks; \h'|\w'\*(HZ'u'/\(** number of ordinary blocks \(**/
|
|
int smblks; \h'|\w'\*(HZ'u'/\(** number of small blocks \(**/
|
|
int hblkhd; \h'|\w'\*(HZ'u'/\(** space in holding block headers \(**/
|
|
int hblks; \h'|\w'\*(HZ'u'/\(** number of holding blocks \(**/
|
|
int usmblks; \h'|\w'\*(HZ'u'/\(** space in small blocks in use \(**/
|
|
int fsmblks; \h'|\w'\*(HZ'u'/\(** space in free small blocks \(**/
|
|
int uordblks; \h'|\w'\*(HZ'u'/\(** space in ordinary blocks in use \(**/
|
|
int fordblks; \h'|\w'\*(HZ'u'/\(** space in free ordinary blocks \(**/
|
|
int keepcost; \h'|\w'\*(HZ'u'/\(** space penalty if keep option \(**/
|
|
\h'|\w'\*(HZ'u'/\(** is used \(**/
|
|
}
|
|
.fi
|
|
For example, an application wishing to determine how many bytes it has
|
|
currently malloc'd should add the
|
|
.I usmblks
|
|
and
|
|
.I uordblks
|
|
fields.
|
|
That total may also include some space that
|
|
.B malloc
|
|
allocates internally for its own use,
|
|
and that extra space cannot be free'd.
|
|
.PP
|
|
Each of the allocation routines returns a pointer
|
|
to space suitably aligned (after possible pointer coercion)
|
|
for storage of any type of object.
|
|
.SH SEE ALSO
|
|
brk(2), malloc(3C), memalign(3C), amalloc(3P), valloc(3C).
|
|
.SH DIAGNOSTICS
|
|
.BR malloc\^ ,
|
|
.BR recalloc\^ ,
|
|
.BR memalign\^ ,
|
|
.B realloc\^
|
|
and
|
|
.B calloc\^
|
|
return a
|
|
.SM NULL
|
|
pointer if there is not enough available memory or \f2size\fP is 0.
|
|
.B memalign\^
|
|
will also return
|
|
.SM NULL
|
|
if \f2align\fP is 0 or not a 4 byte multiple (8 byte multiple for 64-bit programs).
|
|
When
|
|
.B realloc\^
|
|
or
|
|
.B recalloc\^
|
|
returns
|
|
\s-1NULL\s+1, the block pointed to by
|
|
.I ptr\^
|
|
is left intact.
|
|
If
|
|
.B mallopt\^
|
|
is called after any allocation (for most
|
|
.I cmd\^
|
|
arguments) or if
|
|
.I cmd\^
|
|
or
|
|
.I value\^
|
|
are invalid, non-zero is returned.
|
|
Otherwise, it returns zero.
|
|
.SH WARNINGS
|
|
Note that unlike
|
|
.BR malloc (3C),
|
|
this package does not preserve
|
|
the contents of a block when it is freed, unless
|
|
the
|
|
.SM M_KEEP
|
|
option of
|
|
.B mallopt\^
|
|
is used.
|
|
.br
|
|
Undocumented features of
|
|
.BR malloc (3C)
|
|
have not been duplicated.
|
|
.PP
|
|
Products, libraries, or commands that provide their own malloc package
|
|
must provide all of the entry points listed above, or the normal
|
|
libmalloc or libc malloc entry point for the unimplmented routine(s)
|
|
may be called instead, leading to corrupted heaps, as it is unlikely
|
|
that the internal details of the heap management will be the same. If
|
|
the package is a replacement for the libc set, but not the libmalloc
|
|
set, it is not necessary to supply the
|
|
.BR mallopt ,
|
|
.BR mallinfo ,
|
|
.BR mallocblksize,
|
|
or
|
|
.B recalloc
|
|
routines.
|