| 1 | .\" -*-nroff-*- |
| 2 | .TH alloc 3 "8 May 1999" "mLib" |
| 3 | .\" @xmalloc |
| 4 | .\" @xrealloc |
| 5 | .\" @xstrdup |
| 6 | .SH NAME |
| 7 | alloc \- mLib low-level memory allocation |
| 8 | .SH SYNOPSIS |
| 9 | .nf |
| 10 | .B "#include <mLib/alloc.h>" |
| 11 | |
| 12 | .BI "void *xmalloc(size_t " sz ); |
| 13 | .BI "void *xrealloc(void *" p ", size_t " sz ); |
| 14 | .BI "char *xstrdup(const char *" s ); |
| 15 | .fi |
| 16 | .SH DESCRIPTION |
| 17 | These functions allocate and return blocks of memory. If insufficient |
| 18 | memory is available, an |
| 19 | .B EXC_NOMEM |
| 20 | exception is raised. |
| 21 | .PP |
| 22 | The |
| 23 | .B xmalloc |
| 24 | and |
| 25 | .B xrealloc |
| 26 | functions are veneers over the standard |
| 27 | .BR malloc (3) |
| 28 | and |
| 29 | .BR realloc (3) |
| 30 | functions. |
| 31 | .B xmalloc |
| 32 | allocates a block of |
| 33 | .I sz |
| 34 | bytes and returns a pointer to the base of the block; |
| 35 | .B xrealloc |
| 36 | is given a pointer |
| 37 | .I p |
| 38 | to a block of memory, and returns the address of a new block of size |
| 39 | .I sz |
| 40 | bytes with the same contents as the original one (either truncated, if |
| 41 | the new block is smaller, or padded with rubbish at the end if bigger). |
| 42 | .PP |
| 43 | The |
| 44 | .B xstrdup |
| 45 | function allocates and returns a block of memory containing a copy of |
| 46 | the null-terminated string |
| 47 | .IR p . |
| 48 | The block is just large enough for the string and its null terminator. |
| 49 | .PP |
| 50 | The memory blocks allocated by these functions can be released by |
| 51 | calling the standard |
| 52 | .BR free (3) |
| 53 | function. |
| 54 | .SH "RETURN VALUE" |
| 55 | The |
| 56 | .BR xmalloc , |
| 57 | .B xrealloc |
| 58 | and |
| 59 | .B xstrdup |
| 60 | functions return pointers to the blocks they allocated. They do not |
| 61 | return if a block couldn't be allocated; instead, the exception |
| 62 | .B EXC_NOMEM |
| 63 | is raised. |
| 64 | .SH "SEE ALSO" |
| 65 | .BR malloc (3), |
| 66 | .BR realloc (3), |
| 67 | .BR free (3), |
| 68 | .BR exc (3), |
| 69 | .BR mLib (3). |
| 70 | .SH AUTHOR |
| 71 | Mark Wooding, <mdw@nsict.org> |
| 72 | |