logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

realloc.3p (5600B)


  1. '\" et
  2. .TH REALLOC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. realloc
  12. \(em memory reallocator
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdlib.h>
  17. .P
  18. void *realloc(void *\fIptr\fP, size_t \fIsize\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The functionality described on this reference page is aligned with the
  22. ISO\ C standard. Any conflict between the requirements described here and the
  23. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  24. .P
  25. The
  26. \fIrealloc\fR()
  27. function shall deallocate the old object pointed to by
  28. .IR ptr
  29. and return a pointer to a new object that has the size specified by
  30. .IR size .
  31. The contents of the new object shall be the same as that of the old
  32. object prior to deallocation, up to the lesser of the new and old
  33. sizes. Any bytes in the new object beyond the size of the old object
  34. have indeterminate values. If the size of the space requested is zero,
  35. the behavior shall be implementation-defined: either a null pointer is
  36. returned, or the behavior shall be as if the size were some non-zero
  37. value, except that the behavior is undefined if the returned pointer
  38. is used to access an object. If the space cannot be allocated,
  39. the object shall remain unchanged.
  40. .P
  41. If
  42. .IR ptr
  43. is a null pointer,
  44. \fIrealloc\fR()
  45. shall be equivalent to
  46. \fImalloc\fR()
  47. for the specified size.
  48. .P
  49. If
  50. .IR ptr
  51. does not match a pointer returned earlier by
  52. \fIcalloc\fR(),
  53. \fImalloc\fR(),
  54. or
  55. \fIrealloc\fR()
  56. or if the space has previously been deallocated by a call to
  57. \fIfree\fR()
  58. or
  59. \fIrealloc\fR(),
  60. the behavior is undefined.
  61. .P
  62. The order and contiguity of storage allocated by successive calls to
  63. \fIrealloc\fR()
  64. is unspecified. The pointer returned if the allocation succeeds shall
  65. be suitably aligned so that it may be assigned to a pointer to any type
  66. of object and then used to access such an object in the space allocated
  67. (until the space is explicitly freed or reallocated). Each such
  68. allocation shall yield a pointer to an object disjoint from any other
  69. object. The pointer returned shall point to the start (lowest byte
  70. address) of the allocated space. If the space cannot be allocated, a
  71. null pointer shall be returned.
  72. .SH "RETURN VALUE"
  73. Upon successful completion,
  74. \fIrealloc\fR()
  75. shall return a pointer to the (possibly moved) allocated space. If
  76. .IR size
  77. is 0, either:
  78. .IP " *" 4
  79. A null pointer shall be returned
  80. and, if
  81. .IR ptr
  82. is not a null pointer,
  83. .IR errno
  84. shall be set to an implementation-defined value.
  85. .IP " *" 4
  86. A pointer to the allocated space shall be returned, and the
  87. memory object pointed to by
  88. .IR ptr
  89. shall be freed. The application shall ensure that the pointer is not
  90. used to access an object.
  91. .P
  92. If there is not enough available memory,
  93. \fIrealloc\fR()
  94. shall return a null pointer
  95. and set
  96. .IR errno
  97. to
  98. .BR [ENOMEM] .
  99. If
  100. \fIrealloc\fR()
  101. returns a null pointer
  102. and
  103. .IR errno
  104. has been set to
  105. .BR [ENOMEM] ,
  106. the memory referenced by
  107. .IR ptr
  108. shall not be changed.
  109. .SH ERRORS
  110. The
  111. \fIrealloc\fR()
  112. function shall fail if:
  113. .TP
  114. .BR ENOMEM
  115. Insufficient memory is available.
  116. .LP
  117. .IR "The following sections are informative."
  118. .SH EXAMPLES
  119. None.
  120. .SH "APPLICATION USAGE"
  121. The description of
  122. \fIrealloc\fR()
  123. has been modified from previous versions of this standard to align
  124. with the ISO/IEC\ 9899:\|1999 standard. Previous versions explicitly permitted a call to
  125. .IR realloc \c
  126. (\fIp\fI, 0) to free the space pointed to by
  127. .IR p
  128. and return a null pointer. While this behavior could be interpreted as
  129. permitted by this version of the standard, the C language committee have
  130. indicated that this interpretation is incorrect. Applications should
  131. assume that if
  132. \fIrealloc\fR()
  133. returns a null pointer, the space pointed to by
  134. .IR p
  135. has not been freed. Since this could lead to double-frees, implementations
  136. should also set
  137. .IR errno
  138. if a null pointer actually indicates a failure, and applications should
  139. only free the space if
  140. .IR errno
  141. was changed.
  142. .SH RATIONALE
  143. None.
  144. .SH "FUTURE DIRECTIONS"
  145. This standard defers to the ISO\ C standard. While that standard currently has
  146. language that might permit
  147. .IR realloc \c
  148. (\fIp\fI, 0), where
  149. .IR p
  150. is not a null pointer, to free
  151. .IR p
  152. while still returning a null pointer, the committee responsible for that
  153. standard is considering clarifying the language to explicitly prohibit
  154. that alternative.
  155. .SH "SEE ALSO"
  156. .IR "\fIcalloc\fR\^(\|)",
  157. .IR "\fIfree\fR\^(\|)",
  158. .IR "\fImalloc\fR\^(\|)"
  159. .P
  160. The Base Definitions volume of POSIX.1\(hy2017,
  161. .IR "\fB<stdlib.h>\fP"
  162. .\"
  163. .SH COPYRIGHT
  164. Portions of this text are reprinted and reproduced in electronic form
  165. from IEEE Std 1003.1-2017, Standard for Information Technology
  166. -- Portable Operating System Interface (POSIX), The Open Group Base
  167. Specifications Issue 7, 2018 Edition,
  168. Copyright (C) 2018 by the Institute of
  169. Electrical and Electronics Engineers, Inc and The Open Group.
  170. In the event of any discrepancy between this version and the original IEEE and
  171. The Open Group Standard, the original IEEE and The Open Group Standard
  172. is the referee document. The original Standard can be obtained online at
  173. http://www.opengroup.org/unix/online.html .
  174. .PP
  175. Any typographical or formatting errors that appear
  176. in this page are most likely
  177. to have been introduced during the conversion of the source files to
  178. man page format. To report such errors, see
  179. https://www.kernel.org/doc/man-pages/reporting_bugs.html .