modules/src/alloc/alloc.3

   1 .TH ALLOC 3 "$Revision: 1.11 $"
   2 .ad
   3 .SH NAME
   4 Malloc, Salloc, Realloc, Srealloc, st_alloc, st_free\ \-\ low level memory allocation routines
   5 .SH SYNOPSIS
   6 .B #include <alloc.h>
   7 .PP
   8 .B char *Malloc(size)
   9 .br
  10 .B unsigned int size;
  11 .PP
  12 .B char *Salloc(str, size)
  13 .br
  14 .B char *str;
  15 .B unsigned int size;
  16 .PP
  17 .B char *Realloc(ptr, size)
  18 .B char *buf;
  19 .B unsigned int size;
  20 .PP
  21 .B char *Srealloc(str, size)
  22 .br
  23 .B char *str;
  24 .br
  25 .B unsigned int size;
  26 .PP
  27 .B char *st_alloc(phead, size, count)
  28 .br
  29 .B char **phead;
  30 .br
  31 .B unsigned int size;
  32 .PP
  33 .B st_free(ptr, phead, size)
  34 .br
  35 .B char *ptr;
  36 .br
  37 .B char **phead;
  38 .br
  39 .B unsigned int size;
  40 .PP
  41 .B void clear(ptr, size)
  42 .br
  43 .B char *ptr;
  44 .br
  45 .B unsigned int size;
  46 .PP
  47 .void No_Mem()
  48 .PP
  49 .SH DESCRIPTION
  50 This set of routines provides a checking memory allocation mechanism.
  51 .PP
  52 \fIMalloc\fR returns a pointer to a block of at least \fIsize\fR
  53 bytes, beginning on a boundary suitable for any data type.
  54 .PP
  55 \fISalloc\fR returns a pointer to a block of at least \fIsize\fR
  56 bytes, initialized with the null-terminated string \fIstr\fR.
  57 .PP
  58 \fIRealloc\fR changes the size of
  59 the block at \fIbuf\fR to \fIsize\fR bytes, and returns a pointer to the
  60 (possibly moved) block. If \fIbuf\fP is a null pointer, \fIRealloc\fP
  61 behaves as \fIMalloc\fP.
  62 .PP
  63 \fISrealloc\fR reallocates
  64 the string at \fIstr\fR to \fIsize\fR bytes.
  65 It actually does the same as \fIRealloc\fP, and exists only for
  66 backwards compatibility.
  67 .PP
  68 All these routines use \fImalloc\fR and \fIrealloc\fR.
  69 The routine \fIfree\fR can be used on pointers returned by these routines.
  70 .PP
  71 \fISt_alloc\fR and \fIst_free\fR provide a mechanism for maintaining free lists
  72 of structures.
  73 \fISt_alloc\fR takes three parameters: \fIphead\fR is a pointer to a field
  74 containing the head of the free list, \fIsize\fR contains the size of the
  75 structures, and \fIcount\fR indicates how many new structures must be allocated
  76 in case the free list is exhausted.
  77 It returns a pointer to a zero-initialized structure.
  78 \fISt_free\fR also takes three parameters: \fIptr\fR is a pointer to
  79 the structure to be freed, \fIphead\fR is again a pointer to a field
  80 containing the head of the free list, and \fIsize\fR again contains the size
  81 of the structures.
  82 These last two routines are best used in a macro.
  83 .PP
  84 \fIClear\fR clears \fIsize\fR bytes, starting at \fIptr\fR.
  85 .SH FILES
  86 .nf
  87 ~em/modules/h/alloc.h
  88 ~em/modules/lib/liballoc.a
  89 .fi
  90 .SH "MODULES USED"
  91 system(3)
  92 .SH "SEE ALSO"
  93 malloc(3)
  94 .SH DIAGNOSTICS
  95 \fIMalloc\fR, \fISalloc\fR, \fIRealloc\fP, \fISrealloc\fR, and \fIst_alloc\fR
  96 call a routine \fINo_Mem\fR if there is no memory available. This routine
  97 is not supposed to return. A default one, that
  98 gives an error message and stops execution, is provided.
  99 .SH BUGS
 100 The
 101 .I st_alloc
 102 mechanism only works for structures that are large enough to contain one
 103 pointer.
 104 Also,
 105 .I st_free
 106 actually is a macro, and references its arguments more than once, so they
 107 better not have side-effects.