Wording for “Memory allocation with size feedback”

Preamble

contributing

Chris Kennelly, Justin King, Charles Munger (rationale, history)

Charles Munger, Jens Gustedt, Joseph Myers (wording)

Related documents

LaTeX document branch

none yet

Liaison

liaisons to inform: WG21, Austin Group

Relevant polls

Would WG14 like to adopt something along the lines of N3899 and forward it to the Wording Group for C2y?

Justification of wording choices

In general, we chose to simplify additions to the standard. In particular, we refer to behavior of existing functions where this is possible and only mark the differences where they occur.

Naming

We propose to avoid stepping on our user’s toes and only to add new identifiers with a prefix. For functions and the proposed type we opted for a stdc_ prefix as we now have adopted it more widely in several places. For the struct members of stdc_alloc_result_t we opted for the prefix al_, in the line of such structure members in other parts of the standard, similar to the members of struct tm for example.

Exact versus minimal list of struct members

One option question was if the list of described members of stdc_alloc_result_t should be exact or if implementations should be allowed to add other implementation-defined members. In the text, the difference between the two would just be the word exactly or its omission in one place. We leave this as a decision between alternatives to WG14.

Wording adjustments

We also observed that each of the paragraphs 2 of free_sized (7.25.4.7) and free_aligned_sized (7.25.4.8) had wording problems.

1. They used “may” to express a user requirement. We propose to change this to “shall”.

2. Also both functions unconditionally stated that the result of certain allocation functions should not be used. If the allocation function returned a null pointer, evidently such a pointer can still be passed to a deallocation function. We propose to add the condition that the allocation call was successful.

Legend for the wording

Deletions in the shown standard text are as shown here, additions as shown here, code snippets as here. These may be rendered differently according to the style in which the document is shown by your browser but should always be well distinguishable. In the style provided there are two visual distinctions:

• A high contrast color palette (Okabe and Ito) namely using colors black, orange, teal green and light yellow
• normal text, strike through, underlining and typewriter font.

Close to each other proposed changes resemble like this.

Text presented with an orange background such as here, presents a possible omission in new wording (proposed to WG14 as alternative).

Proposed wording

At a suitable position, add to the list of types in 7.25 General utilities <stdlib.h>, 7.25.1 General p3

stdc_alloc_result_t

which is a structure type that is the type of the value returned by the stdc_alloc_at_least and stdc_aligned_alloc_at_least functions,

…

In 7.25.4.1 General

Modify p1

1 The order and contiguity of storage allocated by successive calls to the aligned_alloc, stdc_alloc_at_least, stdc_aligned_alloc_at_least, calloc, malloc, and realloc functions is unspecified. The pointer returned if the allocation succeeds is suitably aligned so that it can be assigned to a pointer to any type of object with a fundamental alignment requirement and size less than or equal to the size requested, or in the case of stdc_aligned_alloc_at_least and stdc_alloc_at_least, the size returned. It can then be used to access such an object or an array of such objects in the space allocated (until the space is explicitly deallocated). The lifetime of an allocated object extends from the allocation until the deallocation. Each such allocation shall yield a pointer to an object disjoint from any other object. The pointer returned points to the start (lowest byte address) of the allocated space. If the space cannot be allocated, a null pointer is returned. If the size of the space requested is zero, the behavior is implementation-defined: either a null pointer is returned to indicate an error, or the behavior is as if the size were some nonzero value, except that the returned pointer shall not be used to access an object.

Add a new paragraph (position at the discretion of the editor)

1′ The stdc_alloc_result_t structure shall contain exactly the following members, in either order:

void* al_ptr;
size_t al_size;

If the stdc_alloc_at_least and stdc_aligned_alloc_at_least functions successfully allocate an object, they return a structure where al_ptr is the address of the allocated object and the value of al_size is not 0 and is the size of the allocated object; otherwise al_ptr is a null pointer and al_size is 0.

Add a new subclause

Add a new subclause

Modify the description in

7.25.4.7 The free_sized function

…

Description

2 If ptr is a null pointer or if it is the result obtained from a call to malloc, realloc, or calloc, where size size is equal to the requested allocation size, this function is equivalent to free(ptr). If ptr and m are the resulting pointer and object size obtained from a call to stdc_alloc_at_least(n), and size is in the closed interval [n, m] this function is equivalent to free(ptr). Otherwise, the behavior is undefined. The result of an aligned_alloc call may not be passed to free_sized. The result of a successful call to aligned_alloc or stdc_aligned_alloc_at_least shall not be passed to free_sized.

Modify the description in

7.25.4.8 The free_aligned_sized function

…

Description

2 If ptr is a null pointer or if it is the result obtained from a call to aligned_alloc, 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). If ptr and m are the resulting pointer and object size obtained from a call to stdc_aligned_alloc_at_least(alignment, n), and size is in the closed interval [n, m] this function is equivalent to free(ptr). Otherwise, the behavior is undefined. The result of an malloc, calloc, or realloc call may not be passed to free_aligned_sized. The result of a successful call to malloc, calloc, realloc, or stdc_alloc_at_least shall not be passed to free_aligned_sized.