.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "REALLOC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" realloc 
.SH NAME
realloc \- memory reallocator
.SH SYNOPSIS
.LP
\fB#include <stdlib.h>
.br
.sp
void *realloc(void *\fP\fIptr\fP\fB, size_t\fP \fIsize\fP\fB);
.br
\fP
.SH DESCRIPTION
.LP
The \fIrealloc\fP() function shall change the size of the memory object
pointed to by \fIptr\fP to the size specified by
\fIsize\fP. The contents of the object shall remain unchanged up to
the lesser of the new and old sizes. If the new size of the
memory object would require movement of the object, the space for
the previous instantiation of the object is freed. If the new
size is larger, the contents of the newly allocated portion of the
object are unspecified. If \fIsize\fP is 0 and \fIptr\fP is
not a null pointer, the object pointed to is freed. If the space cannot
be allocated, the object shall remain unchanged.
.LP
If \fIptr\fP is a null pointer, \fIrealloc\fP() shall be equivalent
to \fImalloc\fP()
for the specified size.
.LP
If \fIptr\fP does not match a pointer returned earlier by \fIcalloc\fP(),
\fImalloc\fP(), or \fIrealloc\fP() or if the space has previously
been deallocated by a call to \fIfree\fP() or \fIrealloc\fP(), the
behavior is undefined.
.LP
The order and contiguity of storage allocated by successive calls
to \fIrealloc\fP() is unspecified. The pointer returned if
the allocation succeeds shall be suitably aligned so that it may be
assigned to a pointer to any type of object and then used to
access such an object in the space allocated (until the space is explicitly
freed or reallocated). Each such allocation shall yield
a pointer to an object disjoint from any other object. The pointer
returned shall point to the start (lowest byte address) of the
allocated space. If the space cannot be allocated, a null pointer
shall be returned.
.SH RETURN VALUE
.LP
Upon successful completion with a size not equal to 0, \fIrealloc\fP()
shall return a pointer to the (possibly moved) allocated
space. If \fIsize\fP is 0, either a null pointer or a unique pointer
that can be successfully passed to \fIfree\fP() shall be returned.
If there is not enough available memory, \fIrealloc\fP() shall
return a null pointer   \ and set \fIerrno\fP to [ENOMEM]. 
.SH ERRORS
.LP
The \fIrealloc\fP() function shall fail if:
.TP 7
.B ENOMEM
Insufficient memory is available. 
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIcalloc\fP() , \fIfree\fP() , \fImalloc\fP() ,
the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<stdlib.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .