Difference between revisions of "cpp/memory/c/free"
(Changed conditional to better express ownership) |
Andreas Krug (Talk | contribs) m ({{c}}, ., fmt) |
||
| Line 1: | Line 1: | ||
{{cpp/title|free}} | {{cpp/title|free}} | ||
{{cpp/memory/c/navbar}} | {{cpp/memory/c/navbar}} | ||
| − | {{ddcl | header=cstdlib | | + | {{ddcl|header=cstdlib| |
void free( void* ptr ); | void free( void* ptr ); | ||
}} | }} | ||
| Line 7: | Line 7: | ||
Deallocates the space previously allocated by {{lc|std::malloc}}, {{lc|std::calloc}}{{rev inl|since=c++17|, {{lc|std::aligned_alloc}}}}, or {{lc|std::realloc}}. | Deallocates the space previously allocated by {{lc|std::malloc}}, {{lc|std::calloc}}{{rev inl|since=c++17|, {{lc|std::aligned_alloc}}}}, or {{lc|std::realloc}}. | ||
| − | If {{ | + | If {{c|ptr}} is a null pointer, the function does nothing. |
| − | The behavior is undefined if the value of {{ | + | The behavior is undefined if the value of {{c|ptr}} does not equal a value returned earlier by {{lc|std::malloc}}, {{lc|std::calloc}}{{rev inl|since=c++17|, {{lc|std::aligned_alloc}}}}, or {{lc|std::realloc}}. |
| − | The behavior is undefined if the memory area referred to by {{ | + | The behavior is undefined if the memory area referred to by {{c|ptr}} has already been deallocated, that is, {{tt|std::free}} or {{lc|std::realloc}} has already been called with {{c|ptr}} as the argument and no calls to {{lc|std::malloc}}, {{lc|std::calloc}}{{rev inl|since=c++17|, {{lc|std::aligned_alloc}}}}, or {{lc|std::realloc}} resulted in a pointer equal to {{c|ptr}} afterwards. |
| − | The behavior is undefined if after {{tt|std::free}} returns, an access is made through the pointer {{ | + | The behavior is undefined if after {{tt|std::free}} returns, an access is made through the pointer {{c|ptr}} (unless another allocation function happened to result in a pointer value equal to {{c|ptr}}). |
{{cpp/memory/thread_safety_note}} | {{cpp/memory/thread_safety_note}} | ||
| Line 19: | Line 19: | ||
===Parameters=== | ===Parameters=== | ||
{{par begin}} | {{par begin}} | ||
| − | {{par | ptr | pointer to the memory to deallocate}} | + | {{par|ptr|pointer to the memory to deallocate}} |
{{par end}} | {{par end}} | ||
| Line 34: | Line 34: | ||
int main() | int main() | ||
{ | { | ||
| − | int* p1 = (int*)std::malloc(10*sizeof *p1); | + | int* p1 = (int*)std::malloc(10 * sizeof *p1); |
std::free(p1); // every allocated pointer must be freed | std::free(p1); // every allocated pointer must be freed | ||
int* p2 = (int*)std::calloc(10, sizeof *p2); | int* p2 = (int*)std::calloc(10, sizeof *p2); | ||
| − | int* p3 = (int*)std::realloc(p2, 1000*sizeof *p3); | + | int* p3 = (int*)std::realloc(p2, 1000 * sizeof *p3); |
| − | if(!p3) // p3 null means realloc failed and p2 must be freed. | + | if (!p3) // p3 null means realloc failed and p2 must be freed. |
| − | + | std::free(p2); | |
std::free(p3); // p3 can be freed whether or not it is null. | std::free(p3); // p3 can be freed whether or not it is null. | ||
} | } | ||
| Line 47: | Line 47: | ||
===See also=== | ===See also=== | ||
{{dsc begin}} | {{dsc begin}} | ||
| − | {{dsc see c | c/memory/free}} | + | {{dsc see c|c/memory/free}} |
{{dsc end}} | {{dsc end}} | ||
{{langlinks|de|es|fr|it|ja|pl|pt|ru|zh}} | {{langlinks|de|es|fr|it|ja|pl|pt|ru|zh}} | ||
Latest revision as of 11:17, 12 June 2023
| Defined in header <cstdlib>
|
||
| void free( void* ptr ); |
||
Deallocates the space previously allocated by std::malloc, std::calloc, std::aligned_alloc(since C++17), or std::realloc.
If ptr is a null pointer, the function does nothing.
The behavior is undefined if the value of ptr does not equal a value returned earlier by std::malloc, std::calloc, std::aligned_alloc(since C++17), or std::realloc.
The behavior is undefined if the memory area referred to by ptr has already been deallocated, that is, std::free or std::realloc has already been called with ptr as the argument and no calls to std::malloc, std::calloc, std::aligned_alloc(since C++17), or std::realloc resulted in a pointer equal to ptr afterwards.
The behavior is undefined if after std::free returns, an access is made through the pointer ptr (unless another allocation function happened to result in a pointer value equal to ptr).
|
The following functions are required to be thread-safe:
Calls to these functions that allocate or deallocate a particular unit of storage occur in a single total order, and each such deallocation call happens-before the next allocation (if any) in this order. |
(since C++11) |
Contents |
[edit] Parameters
| ptr | - | pointer to the memory to deallocate |
[edit] Return value
(none)
[edit] Notes
The function accepts (and does nothing with) the null pointer to reduce the amount of special-casing. Whether allocation succeeds or not, the pointer returned by an allocation function can be passed to std::free.
[edit] Example
#include <cstdlib> int main() { int* p1 = (int*)std::malloc(10 * sizeof *p1); std::free(p1); // every allocated pointer must be freed int* p2 = (int*)std::calloc(10, sizeof *p2); int* p3 = (int*)std::realloc(p2, 1000 * sizeof *p3); if (!p3) // p3 null means realloc failed and p2 must be freed. std::free(p2); std::free(p3); // p3 can be freed whether or not it is null. }
[edit] See also
| C documentation for free
|
