This chapter describes the Palm OS® compiler's C/C++ language differences, as compared to the ANSI standard. The following language elements of C and C++ are described:
Lexical Elements
This section describes the following lexical elements of C and C++:
Character Set
The Palm OS compiler only specifically supports the ASCII character set for input, although the compiler is intended to be 8-bit neutral. The following lists the basic character set that is available at both compile and run time:
- The uppercase and lowercase letters of the English alphabet
- The decimal digits 0 through 9
- The following graphic characters:
- The caret (
^
) character - The split vertical bar (
|
) character - The space character (' ')
- The control characters representing newline, horizontal tab, vertical tab, and form feed, and end of string (terminating null character).
The number sign (#
) character is used for preprocessing only, and the underscore (_
) character is treated as a normal letter.
Comments
The following comments within C/C++ source code are permitted:
- The
/*
(slash, asterisk) characters, followed by any sequence of characters (including newlines), followed by the*/
(asterisk, slash) characters. - The
//
(two slashes) characters followed by any sequence of characters. A newline not immediately preceded by a line-continuation (\
) character terminates this form of comment. This kind of comment is commonly called a single-line comment.
You can put comments anywhere the language allows white space.
The Palm OS compiler also recognizes the following comments within C/C++ source code, used to affect warning messages generated by the compiler:
-
/*ARGSUSED*/
- When placed before a function definition, this comment suppresses compiler warnings about unused parameters in functions.
-
/*NOTREACHED*/
- When inserted at the beginning of a block of code that appears unreachable by the compiler, this comment suppresses the "unreachable code" warning.
Tokens
Source code is treated during preprocessing and compilation as a sequence of tokens. There are five different types of tokens:
Adjacent identifiers, keywords, and literals must be separated with white space. Other tokens should be separated by white space to make the source code more readable. White space includes blanks, horizontal and vertical tabs, newlines, form feeds, and comments.
Identifiers
An identifier consists of an arbitrary number of letters or digits; however, it must not begin with a digit and it must not have the same spelling as a keyword. Identifiers provide names for the following language elements:
- Functions
- Data objects
- Labels
- Enumerated tags
- Variables
- Macros
- Typedefs
- Structure members
- Union members
Keywords
Keywords are identifiers reserved by the language for special use.
- Refer to the C language standard: ANSI/ISO/IEC 9899:1999 specification for a list of the keywords common to the C language.
- Refer to the C++ language standard: ANSI/ISO/IEC 14882:1998 specification for a list of the keywords common to the C++ language.
Extension keywords
The Palm OS compiler also recognizes the following keywords:
-
__align(
n
) -
n
may be 1, 2, 4, 8, or 16. When applied to a global object, guarantees that the object is emitted with at least the specified alignment. When applied to a type declaration (e.g.,typedef
orstruct
), applies to all global objects that are instances of that type. Note: This keyword does not alter the packing within a structure or modify what code is used to access through a pointer. Use__pack
or#pragma pack
for the former, and__packed
for the latter. -
asm
- The
asm
keyword is used to pass information through the compiler to the assembler. The Palm OS compiler permits assembler code to be inlined using the keywordsasm
,_asm
, and__asm
. Theasm
keyword has its normal C99 and C++ behavior; in addition, when used as the first keyword in a function definition, the contents of the function are all taken as assembly instructions and the function is emitted "naked," without a prologue or epilogue that pushes or pops registers from the stack. (A 'bx lr' return instruction is placed after your code, in case you do not explicitly return.) Anasm
function is called in the same way as any function; its arguments are in registers r0-r3 and on the stack, as is defined by ATPCS: - The "inline" qualifier can be used with
asm
functions to indicate that the body of theasm
function should be inserted at each call-site. (Theasm
function should not explicitly return or use labels. As in the above example, it should fall off the end to return execution to the caller.) - Supported use of
asm
routines is limited to "nop," as an inlineasm
statement and relatively smallasm
functions that do not use labels. -
__asm
- Followed by curly brackets, indicates a multi-line inline assembly block. Otherwise, indicates inline assembly until the end of the current line.
-
__inline
- An exact alias of the normal
inline
keyword, in C99 or C++, depending on which is being compiled. -
__int64
- Alias for
long long
type. -
__pack(
n
) -
n
may be 0, 1, 2, 4, 8, or 16. Applied to a structure definition, this keyword changes the packing in effect for that structure. This keyword overrides any#pragma pack()
setting for this structure. If zero (0) is selected, natural alignment is used (not the current#pragma pack
value). -
__packed
- Hybrid modifier: when applied to a structure definition, forces the packing to be 1-byte aligned. When applied to a pointer, forces all accesses through that pointer to assume an unaligned pointer. (This is also the case when a pointer to a
__packed
structure is used.) -
__pure
- In function prototypes modifying the function name, this keyword indicates that the function has no side-effects and relies only on its input parameters. Currently, the Palm OS compiler ignores this keyword.
-
__ror32(
x
,y
) - A built-in operator that returns the 32-bit unsigned integer
x
rotated right byy
bits. -
__value_in_regs
- When this keyword is applied to a function prototype or declaration, states that the return value of the function, if it is a small structure (16 bytes or less), is passed in processor registers r0-r3. (Normally structure return values are passed by pointer in a hidden first argument.)
- This calling convention keyword is potentially useful to interoperate with special routines.
- Example:
-
__weak
- In declarations of external objects (functions or data), this modifier indicates that the object is not required and the linker should fix up references if the object is not available during linkage.
asm int func (int a, int b) {
add r0, r0, r1 // return a+b
}
struct div_result {int div, rem;};
struct div_result __value_in_regs do_div (int x, int y);
Constants
The value of any constant must be in the range of representable values for its type. The C language contains the following types of constants (also called literals):
- Integer (decimal, octal, or hexadecimal notation)
- Floating-point (
double
,float
,long double
, or hexadecimal notation) - Character (one or more characters in apostrophes)
- String (sequence of characters enclosed in double quotes)
- Enumeration
Operators
Operators can be classified as:
Postfix
Postfix operators are operators that are suffixed to an expression, such as, operand++
.
Prefix
Prefix operators are operators that are prefixed to an expression, such as, ++operand
or !operand
.
Normal
There are several normal operators that return the result defined for each:
-
+
addition -
-
subtraction -
*
multiplication -
/
division -
%
modulo -
&
AND -
|
OR -
^
XOR -
>>
shift right -
<<
shift left
Boolean
The Boolean operators return either 1 (true) or 0 (false).
-
&&
logical AND -
||
logical OR -
<
less than -
>
greater than -
<=
less than equal -
>=
greater than equal -
==
equal -
!=
not equal
Assignment
An assignment operator stores the value of the right expression into the left expression:
-
=
a = b
assigns the value ofb
intoa
-
*=
a *= b
is equivalent toa = a * b
-
/=
a /= b
is equivalent toa = a / b
-
%=
a %= b
is equivalent toa = a % b
-
+=
index += 2
is equivalent toindex = index + 2
-
-=
index -= 3
is equivalent toindex = index - 3
-
<<=
n1 <<= n2
is equivalent ton1 = n1 << n2
-
>>=
n1 >>= n2
is equivalent ton1 = n1 >> n2
-
&=
mask &= 2
is equivalent tomask = mask & 2
-
^=
t1 ^= t2
is equivalent tot1 = t1 ^ t2
-
|=
flag |= ON
is equivalent toflag = flag | ON
C++ Compatibility
There are three new compound operators in C++:
-
.*
Binds its second operand, which shall be of type "pointer to member of T" (where T is a completely defined class type) to its first operand, which shall be of class T. -
->*
Binds its second operand, which shall be of type "pointer to member of T" (where T is a completely defined class type) to its first operand, which shall be of type "pointer to T" or "pointer to a class of which T is an unambiguous and accessible base class." -
::
Allows a type, an object, a function, an enumerator, or a namespace declared in the global namespace to be referred to even if its identifier has been hidden.
Separators
Preprocessor Directives
Preprocessor directives instruct the preprocessor to act on the text of the program. Preprocessor directives begin with the # token followed by a preprocessor keyword. The # token must appear as the first character that is not white space on a line. The # is not part of the directive name and can be separated from the name with white space. Except for some #pragma
directives, preprocessor directives can appear anywhere in a program.
Predefined Constants
This section describes the predefined constants provided by the Palm OS Protein C/C++ Compiler.
-
__APGE__
- Defined as 1.
-
__APOGEE__
- Defined as 1.
-
__arm
- Defined as 1.
-
_BOOL
- Defined in C++ mode when
bool
is a keyword. -
__cplusplus
- Defined in C++ mode.
-
c_plusplus
- Defined in default C++ mode, but not in
strict
mode. -
__DATE__
- Defined in all modes to the date of the compilation in the form "Mmm dd yyyy."
-
__EDG__
- Always defined.
-
__EDG_VERSION__
- Defined to an integral value that represents the version number of the front end. For example, version 2.30 is represented as 230.
-
__embedded_cplusplus
- Defined as 1 in embedded C++ mode.
-
__EXCEPTIONS
- Defined in C++ mode when exception handling is enabled.
-
_PACC_VER
-
0xMmmrrbbb
, where (M=Major, m=minor, r=rev, b=build). For example,0x1000000D
, for 1.0.0.13. -
__PALMSOURCE__
- Defined as 1.
-
__PSI__
- Defined as 1.
-
__RTTI
- Defined in C++ mode when RTTI is enabled.
-
__SIGNED_CHARS__
- Defined when plain character is signed. (By default, the character type is unsigned.)
-
__STDC__
- Defined in ANSI C mode and in C++ mode. In C++ mode, the value may be redefined.
-
__STDC_HOSTED__
- Defined in C99 mode with the value zero (0).
-
__STDC_VERSION__
- Defined in ANSI C mode with the value
199901L
. -
__TIME__
- Defined in all modes to the time of the compilation in the form "hh:mm:ss."
-
_WCHAR_T
- Defined in C++ mode when
wchar_t
is a keyword.
#pragma
A pragma directive is an implementation-defined instruction to the compiler. This section describes the #pragma
commands that the Palm OS compiler recognizes.
-
#pragma once
- Indicates that a source file (usually a header) need not be included again. (Thus an
#include
of the same header has no effect.) If normal header guards are used, the compiler optimizes them into a#pragma once
: -
#pragma once // unnecessary
-
#ifndef MY_HEADER_GUARD
-
#define MY_HEADER_GUARD
-
// header contents ...
-
#endif /* MY_HEADER_GUARD */
-
#pragma pack(
n
) - Sets current structure packing to
n
, wheren
is 1, 2, 4, 8, or 16. -
#pragma pack()
- Resets current structure packing to natural alignment.
-
#pragma pack (pop [,
name
] [,n
]) - If
name
is supplied, pops back to the position on the stack with thatname
, otherwise pops a single value off the stack. Ifn
is supplied, sets the alignment to that value after popping. -
#pragma pack (push [,
name
] [,n
]) - Pushes the current structure packing onto a stack. If
name
(an identifier) is supplied, names the prior position on the stack. Ifn
is supplied, sets the packing to that value, after pushing the original value. -
#pragma weak
name
- Same as declaring the global object with the external name of
name
with the__WEAK
attribute.