[unix-history] / usr / man / man3 / malloc.3

.TH MALLOC 3 
.SH NAME
malloc, free, realloc, calloc \- main memory allocator
.SH SYNOPSIS
.B char *malloc(size)
.br
.B unsigned size;
.PP
.B free(ptr)
.br
.B char *ptr;
.PP
.B char *realloc(ptr, size)
.br
.B char *ptr;
.br
.B unsigned size;
.PP
.B char *calloc(nelem, elsize)
.br
.B unsigned nelem, elsize;
.SH DESCRIPTION
.I Malloc
and
.I free
provide a simple general-purpose memory allocation package.
.I Malloc
returns a pointer to a block of at least
.I size
bytes beginning on a word boundary.
.PP
The argument to
.I free
is a pointer to a block previously allocated by
.IR malloc ;
this space is made available for further allocation,
but its contents are left undisturbed.
.PP
Needless to say, grave disorder will result if the space
assigned by
.I malloc
is overrun or if some random number is handed to
.IR free .
.PP
.I Malloc
allocates the first big enough contiguous reach of
free space
found in a circular search from the last 
block allocated or freed,
coalescing adjacent free blocks as it searches.
It calls
.I sbrk
(see
.IR break (2))
to get more memory from the system when there is no
suitable space already free.
.PP
.I Realloc
changes the size of the block pointed to by
.I ptr
to
.I size
bytes and returns a pointer to the (possibly moved)
block.
The contents will be unchanged up to the
lesser of the new and old sizes.
.PP
.I Realloc
also works if
.I ptr
points to a block freed since the last call of
.I malloc, realloc
or
.IR calloc ;
thus sequences of
.I free, malloc
and
.I realloc
can exploit the search strategy of
.I malloc
to do storage compaction.
.PP
.I Calloc
allocates space for
an array of
.I nelem
elements of size
.I elsize.
The space is initialized to zeros.
.PP
Each of the allocation routines returns a pointer
to space suitably aligned (after possible pointer coercion)
for storage of any type of object.
.SH DIAGNOSTICS
.I Malloc, realloc
and
.I calloc
return a null pointer (0) if there is no available memory
or if the arena has been detectably corrupted by storing outside the bounds
of a block.
.I Malloc
may be recompiled to check the arena very stringently
on every transaction;
see the source code.
.SH BUGS
When
.I realloc
returns 0,
the block
pointed to by
.I ptr
may be destroyed.
Commit	Line	Data
f84a56bb TL	1	.TH MALLOC 3
	2	.SH NAME
	3	malloc, free, realloc, calloc \- main memory allocator
	4	.SH SYNOPSIS
	5	.B char *malloc(size)
	6	.br
	7	.B unsigned size;
	8	.PP
	9	.B free(ptr)
	10	.br
	11	.B char *ptr;
	12	.PP
	13	.B char *realloc(ptr, size)
	14	.br
	15	.B char *ptr;
	16	.br
	17	.B unsigned size;
	18	.PP
	19	.B char *calloc(nelem, elsize)
	20	.br
	21	.B unsigned nelem, elsize;
	22	.SH DESCRIPTION
	23	.I Malloc
	24	and
	25	.I free
	26	provide a simple general-purpose memory allocation package.
	27	.I Malloc
	28	returns a pointer to a block of at least
	29	.I size
	30	bytes beginning on a word boundary.
	31	.PP
	32	The argument to
	33	.I free
	34	is a pointer to a block previously allocated by
	35	.IR malloc ;
	36	this space is made available for further allocation,
	37	but its contents are left undisturbed.
	38	.PP
	39	Needless to say, grave disorder will result if the space
	40	assigned by
	41	.I malloc
	42	is overrun or if some random number is handed to
	43	.IR free .
	44	.PP
	45	.I Malloc
	46	allocates the first big enough contiguous reach of
	47	free space
	48	found in a circular search from the last
	49	block allocated or freed,
	50	coalescing adjacent free blocks as it searches.
	51	It calls
	52	.I sbrk
	53	(see
	54	.IR break (2))
	55	to get more memory from the system when there is no
	56	suitable space already free.
	57	.PP
	58	.I Realloc
	59	changes the size of the block pointed to by
	60	.I ptr
	61	to
	62	.I size
	63	bytes and returns a pointer to the (possibly moved)
	64	block.
65	The contents will be unchanged up to the
66	lesser of the new and old sizes.
67	.PP
68	.I Realloc
69	also works if
70	.I ptr
71	points to a block freed since the last call of
72	.I malloc, realloc
73	or
74	.IR calloc ;
75	thus sequences of
76	.I free, malloc
77	and
78	.I realloc
79	can exploit the search strategy of
80	.I malloc
81	to do storage compaction.
82	.PP
83	.I Calloc
84	allocates space for
85	an array of
86	.I nelem
87	elements of size
88	.I elsize.
89	The space is initialized to zeros.
90	.PP
91	Each of the allocation routines returns a pointer
92	to space suitably aligned (after possible pointer coercion)
93	for storage of any type of object.
94	.SH DIAGNOSTICS
95	.I Malloc, realloc
96	and
97	.I calloc
98	return a null pointer (0) if there is no available memory
99	or if the arena has been detectably corrupted by storing outside the bounds
100	of a block.
101	.I Malloc
102	may be recompiled to check the arena very stringently
103	on every transaction;
104	see the source code.
105	.SH BUGS
106	When
107	.I realloc
108	returns 0,
109	the block
110	pointed to by
111	.I ptr
112	may be destroyed.