This document describes how functions named with a trailing C are handled on the stack.
The case of allocating an object and pushing it to the cleanup stack is
sufficiently common that allocation functions are often coded to do both in
a single operation. For example, there is a User::AllocLC()
whose
semantics are to call User::Alloc()
to allocate the memory,
leave if the allocation failed, and push to the cleanup stack if it succeeded.
The trailing C
indicates that the item is pushed to the
cleanup stack if successfully allocated: the resulting function can be referred
to as a C function: in the great majority of cases, C functions
are also L functions. Any function which calls User::AllocLC()
to
allocate a buffer should also use this naming convention.
The function that calls a -C
function must pop (and destroy,
if the -C
function allocated an object) the object from the
stack when its use is complete.