How to use the trailing-C naming convention

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.