malloc.3

<B>Digital的Unix操作系统VAX 4.2源码</B>

.\" SCCSID: @(#)malloc.3	3.1	11/24/87
.TH malloc 3 RISC
.SH Name
malloc, free, realloc, calloc, alloca \- memory allocator
.SH Syntax
.nf
.B char *malloc(size)
.B unsigned size;
.PP
.B free(ptr)
.B void *ptr;
.PP
.B char *realloc(ptr, size)
.B void *ptr;
.B unsigned size;
.PP
.B char *calloc(nelem, elsize)
.B unsigned nelem, elsize;
.PP
.B char *alloca(size)
.B int size;
.fi
.SH Description
.NXR "malloc subroutine (standard C)"
.NXR "free subroutine (standard C)"
.NXR "realloc subroutine (standard C)"
.NXR "calloc subroutine (standard C)"
.NXR "alloca subroutine"
.NXA "memory" "shared memory"
.NXR "memory" "allocating"
The
.PN malloc
and
.PN free
subroutines
provide a simple general-purpose memory allocation package.
The
.PN malloc
subroutine
returns a pointer to a block of at least
.I size
bytes beginning on a word boundary.
.PP
The argument to
.PN free
is a pointer to a block previously allocated by
.PN 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
.PN malloc
is overrun or if some random number is handed to
.PN free .
.PP
The
.PN malloc
subroutine
maintains multiple lists of free blocks according to size,
allocating space from the appropriate list.
It calls
.PN sbrk
to get more memory from the system when there is no
suitable space already free.
For further information, see 
.MS brk 2 .
.PP
The
.PN realloc
subroutine 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
In order to be compatible with older versions,
.PN realloc
also works if
.I ptr
points to a block freed since the last call of
.PN malloc ,
.PN realloc ,
or
.PN calloc .
Sequences of
.PN free ,
.PN malloc, 
and
.PN realloc
were previously used to attempt storage compaction.
This procedure is no longer recommended.
.PP
The
.PN calloc
subroutine allocates space for an array of
.I nelem
elements of size
.I elsize.
The space is initialized to zeros.
.PP
.\"VAX
.\"The
.\".PN alloca
.\"subroutine allocates 
.\".I size
.\"bytes of space in the stack frame of the caller.
.\"This temporary space is automatically freed on
.\"return.
The
.PN alloca
subroutine allocates 
.I size
bytes of space associated with the stack frame of the caller.
This temporary space is available for reuse when the caller returns.
On MIPS machines, calling
.PN alloca (0)
reclaims all available storage.  On VAX machines, the space is
automatically freed on return.
.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 Restrictions
.NXR "malloc subroutine (standard C)" "restricted"
When
.PN realloc
returns 0, the block pointed to by
.I ptr
may be destroyed.
.PP
Currently, the allocator is unsuitable for direct use in a large
virtual environment where many small blocks are kept, 
since it keeps all allocated and freed blocks on a circular
list.
Just before more memory is allocated,
all allocated and freed blocks are referenced.
.PP
.\"VAX
.\"The
.\".PN alloca
.\"subroutine is machine dependent.
Because the
.PN alloca
subroutine is machine dependent,
its use should be avoided.
.SH Diagnostics
The
.PN malloc ,
.PN realloc ,
and
.PN calloc
subroutines
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.