Subversion Repositories planix.SVN

.TH MALLOC 2

.SH NAME

malloc, mallocalign, mallocz, free, realloc, calloc, msize, setmalloctag, setrealloctag, getmalloctag, getrealloctag, malloctopoolblock \- 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*	mallocalign(ulong size, ulong align, long offset, ulong span)

.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

ulong	msize(void *ptr)

.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)

.PP

.B

void*	malloctopoolblock(void*)

.PP

.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 Mallocalign

allocates a block of at least 

.I size

bytes of memory respecting alignment contraints.

If

.I align

is non-zero,

the returned pointer is aligned to be equal to

.I offset

modulo

.IR align .

If

.I span

is non-zero,

the

.IR size -byte

block allocated will not span a

.IR span -byte

boundary.

.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:

.TF "\fLrealloc(0, sz)

.PD

.TP

.B "realloc(0, sz)

means

.LR malloc(sz) ;

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

When a block is allocated, sometimes there is some extra unused space at the end.

.I Msize

grows the block to encompass this unused space and returns the new number

of bytes that may be used.

.PP

The memory allocator 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 (2) 

to 

.IR setmalloctag )

to provide more useful information about

the source of allocation.

.PP

.I Malloctopoolblock

takes the address of a block returned by

.I malloc

and returns the address of the corresponding

block allocated by the

.IR pool (2)

routines.

.SH SOURCE

.B /sys/src/libc/port/malloc.c

.SH SEE ALSO

.IR leak (1),

.I trump

(in

.IR acid (1)),

.IR brk (2),

.IR getcallerpc (2),

.IR pool (2)

.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

After including

.BR pool.h ,

the call

.B poolcheck(mainmem)

can be used to scan the storage arena for inconsistencies

such as data written beyond the bounds of allocated blocks.

It is often useful to combine this with with setting

.EX

    mainmem->flags |= POOL_NOREUSE;

.EE

at the beginning of your program.

This will cause malloc not to reallocate blocks even

once they are freed;

.B poolcheck(mainmem)

will then detect writes to freed blocks.

.PP

The 

.I trump

library for

.I acid

can be used to obtain traces of malloc execution; see

.IR 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.