|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-27AAD3D5-AEC0-5A33-B14A-2E8B8D21CDAA" xml:lang="en"><title>How |
|
13 to use the trailing-C naming convention</title><shortdesc>This document describes how functions named with a trailing C are |
|
14 handled on the stack.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <p>The case of allocating an object and pushing it to the cleanup stack is |
|
16 sufficiently common that allocation functions are often coded to do both in |
|
17 a single operation. For example, there is a <codeph>User::AllocLC()</codeph> whose |
|
18 semantics are to call <codeph>User::Alloc()</codeph> to allocate the memory, |
|
19 leave if the allocation failed, and push to the cleanup stack if it succeeded.</p> |
|
20 <p>The trailing <codeph>C</codeph> indicates that the item is pushed to the |
|
21 cleanup stack if successfully allocated: the resulting function can be referred |
|
22 to as a <keyword>C function</keyword>: in the great majority of cases, C functions |
|
23 are also <keyword>L functions</keyword>. Any function which calls <codeph>User::AllocLC()</codeph> to |
|
24 allocate a buffer should also use this naming convention. </p> |
|
25 <p>The function that calls a -<codeph>C</codeph> function must pop (and destroy, |
|
26 if the -<codeph>C</codeph> function allocated an object) the object from the |
|
27 stack when its use is complete.</p> |
|
28 </conbody></concept> |