(Palm OS Tools) Language Elements | Palm OS® Protein C/C++ Compiler Language & Library Reference

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 ^TOP^

This section describes the following lexical elements of C and C++:

Character Set ^TOP^

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
a b c d e f g h i j k l m n o p q r s t u v w x y z

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
The decimal digits 0 through 9
0 1 2 3 4 5 6 7 8 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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 or struct), 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 keywords asm, _asm, and __asm. The asm 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.) An asm 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 the asm function should be inserted at each call-site. (The asm 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 inline asm statement and relatively small asm 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 by y 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.

Constants ^TOP^

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 ^TOP^

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 of b into a
*= a *= b is equivalent to a = a * b
/= a /= b is equivalent to a = a / b
%= a %= b is equivalent to a = a % b
+= index += 2 is equivalent to index = index + 2
-= index -= 3 is equivalent to index = index - 3
<<= n1 <<= n2 is equivalent to n1 = n1 << n2
>>= n1 >>= n2 is equivalent to n1 = n1 >> n2
&= mask &= 2 is equivalent to mask = mask & 2
^= t1 ^= t2 is equivalent to t1 = t1 ^ t2
|= flag |= ON is equivalent to flag = 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 ^TOP^

Separators can include:

( ) parenthesis
[ ] brackets
{ } braces
, comma
; semi-colon
: colon

Preprocessor Directives ^TOP^

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 ^TOP^

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 ^TOP^

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, where n 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 that name, otherwise pops a single value off the stack. If n 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. If n 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.

2 Language Elements