Provided by: manpages-posix-dev_2013a-2_all bug

PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of
       this interface may differ (consult the corresponding Linux  manual  page  for  details  of
       Linux behavior), or the interface may not be implemented on Linux.

NAME

       realloc — memory reallocator

SYNOPSIS

       #include <stdlib.h>

       void *realloc(void *ptr, size_t size);

DESCRIPTION

       The functionality described on this reference page is aligned with the ISO C standard. Any
       conflict between the requirements described here and the ISO C standard is  unintentional.
       This volume of POSIX.1‐2008 defers to the ISO C standard.

       The  realloc()  function  shall  deallocate  the old object pointed to by ptr and return a
       pointer to a new object that has the size specified by size.   The  contents  of  the  new
       object shall be the same as that of the old object prior to deallocation, up to the lesser
       of the new and old sizes. Any bytes in the new object beyond the size of  the  old  object
       have  indeterminate values. If the size of the space requested is zero, the behavior shall
       be implementation-defined: either a null pointer is returned, or the behavior shall be  as
       if  the  size were some non-zero value, except that the returned pointer shall not be used
       to access an object. If the space cannot be allocated, the object shall remain unchanged.

       If ptr is a null pointer, realloc() shall be equivalent  to  malloc()  for  the  specified
       size.

       If ptr does not match a pointer returned earlier by calloc(), malloc(), or realloc() or if
       the space has previously been deallocated by a call to free() or realloc(),  the  behavior
       is undefined.

       The  order  and  contiguity  of  storage  allocated  by  successive  calls to realloc() 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.

RETURN VALUE

       Upon  successful  completion,  realloc()  shall  return  a pointer to the (possibly moved)
       allocated space. If size is 0, either:

        *  A null pointer shall be returned and errno set to an implementation-defined value.

        *  A unique pointer that can be successfully passed to free() shall be returned, and  the
           memory  object pointed to by ptr shall be freed. The application shall ensure that the
           pointer is not used to access an object.

       If there is not enough available memory, realloc() shall return a  null  pointer  and  set
       errno  to  [ENOMEM].   If  realloc()  returns  a  null  pointer  and errno has been set to
       [ENOMEM], the memory referenced by ptr shall not be changed.

ERRORS

       The realloc() function shall fail if:

       ENOMEM Insufficient memory is available.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       The description of realloc() has been modified from previous versions of this standard  to
       align  with  the ISO/IEC 9899:1999 standard. Previous versions explicitly permitted a call
       to realloc(p, 0) to free the space pointed to by p and return a null pointer.  While  this
       behavior could be interpreted as permitted by this version of the standard, the C language
       committee have indicated that this interpretation is incorrect. Applications should assume
       that  if  realloc()  returns a null pointer, the space pointed to by p has not been freed.
       Since this could lead to double-frees, implementations should also set  errno  if  a  null
       pointer actually indicates a failure, and applications should only free the space if errno
       was changed.

RATIONALE

       None.

FUTURE DIRECTIONS

       This standard defers to the ISO C standard. While that  standard  currently  has  language
       that  might  permit  realloc(p,  0),  where p is not a null pointer, to free p while still
       returning a null pointer, the committee  responsible  for  that  standard  is  considering
       clarifying the language to explicitly prohibit that alternative.

SEE ALSO

       calloc(), free(), malloc()

       The Base Definitions volume of POSIX.1‐2008, <stdlib.h>

COPYRIGHT

       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2013 Edition, Standard for Information Technology  --  Portable  Operating  System
       Interface  (POSIX),  The Open Group Base Specifications Issue 7, Copyright (C) 2013 by the
       Institute of Electrical and Electronics Engineers, Inc  and  The  Open  Group.   (This  is
       POSIX.1-2008  with  the  2013  Technical  Corrigendum  1  applied.)  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.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are most  likely  to  have
       been  introduced  during  the conversion of the source files to man page format. To report
       such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .