sys/man/9/malloc

   1 .TH MALLOC 9
   2 .SH NAME
   3 malloc, mallocz, smalloc, realloc, free, msize, secalloc, secfree, setmalloctag, setrealloctag, getmalloctag, getrealloctag \- kernel memory allocator
   4 .SH SYNOPSIS
   5 .ta \w'\fLvoid* 'u
   6 .B
   7 void*   malloc(ulong size)
   8 .PP
   9 .B
  10 void*   mallocalign(ulong size, ulong align, long offset, ulong span)
  11 .PP
  12 .B
  13 void*   mallocz(ulong size, int clr)
  14 .PP
  15 .B
  16 void*   smalloc(ulong size)
  17 .PP
  18 .B
  19 void*   realloc(void *p, ulong size)
  20 .PP
  21 .B
  22 void    free(void *ptr)
  23 .PP
  24 .B
  25 ulong   msize(void *ptr)
  26 .PP
  27 .B
  28 void*   secalloc(ulong size)
  29 .PP
  30 .B
  31 void    secfree(void *ptr)
  32 .PP
  33 .B
  34 void    setmalloctag(void *ptr, ulong tag)
  35 .PP
  36 .B
  37 ulong   getmalloctag(void *ptr)
  38 .PP
  39 .B
  40 void    setrealloctag(void *ptr, ulong tag)
  41 .PP
  42 .B
  43 ulong   getrealloctag(void *ptr)
  44 .PP
  45 .SH DESCRIPTION
  46 These are kernel versions of the functions in
  47 .IR malloc (2).
  48 They allocate memory from the
  49 .B mainmem
  50 memory pool,
  51 which is managed by
  52 the allocator
  53 .IR pool (2),
  54 which in turn replenishes the pool as required by calling
  55 .IR xalloc (9).
  56 All but
  57 .I smalloc
  58 (which calls
  59 .IR sleep (9))
  60 may safely be called by interrupt handlers.
  61 .PP
  62 .I Malloc
  63 returns a pointer to a block of at least
  64 .I size
  65 bytes, initialised to zero.
  66 The block is suitably aligned for storage of any type of object.
  67 The call
  68 .B malloc(0)
  69 returns a valid pointer rather than null.
  70 .I Mallocz
  71 is similar, but only clears the memory if
  72 .I clr
  73 is non-zero.
  74 .PP
  75 .I Smalloc
  76 returns a pointer to a block of
  77 .I size
  78 bytes, initialised to zero.
  79 If the memory is not immediately available,
  80 .I smalloc
  81 retries every 100 milliseconds until the memory is acquired.
  82 .PP
  83 .I Mallocalign
  84 allocates a block of at least
  85 .I n
  86 bytes of memory respecting alignment contraints.
  87 If
  88 .I align
  89 is non-zero,
  90 the returned pointer is aligned to be equal to
  91 .I offset
  92 modulo
  93 .IR align .
  94 If
  95 .I span
  96 is non-zero,
  97 the
  98 .I n
  99 byte block allocated will not span a
 100 .IR span -byte
 101 boundary.
 102 .PP
 103 .I Realloc
 104 changes the size of the block pointed to by
 105 .I p
 106 to
 107 .I size
 108 bytes,
 109 if possible without moving the data,
 110 and returns a pointer to the block.
 111 The contents are unchanged up to the lesser of old and new sizes,
 112 and any new space allocated is initialised to zero.
 113 .I Realloc
 114 takes on special meanings when one or both arguments are zero:
 115 .TP
 116 .B "realloc(0,\ size)
 117 means
 118 .LR malloc(size) ;
 119 returns a pointer to the newly-allocated memory
 120 .TP
 121 .B "realloc(ptr,\ 0)
 122 means
 123 .LR free(ptr) ;
 124 returns null
 125 .TP
 126 .B "realloc(0,\ 0)
 127 no-op; returns null
 128 .PD
 129 .PP
 130 The argument to
 131 .I free
 132 is a pointer to a block of memory allocated by one of the routines above, which
 133 is returned to the allocation pool, or a null pointer, which is ignored.
 134 .PP
 135 When a block is allocated, sometimes there is some extra unused space at the end.
 136 .I Msize
 137 grows the block to encompass this unused space and returns the new number
 138 of bytes that may be used.
 139 .PP
 140 .I Secalloc
 141 and
 142 .I secfree
 143 are security-aware functions that use a pool flagged by
 144 .B POOL_ANTAGONISM
 145 (see
 146 .IR pool (2)),
 147 which fills every allocated block with garbage before and after its
 148 use, to prevent leakage.
 149 .PP
 150 The memory allocator maintains two word-sized fields
 151 associated with each block, the ``malloc tag'' and the ``realloc tag''.
 152 By convention, the malloc tag is the PC that allocated the block,
 153 and the realloc tag the PC that last reallocated the block.
 154 These may be set or examined with
 155 .IR setmalloctag ,
 156 .IR getmalloctag ,
 157 .IR setrealloctag ,
 158 and
 159 .IR getrealloctag .
 160 When allocating blocks directly with
 161 .I malloc
 162 and
 163 .IR realloc ,
 164 these tags will be set properly.
 165 If a custom allocator wrapper is used,
 166 the allocator wrapper can set the tags
 167 itself (usually by passing the result of
 168 .IR getcallerpc (2)
 169 to
 170 .IR setmalloctag )
 171 to provide more useful information about
 172 the source of allocation.
 173 .SH SOURCE
 174 .B /sys/src/9/port/alloc.c
 175 .SH DIAGNOSTICS
 176 All functions except
 177 .I smalloc
 178 return a null pointer if space is unavailable.
 179 If the allocated blocks have no malloc or realloc tags,
 180 .I getmalloctag
 181 and
 182 .I getrealloctag
 183 return
 184 .BR ~0 .
 185 .SH SEE ALSO
 186 .IR pool (2),
 187 .IR xalloc (9)