alloc.3 2.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106
  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. .br
  42. .B clear(ptr, size)
  43. .br
  44. .B char *ptr;
  45. .br
  46. .B unsigned int size;
  47. .PP
  48. .SH DESCRIPTION
  49. This set of routines provides a checking memory allocation mechanism.
  50. .PP
  51. \fIMalloc\fR returns a pointer to a block of at least \fIsize\fR
  52. bytes, beginning on a boundary suitable for any data type.
  53. .PP
  54. \fISalloc\fR returns a pointer to a block of at least \fIsize\fR
  55. bytes, initialized with the null-terminated string \fIstr\fR.
  56. .PP
  57. \fIRealloc\fR changes the size of
  58. the block at \fIbuf\fR to \fIsize\fR bytes, and returns a pointer to the
  59. (possibly moved) block. If \fIbuf\fP is a null pointer, \fIRealloc\fP
  60. behaves as \fIMalloc\fP.
  61. .PP
  62. \fISrealloc\fR reallocates
  63. the string at \fIstr\fR to \fIsize\fR bytes.
  64. It actually does the same as \fIRealloc\fP, and exists only for
  65. backwards compatibility.
  66. .PP
  67. All these routines use \fImalloc\fR and \fIrealloc\fR.
  68. The routine \fIfree\fR can be used on pointers returned by these routines.
  69. .PP
  70. \fISt_alloc\fR and \fIst_free\fR provide a mechanism for maintaining free lists
  71. of structures.
  72. \fISt_alloc\fR takes three parameters: \fIphead\fR is a pointer to a field
  73. containing the head of the free list, \fIsize\fR contains the size of the
  74. structures, and \fIcount\fR indicates how many new structures must be allocated
  75. in case the free list is exhausted.
  76. It returns a pointer to a zero-initialized structure.
  77. \fISt_free\fR also takes three parameters: \fIptr\fR is a pointer to
  78. the structure to be freed, \fIphead\fR is again a pointer to a field
  79. containing the head of the free list, and \fIsize\fR again contains the size
  80. of the structures.
  81. These last two routines are best used in a macro.
  82. .PP
  83. \fIClear\fR clears \fIsize\fR bytes, starting at \fIptr\fR.
  84. .SH FILES
  85. .nf
  86. ~em/modules/h/alloc.h
  87. ~em/modules/lib/liballoc.a
  88. .fi
  89. .SH "MODULES USED"
  90. system(3)
  91. .SH "SEE ALSO"
  92. malloc(3)
  93. .SH DIAGNOSTICS
  94. \fIMalloc\fR, \fISalloc\fR, \fIRealloc\fP, \fISrealloc\fR, and \fIst_alloc\fR
  95. call a routine \fINo_Mem\fR if there is no memory available. This routine
  96. is not supposed to return. A default one, that
  97. gives an error message and stops execution, is provided.
  98. .SH BUGS
  99. The
  100. .I st_alloc
  101. mechanism only works for structures that are large enough to contain one
  102. pointer.
  103. Also,
  104. .I st_free
  105. actually is a macro, and references its arguments more than once, so they
  106. better not have side-effects.