sys/man/9/xalloc

   1 .TH XALLOC 9
   2 .SH NAME
   3 xalloc, xallocz, xspanalloc, xfree, xsummary \- basic memory management
   4 .SH SYNOPSIS
   5 .ta \w'\fLvoid* 'u
   6 .B
   7 void*   xalloc(ulong size)
   8 .PP
   9 .B
  10 void*   xallocz(ulong size, int clr)
  11 .PP
  12 .B
  13 void*   xspanalloc(ulong size, int align, ulong span)
  14 .PP
  15 .B
  16 void    xfree(void *p)
  17 .PP
  18 .B
  19 void    xsummary(void)
  20 .SH DESCRIPTION
  21 These are primitives used by higher-level memory allocators in the kernel,
  22 such as
  23 .IR malloc (9).
  24 They are not intended for use directly by most kernel routines.
  25 The main exceptions are routines that permanently allocate large structures,
  26 or need the special alignment properties guaranteed by
  27 .IR xspanalloc .
  28 .PP
  29 .I Xalloc
  30 returns a pointer to a range of size bytes of memory. The memory will be zero filled and aligned on a 8 byte
  31 .RB ( BY2V )
  32 address. If the memory is not available,
  33 .B xalloc
  34 returns a null pointer.
  35 .PP
  36 .I Xmallocz
  37 will clear the memory after allocation if
  38 .I clr
  39 is set to a value other than zero. Since it is used by
  40 .IR xmalloc ,
  41 the same diagnostics apply.
  42 .PP
  43 .I Xspanalloc
  44 allocates memory given alignment and spanning constraints.
  45 The block returned will contain
  46 .I size
  47 bytes, aligned on a boundary that is
  48 .BI "0 mod" " align,"
  49 in such a way that the memory in the block does not
  50 span an address that is
  51 .BI "0 mod" " span."
  52 .I Xspanalloc
  53 is intended for use
  54 allocating hardware data structures (eg, page tables) or I/O buffers
  55 that must satisfy specific alignment restrictions.
  56 If
  57 .I xspanalloc
  58 cannot allocate memory to satisfy the given constraints, it will
  59 .IR panic (9).
  60 The technique it uses can sometimes cause memory to be wasted.
  61 Consequently,
  62 .I xspanalloc
  63 should be used sparingly.
  64 .PP
  65 .I Xfree
  66 frees the block of memory at
  67 .IR p ,
  68 which must be an address previously returned by
  69 .I xalloc
  70 (not
  71 .IR xspanalloc ).
  72 .PP
  73 .I Xsummary
  74 dumps memory allocation statistics to the console.
  75 The output includes the total free space, the number of free holes,
  76 and a summary of active holes.
  77 Each line shows `address top size'.
  78 .SH SOURCE
  79 .B /sys/src/9/port/xalloc.c
  80 .SH SEE ALSO
  81 .IR malloc (9)