alloc.3 2.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107
  1. .TH ALLOC 3 "$Revision$"
  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.