b6b9d458 |
1 | .\" -*-nroff-*- |
08da152e |
2 | .TH alloc 3 "8 May 1999" "mLib" |
3 | .\" @xmalloc |
4 | .\" @xrealloc |
5 | .\" @xstrdup |
b6b9d458 |
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), |
08da152e |
68 | .BR exc (3), |
69 | .BR mLib (3). |
b6b9d458 |
70 | .SH AUTHOR |
71 | Mark Wooding, <mdw@nsict.org> |
72 | |