|  | 
 NAME     
 |  |  |  | malloc, mallocz, free, realloc, calloc, setmalloctag, setrealloctag,
    getmalloctag, getrealloctag – memory allocator 
 | 
 SYNOPSIS     
 |  |  |  | #include <u.h> #include <libc.h> 
    
    
    void* malloc(ulong size) 
    
    
    void* mallocz(ulong size, int clr) 
    
    
    void    free(void *ptr) 
    
    
    void* realloc(void *ptr, ulong size) 
    
    
    void* calloc(ulong nelem, ulong elsize) 
    
    
    void    setmalloctag(void *ptr, ulong tag) 
    
    
    ulong getmalloctag(void *ptr) 
    
    
    void    setrealloctag(void *ptr, ulong tag) 
    
    
    ulong getrealloctag(void *ptr)
 
 | 
 DESCRIPTION     
 |  |  |  | Malloc and free provide a simple memory allocation package. Malloc
    returns a pointer to a new block of at least size bytes. The block
    is suitably aligned for storage of any type of object. No two
    active pointers from malloc will have the same value. The call
    malloc(0) returns a valid pointer rather than null. 
    
    
    The argument to free is a pointer to a block previously allocated
    by 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 malloc are undefined. Mallocz
    behaves as malloc, except that if clr is non-zero, the memory
    returned will be zeroed. 
    
    
    Realloc changes the size of the block pointed to by ptr to 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. Realloc takes on special meanings when one or both arguments
    are zero: realloc(0, size)
 
 realloc(ptr, 0)|  |  |  | means malloc(size); returns a pointer to the newly-allocated memory 
 | 
 
 realloc(0, 0)|  |  |  | means free(ptr); returns null 
 | 
 Calloc allocates space for an array of nelem elements of size
    elsize. The space is initialized to zeros. Free frees such a block.
    
    
    
    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 setmalloctag, getmalloctag,
    setrealloctag, and getrealloctag.
    When allocating blocks directly with malloc and 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 getcallerpc(3) to setmalloctag) to provide more
    useful information about the source of allocation.
 
 | 
 SOURCE     
 SEE ALSO    
 DIAGNOSTICS     
 |  |  |  | Malloc, realloc and calloc return 0 if there is no available memory.
    Errstr is likely to be set. If the allocated blocks have no malloc
    or realloc tags, getmalloctag and getrealloctag return ~0. 
    
    
    The trump library for acid can be used to obtain traces of malloc
    execution; see acid(1). 
 | 
 BUGS     
 |  |  |  | The different specification of calloc is bizarre. 
    
    
    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 malloc and free detect such
    corruption, they abort. 
    
    
    To avoid name conflicts with the system versions of these functions,
    malloc, realloc, calloc, and free are preprocessor macros defined
    as p9malloc, p9realloc, p9calloc, and p9free; see intro(3). 
 | 
 |  |