7. #pragmas

The compiler understands some pragmas that may be used to change code generation and other stuff. Some of these pragmas understand a special form: If the first parameter is push, the old value is saved onto a stack before changing it. The value may later be restored by using the pop parameter with the #pragma.

7.1 #pragma bssseg ([push,]<name>)

This pragma changes the name used for the BSS segment (the BSS segment is used to store uninitialized data). The argument is a string enclosed in double quotes.

Note: The default linker configuration file does only map the standard segments. If you use other segments, you have to create a new linker configuration file.

Beware: The startup code will zero only the default BSS segment. If you use another BSS segment, you have to do that yourself, otherwise uninitialized variables do not have the value zero.

The #pragma understands the push and pop parameters as explained above.

Example:

        #pragma bssseg ("MyBSS")
  

7.2 #pragma charmap (<index>, <code>)

Each literal string and each literal character in the source is translated by use of a translation table. This translation table is preset when the compiler is started depending on the target system, for example to map ISO-8859-1 characters into PETSCII if the target is a commodore machine.

This pragma allows to change entries in the translation table, so the translation for individual characters, or even the complete table may be adjusted.

Both arguments are assumed to be unsigned characters with a valid range of 1-255.

Beware of two pitfalls:

• The character index is actually the code of the character in the C source, so character mappings do always depend on the source character set. This means that #pragma charmap is not portable -- it depends on the build environment.
• While it is possible to use character literals as indices, the result may be somewhat unexpected, since character literals are itself translated. For this reason I would suggest to avoid character literals and use numeric character codes instead.

Example:

        /* Use a space wherever an 'a' occurs in ISO-8859-1 source */
        #pragma charmap (0x61, 0x20);
  

7.3 #pragma checkstack ([push,]on|off)

Tells the compiler to insert calls to a stack checking subroutine to detect stack overflows. The stack checking code will lead to somewhat larger and slower programs, so you may want to use this pragma when debugging your program and switch it off for the release version. If a stack overflow is detected, the program is aborted.

If the argument is "off", stack checks are disabled (the default), otherwise they're enabled.

The #pragma understands the push and pop parameters as explained above.

7.4 #pragma codeseg ([push,]<name>)

This pragma changes the name used for the CODE segment (the CODE segment is used to store executable code). The argument is a string enclosed in double quotes.

Note: The default linker configuration file does only map the standard segments. If you use other segments, you have to create a new linker configuration file.

The #pragma understands the push and pop parameters as explained above.

Example:

        #pragma codeseg ("MyCODE")
  

7.5 #pragma codesize ([push,]<int>)

This pragma allows finer control about speed vs. size decisions in the code generation and optimization phase. It gives the allowed size increase factor (in percent). The default is can be changed by use of the --codesize compiler option.

The #pragma understands the push and pop parameters as explained above.

7.6 #pragma dataseg ([push,]<name>)

This pragma changes the name used for the DATA segment (the DATA segment is used to store initialized data). The argument is a string enclosed in double quotes.

Note: The default linker configuration file does only map the standard segments. If you use other segments, you have to create a new linker configuration file.

The #pragma understands the push and pop parameters as explained above.

Example:

        #pragma dataseg ("MyDATA")
  

7.7 #pragma optimize ([push,]on|off)

Switch optimization on or off. If the argument is "off", optimization is disabled, otherwise it is enabled. Please note that this pragma only effects whole functions. The setting in effect when the function is encountered will determine if the generated code is optimized or not.

Optimization and code generation is also controlled by the codesize pragma.

The default is "off", but may be changed with the -O compiler option.

The #pragma understands the push and pop parameters as explained above.

7.8 #pragma rodataseg ([push,]<name>)

This pragma changes the name used for the RODATA segment (the RODATA segment is used to store readonly data). The argument is a string enclosed in double quotes.

Note: The default linker configuration file does only map the standard segments. If you use other segments, you have to create a new linker configuration file.

The #pragma understands the push and pop parameters as explained above.

Example:

        #pragma rodataseg ("MyRODATA")
  

7.9 #pragma regvaraddr ([push,]on|off)

The compiler does not allow to take the address of register variables. The regvaraddr pragma changes this. Taking the address of a register variable is allowed after using this pragma with "on" as argument. Using "off" as an argument switches back to the default behaviour.

Beware: The C standard does not allow taking the address of a variable declared as register. So your programs become non-portable if you use this pragma. In addition, your program may not work. This is usually the case if a subroutine is called with the address of a register variable, and this subroutine (or a subroutine called from there) uses register variables. So be careful with this #pragma.

The #pragma understands the push and pop parameters as explained above.

Example:

        #pragma regvaraddr(on)  /* Allow taking the address
                                 * of register variables
                                 */
  

7.10 #pragma regvars ([push,]on|off)

Enables or disables use of register variables. If register variables are disabled (the default), the register keyword is ignored. Register variables are explained in more detail in a separate chapter.

The #pragma understands the push and pop parameters as explained above.

7.11 #pragma signedchars ([push,]on|off)

Changes the signedness of the default character type. If the argument is "on", default characters are signed, otherwise characters are unsigned. The compiler default is to make characters unsigned since this creates a lot better code. This default may be overridden by the --signed-chars command line option.

The #pragma understands the push and pop parameters as explained above.

7.12 #pragma staticlocals ([push,]on|off)

Use variables in the bss segment instead of variables on the stack. This pragma changes the default set by the compiler option -Cl. If the argument is "on", local variables are allocated in the BSS segment, leading to shorter and in most cases faster, but non-reentrant code.

The #pragma understands the push and pop parameters as explained above.

7.13 #pragma warn ([push,]on|off)

Switch compiler warnings on or off. If the argument is "off", warnings are disabled, otherwise they're enabled. The default is "on", but may be changed with the -W compiler option.

The #pragma understands the push and pop parameters as explained above.

7.14 #pragma zpsym (<name>)

Tell the compiler that the -- previously as external declared -- symbol with the given name is a zero page symbol (usually from an assembler file). The compiler will create a matching import declaration for the assembler.

Example:

        extern int foo;
        #pragma zpsym ("foo");  /* foo is in the zeropage */