MALLOC(2)                                               MALLOC(2)

     NAME
          malloc, mallocalign, mallocz, free, realloc, calloc, msize,
          setmalloctag, setrealloctag, getmalloctag, getrealloctag,
          malloctopoolblock - memory allocator

     SYNOPSIS
          #include <u.h>
          #include <libc.h>

          void* malloc(ulong size)

          void* mallocalign(ulong size, ulong align, long offset,
          ulong span)

          void* mallocz(ulong size, int clr)

          void  free(void *ptr)

          void* realloc(void *ptr, ulong size)

          void* calloc(ulong nelem, ulong elsize)

          ulong msize(void *ptr)

          void  setmalloctag(void *ptr, uintptr tag)

          uintptrgetmalloctag(void *ptr)

          void  setrealloctag(void *ptr, uintptr tag)

          uintptrgetrealloctag(void *ptr)

          void* malloctopoolblock(void*)

     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 fur-
          ther 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.

          Mallocalign allocates a block of at least n bytes of memory

     Page 1                       Plan 9             (printed 12/4/24)

     MALLOC(2)                                               MALLOC(2)

          respecting alignment contraints.  If align is non-zero, the
          returned pointer is aligned to be equal to offset modulo
          align. If span is non-zero, the n byte block allocated will
          not span a span-byte boundary.

          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)
               means `malloc(size)'; returns a pointer to the newly-
               allocated memory

          realloc(ptr, 0)
               means `free(ptr)'; returns null

          realloc(0, 0)
               no-op; 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.

          When a block is allocated, sometimes there is some extra
          unused space at the end.  Msize grows the block to encompass
          this unused space and returns the new number of bytes that
          may be used.

          The memory allocator maintains two word-sized fields associ-
          ated with each block, the ``malloc tag'' and the ``realloc
          tag''.  By convention, the malloc tag is the PC that allo-
          cated the block, and the realloc tag the PC that last real-
          located 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(2)
          to setmalloctag) to provide more useful information about
          the source of allocation.

          Malloctopoolblock takes the address of a block returned by
          malloc and returns the address of the corresponding block
          allocated by the pool(2) routines.

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

     SEE ALSO
          leak(1), trump (in acid(1)), brk(2), getcallerpc(2), pool(2)

     Page 2                       Plan 9             (printed 12/4/24)

     MALLOC(2)                                               MALLOC(2)

     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.

          After including pool.h, the call 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 setting
              mainmem->flags |= POOL_NOREUSE;
          at the beginning of your program.  This will cause malloc
          not to reallocate blocks even once they are freed;
          poolcheck(mainmem) will then detect writes to freed blocks.

          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.

     Page 3                       Plan 9             (printed 12/4/24)