195 lines
4.8 KiB
Plaintext
195 lines
4.8 KiB
Plaintext
'\"macro stdmacro
|
|
.if n .pH g3c.malloc @(#)malloc 30.3 of 1/19/86
|
|
.nr X
|
|
.if \nX=0 .ds x} MALLOC 3C "C Programming Language Utilities" "\&"
|
|
.if \nX=1 .ds x} MALLOC 3C "C Programming Language Utilities"
|
|
.if \nX=2 .ds x} MALLOC 3C "" "\&"
|
|
.if \nX=3 .ds x} MALLOC "" "" "\&"
|
|
.TH \*(x}
|
|
.SH NAME
|
|
malloc, free, realloc, calloc, memalign, valloc \- main memory allocator
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <stdlib.h>
|
|
.P
|
|
.B void \(**malloc (size_t size);
|
|
.PP
|
|
.B void free (void \(**ptr);
|
|
.PP
|
|
.B void \(**realloc (void \(**ptr, size_t size);
|
|
.PP
|
|
.B void \(**calloc (size_t nelem, size_t elsize);
|
|
.PP
|
|
.B void \(**memalign (size_t alignment, size_t size);
|
|
.PP
|
|
.B void \(**valloc (size_t size);
|
|
.SH DESCRIPTION
|
|
.B malloc\^
|
|
and
|
|
.B free\^
|
|
provide a simple general-purpose memory allocation package.
|
|
.B malloc\^
|
|
returns a pointer to a block of at least
|
|
.I size\^
|
|
bytes suitably aligned for any use.
|
|
.PP
|
|
The argument to
|
|
.B free\^
|
|
is a pointer to a block previously allocated by
|
|
.BR malloc ;
|
|
after
|
|
.B free\^
|
|
is performed this space is made available for further allocation,
|
|
but its contents are left undisturbed.
|
|
.PP
|
|
Undefined results will occur if the space
|
|
allocated by
|
|
.B malloc\^
|
|
is overrun or if some random value is passed as the argument to
|
|
.BR free .
|
|
.PP
|
|
.B 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
|
|
.B sbrk\^
|
|
[see \f4brk\fP(2)]
|
|
to get more memory from the system when there is no
|
|
suitable space already free.
|
|
.PP
|
|
.B 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.
|
|
If no free block of
|
|
.I size\^
|
|
bytes is available in the storage arena, then
|
|
.B realloc\^
|
|
will ask
|
|
.B malloc\^
|
|
to enlarge the arena by
|
|
.I size\^
|
|
bytes and will then move the data to the new space.
|
|
If
|
|
.I ptr\^
|
|
is NULL,
|
|
.B realloc
|
|
behaves like \f4malloc\fP(\f2size\fP).
|
|
If
|
|
.I size
|
|
is zero, the storage associated with
|
|
.I ptr
|
|
is freed and
|
|
.B realloc
|
|
returns the same result as does
|
|
.BR malloc (0).
|
|
.\".PP
|
|
.\".I Realloc\^
|
|
.\"also works if
|
|
.\".I ptr\^
|
|
.\"points to a block freed since the last call of
|
|
.\".IR malloc ,
|
|
.\".IR realloc ,
|
|
.\"or
|
|
.\".IR calloc ;
|
|
.\"thus sequences of
|
|
.\".IR free ,
|
|
.\".I malloc\^
|
|
.\"and
|
|
.\".I realloc\^
|
|
.\"can exploit the search strategy of
|
|
.\".I malloc\^
|
|
.\"to do storage compaction.
|
|
.PP
|
|
.B calloc\^
|
|
allocates space for
|
|
an array of
|
|
.I nelem\^
|
|
elements of size
|
|
.IR elsize .
|
|
The space is initialized to zeros.
|
|
.PP
|
|
.B memalign\^
|
|
allocates
|
|
.I size
|
|
bytes on a specified alignment
|
|
boundary and returns a pointer to the allocated block.
|
|
The value of the returned address is guaranteed to be a
|
|
multiple of \f2alignment\fP. Note that the value of \f2alignment\fP must be
|
|
a power of two and must be greater than or equal to the size
|
|
of a word, or, for 64 bit objects, the size of a doubleword.
|
|
.PP
|
|
\f4valloc\fP(\f2size\fP)
|
|
is equivalent to
|
|
\f4memalign\fP(\f4sysconf\fP(\f4_SC_PAGESIZE\fP),\f2size\fP).
|
|
For more information see \f4sysconf\f1(3c).
|
|
.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 "SEE ALSO"
|
|
brk(2), sysconf(3c), malloc(3X)
|
|
.SH DIAGNOSTICS
|
|
.BR malloc ,
|
|
.B realloc\^,
|
|
.B calloc\^,
|
|
.B memalign\^,
|
|
and
|
|
.B valloc\^
|
|
return a
|
|
.SM NULL
|
|
pointer if there is no available memory
|
|
or if the arena has been detectably corrupted by storing outside the bounds
|
|
of a block.
|
|
When this happens
|
|
the block
|
|
pointed to by
|
|
.I ptr\^
|
|
may be destroyed.
|
|
.SH NOTES
|
|
How an application manages its heap can greatly affect the performance
|
|
of these routines. For most applications, this set will perform well.
|
|
For some applications, the more flexible \f4malloc\fP(3X) package
|
|
might be more appropriate.
|
|
.PP
|
|
A SEGV or Bus Error inside the
|
|
.B malloc\^
|
|
routine is almost certainly caused by a previous memory overwrite by the
|
|
user. This is a delayed error which is caused by a previous overwrite of
|
|
unallocated memory and is not a bug in
|
|
.B malloc\^
|
|
itself.
|
|
.PP
|
|
When called with
|
|
.I size\^
|
|
of zero,
|
|
.B malloc\^
|
|
returns a valid pointer to a block of zero bytes. Storage into a block
|
|
of length zero will corrupt the
|
|
.B malloc
|
|
arena and may have serious consequences.
|
|
.PP
|
|
Products, libraries, or commands that provide their own
|
|
.B malloc
|
|
package must provide all of the entry points listed above, or the normal
|
|
\f4libc malloc\fP entry point for the unimplemented routine(s)
|
|
may be called instead, leading to
|
|
corrupted heaps, since it is unlikely that the internal details of the heap
|
|
management will be the same. If the
|
|
.B malloc
|
|
package is also intended
|
|
to replace
|
|
.BR malloc (3X),
|
|
it must also provide the additional routines listed there.
|
|
'\".so /pubs/tools/origin.att
|
|
.\" @(#)malloc.3c 6.3 of 10/20/83
|
|
.Ee
|