MALLOC(9)                                               MALLOC(9)

     NAME
          malloc, mallocz, smalloc, realloc, free, msize, secalloc,
          secfree, setmalloctag, setrealloctag, getmalloctag,
          getrealloctag - kernel memory allocator

     SYNOPSIS
          void* malloc(ulong size)

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

          void* mallocz(ulong size, int clr)

          void* smalloc(ulong size)

          void* realloc(void *p, ulong size)

          void  free(void *ptr)

          ulong msize(void *ptr)

          void* secalloc(ulong size)

          void  secfree(void *ptr)

          void  setmalloctag(void *ptr, ulong tag)

          ulong getmalloctag(void *ptr)

          void  setrealloctag(void *ptr, ulong tag)

          ulong getrealloctag(void *ptr)

     DESCRIPTION
          These are kernel versions of the functions in malloc(2).
          They allocate memory from the mainmem memory pool, which is
          managed by the allocator pool(2), which in turn replenishes
          the pool as required by calling xalloc(9). All but smalloc
          (which calls sleep(9)) may safely be called by interrupt
          handlers.

          Malloc returns a pointer to a block of at least size bytes,
          initialised to zero.  The block is suitably aligned for
          storage of any type of object.  The call malloc(0) returns a
          valid pointer rather than null.  Mallocz is similar, but
          only clears the memory if clr is non-zero.

          Smalloc returns a pointer to a block of size bytes, ini-
          tialised to zero.  If the memory is not immediately avail-
          able, smalloc retries every 100 milliseconds until the

     Page 1                       Plan 9              (printed 4/8/20)

     MALLOC(9)                                               MALLOC(9)

          memory is acquired.

          Mallocalign allocates a block of at least n bytes of memory
          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 p to
          size bytes, if possible without moving the data, and returns
          a pointer to the block.  The contents are unchanged up to
          the lesser of old and new sizes, and any new space allocated
          is initialised to zero.  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

          The argument to free is a pointer to a block of memory allo-
          cated by one of the routines above, which is returned to the
          allocation pool, or a null pointer, which is ignored.

          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.

          Secalloc and secfree are security-aware functions that use a
          pool flagged by POOL_ANTAGONISM (see pool(2)), which fills
          every allocated block with garbage before and after its use,
          to prevent leakage.

          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.

     Page 2                       Plan 9              (printed 4/8/20)

     MALLOC(9)                                               MALLOC(9)

     SOURCE
          /sys/src/9/port/alloc.c

     DIAGNOSTICS
          All functions except smalloc return a null pointer if space
          is unavailable.  If the allocated blocks have no malloc or
          realloc tags, getmalloctag and getrealloctag return ~0.

     SEE ALSO
          pool(2), xalloc(9)

     Page 3                       Plan 9              (printed 4/8/20)