[mLib] / man / alloc.3

.\" -*-nroff-*-
.TH alloc 3mLib "8 May 1999" "mLib"
.SH NAME
alloc \- mLib low-level memory allocation
.SH SYNOPSIS
.nf
.B "#include <mLib/alloc.h>"

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