Summary

WG14 straw polls on N2699 (Sized Memory Deallocation) indicated directional support and support for its choice of names. Author homework was:

• A reflector discussion on calloc overflow handling.
• A new paper with a candidate for the final wording, as modified in reflector and committee discussion.

This is the promised paper.

Requested changes

These are the changes WG14 requested.

Paragraph 2 in each section has been changed from "If ptr is the result obtained from a call ..." to "If ptr is a null pointer or the result obtained from a call ...". This fixes the issue pointed out by Joseph Myers on the reflector, that the previous wording unintentionally made sized deallocation of null pointers undefined behavior if those pointers did not come from an allocation function (a divergence from existing implementations and other languages).

In the same paragraphs, "Otherwise, the result is undefined" has been changed to "Otherwise, the behavior is undefined". This is clearer, since these functions return void; there's not "result" per se.

Wording candidate 1

To be added to the memory management functions section (7.22.3, relative to n2596), with X and Y filled in by the editor as appropriate. This is the version with the minimal edits suggested in previous discussion.

7.22.3.X The free_sized function

Synopsis

1.

#include <stdlib.h>
void free_sized(void *ptr, size_t size);

Description

2. If ptr is a null pointer or the result obtained from a call to malloc(size), realloc(old_ptr, size), or calloc(nmemb, memb_size), where nmemb * memb_size is equal to size, this function behaves equivalently to free(ptr). Otherwise, the behavior is undefined.

3. NOTE: A conforming implementation may simply ignore size and call free.

4. NOTE: The result of an aligned_alloc call may not be passed to free_sized.

Recommended practice

5. Implementations may provide extensions to query the usable size of an allocation, or to determine the usable size of the allocation that would result if a request for some other size were to succeed. Such implementations should allow passing the resulting usable size as the size parameter, and provide functionality equivalent to free in such cases.

Returns

6. The free_sized function returns no value.

7.22.3.Y The free_aligned_sized function

Synopsis

1.

#include <stdlib.h>
void free_aligned_sized(void *ptr, size_t alignment, size_t size);

Description

2. If ptr is a null pointer or the result obtained from a call to aligned_alloc(alignment, size), this function behaves equivalently to free(ptr). Otherwise, the behavior is undefined.

3. NOTE: A conforming implementation may simply ignore size and alignment and call free.

4. NOTE: The result of a malloc, calloc, or realloc call may not be passed to free_aligned_sized.

Recommended practice

5. Implementations may provide extensions to query the usable size of an allocation, or to determine the usable size of the allocation that would result if a request for some other size were to succeed. Such implementations should allow passing the resulting usable size as the size parameter, and provide functionality equivalent to free in such cases.

Returns

6. The free_aligned_sized function returns no value.

Wording candidate 2

In review, Robert Seacord suggested some additional wording clarifications:

• Use the phrasing "is equivalent to", which better matches the wording in other parts of the standard (e.g. when defining printf in terms of fprintf).
• Omit references to the parameter names of the allocating functions, instead describing semantics in terms of the requested allocation sizes and alignments.
• Omit the word "simply" in describing the fallback to free.

This wording makes those changes (in addition to those above).

7.22.3.X The free_sized function

Synopsis

1.

#include <stdlib.h>
void free_sized(void *ptr, size_t size);

Description

2. If ptr is a null pointer or the result obtained from a call to malloc, realloc, or calloc, where size is equal to the requested allocation size, this function is equivalent to free(ptr). Otherwise, the behavior is undefined.

3. NOTE: A conforming implementation may ignore size and call free.

4. NOTE: The result of an aligned_alloc call may not be passed to free_sized.

Recommended practice

5. Implementations may provide extensions to query the usable size of an allocation, or to determine the usable size of the allocation that would result if a request for some other size were to succeed. Such implementations should allow passing the resulting usable size as the size parameter, and provide functionality equivalent to free in such cases.

Returns

6. The free_sized function returns no value.

7.22.3.Y The free_aligned_sized function

Synopsis

1.

#include <stdlib.h>
void free_aligned_sized(void *ptr, size_t alignment, size_t size);

Description

2. If ptr is a null pointer or the result obtained from a call to aligned_alloc(alignment, size), where alignment is equal to the requested allocation alignment and size is equal to the requested allocation size, this function is equivalent to free(ptr). Otherwise, the behavior is undefined.

3. NOTE: A conforming implementation may ignore size and alignment and call free.

4. NOTE: The result of a malloc, calloc, or realloc call may not be passed to free_aligned_sized.

Recommended practice

5. Implementations may provide extensions to query the usable size of an allocation, or to determine the usable size of the allocation that would result if a request for some other size were to succeed. Such implementations should allow passing the resulting usable size as the size parameter, and provide functionality equivalent to free in such cases.

Returns

6. The free_aligned_sized function returns no value.