C/C++ extended keywords

Watcom C/C++ supports the use of some special keywords to describe system-dependent attributes of functions and other object names. These attributes are inspired by the Intel processor architecture and the plethora of function-calling conventions in use by compilers for this architecture. In keeping with the ANSI C and C++ language standards, Watcom C/C++ uses a double underscore (__), or a single underscore followed by an uppercase letter (for example, _S) as a prefix for these keywords. To support compatibility with other C/C++ compilers, alternate forms of these keywords are also supported through predefined macros.

__near

Watcom C/C++ supports the __near keyword to describe functions and other object names that are in near memory, and pointers to near objects.

Watcom C/C++ predefines the macros near and _near to be equivalent to the __near keyword.

__far

Watcom C/C++ supports the __far keyword to describe functions and other object names that are in far memory, and pointers to far objects.

Watcom C/C++ predefines the macros far, _far and SOMDLINK (16-bit only) to be equivalent to the __far keyword.

__huge

Watcom C/C++ supports the __huge keyword to describe functions and other object names that are in huge memory, and pointers to huge objects. The 32-bit compilers treat these as equivalent to far objects.

Watcom C/C++ predefines the macros huge and _huge to be equivalent to the __huge keyword.

__based

Watcom C/C++ supports the __based keyword to describe pointers to objects that appear in other segments, or the objects themselves. See ``Based Pointers'' for an explanation of the __based keyword.

Watcom C/C++ predefines the macro _based to be equivalent to the __based keyword.

__segment

Watcom C/C++ supports the __segment keyword, which is used when describing objects of type segment. See ``Based Pointers'' for an explanation of the __segment keyword.

Watcom C/C++ predefines the macro _segment to be equivalent to the __segment keyword.

__segname

Watcom C/C++ supports the __segname keyword, which is used when describing segname constant based pointers or objects. See ``Based Pointers'' for an explanation of the __segname keyword.

Watcom C/C++ predefines the macro _segname to be equivalent to the __segname keyword.

__self

Watcom C/C++ supports the __self keyword, which is used when describing self-based pointers. See ``Based Pointers'' for an explanation of the __self keyword.

Watcom C/C++ predefines the macro _self to be equivalent to the __self keyword.

_Packed

Watcom C/C++ supports the _Packed keyword, which is used when describing a structure. If specified before the struct keyword, the compiler forces the structure to be packed (no alignment, no gaps), regardless of the setting of the command-line option or the #pragma controlling the alignment of members.

__cdecl

Watcom C/C++ supports the __cdecl keyword to describe C functions that are called using a special convention. This keyword is described in the chapters

• 16-bit Pragmas, in the 16-bit Topics supplement
• 32-bit Pragmas

Watcom C/C++ predefines the macros cdecl, _cdecl, _Cdecl and SOMLINK (16-bit only) to be equivalent to the __cdecl keyword.

__pascal

Watcom C/C++ supports the __pascal keyword to describe Pascal functions that are called using a special convention described by a pragma in the stddef.h header file. For more information on this pragma, see the chapters:

• 16-bit Pragmas, in the 16-bit Topics supplement
• 32-bit Pragmas

Watcom C/C++ predefines the macros pascal, _pascal and _Pascal to be equivalent to the __pascal keyword.

__fortran

Watcom C/C++ supports the __fortran keyword to describe functions that are called from FORTRAN. It converts the name to uppercase letters and suppresses the underscore (_) that's appended to the function name for certain calling conventions.

Watcom C/C++ predefines the macros fortran and _fortran to be equivalent to the __fortran keyword.

__interrupt

Watcom C/C++ supports the __interrupt keyword to describe a function that's an interrupt handler.

For example:

#include <i86.h>

void __interrupt int10( union INTPACK r )
{
    .
    .
    .
}
       

The code generator emits instructions to save all registers. The registers are saved on the stack in a specific order so that they may be referenced using the INTPACK union as shown in the DOS example above.

The code generator emits instructions to establish addressability to the program's data segment since the DS segment register contents are unpredictable. The function returns using an IRET (16-bit) or IRETD (32-bit) (interrupt return) instruction.

Watcom C/C++ predefines the macros interrupt and _interrupt to be equivalent to the __interrupt keyword.

Don't use the __interrupt keyword for QNX interrupt handlers.

__export

Watcom C/C++ supports the __export keyword to describe functions and other object names that are to be exported from a Microsoft Windows or OS/2 Dynamic Link Library (DLL). See also the description of the zu option.

For example:

void __export _Setcolor( int color )
{
    .
    .
    .
}
      

Watcom C/C++ predefines the macro _export to be equivalent to the __export keyword.

__loadds

Watcom C/C++ supports the __loadds keyword to describe functions that require specific loading of the DS register to establish addressability to the function's data segment. This keyword is useful in describing a function that is placed in a Microsoft Windows or OS/2 1.x Dynamic Link Library (DLL). See also the description of the nd and zu options.

For example:

void __export __loadds _Setcolor( int color )
{
    .
    .
    .
}
      

If the function in an OS/2 1.x Dynamic Link Library requires access to private data, the data segment register must be loaded with an appropriate value since it will contain the DS value of the calling application on entry to the function.

Watcom C/C++ predefines the macro _loadds to be equivalent to the __loadds keyword.

__saveregs

Watcom C/C++ recognizes the __saveregs keyword, which is an attribute used by C/C++ compilers to describe a function that must save and restore all registers.

Watcom C/C++ predefines the macro _saveregs to be equivalent to the __saveregs keyword.

__stdcall

(32-bit only) The __stdcall keyword may be used with function definitions, and indicates that the 32-bit Win32 calling convention is to be used. Note the following: For more information, see ``Predefined __stdcall alias'' in the 32-bit Pragmas chapter.

__syscall

(32-bit only) The __syscall keyword may be used with function definitions, and indicates that the calling convention used is compatible with functions provided by 32-bit OS/2. For more information, see ``Predefined __syscall alias'' in the 32-bit Pragmas chapter.

Watcom C/C++ predefines the macros _syscall, _System and SOMLINK (32-bit only) to be equivalent to the __syscall keyword.

__far16

(32-bit only) Watcom C/C++ recognizes the __far16 keyword, which can be used to define far 16-bit (far16) pointers (16-bit selector with 16-bit offset) or far 16-bit function prototypes.

This keyword can be used under 32-bit OS/2 to call 16-bit functions from your 32-bit flat model program. Integer arguments are automatically converted to 16-bit integers, and 32-bit pointers are converted to far16 pointers before calling a special thunking layer to transfer control to the 16-bit function.

Watcom C/C++ predefines the macros _far16 and _Far16 to be equivalent to the __far16 keyword. This keyword is compatible with Microsoft C.

In the OS/2 operating system (version 2.0 or higher), the first 512 megabytes of the 4 gigabyte segment referenced by the DS register is divided into 8192 areas of 64K bytes each. A far16 pointer consists of a 16-bit selector referring to one of the 64K byte areas, and a 16-bit offset into that area.

A pointer declared as:

[type] __far16 *name;

defines an object that is a far16 pointer. If such a pointer is accessed in the 32-bit environment, the compiler generates the necessary code to convert between the far16 pointer and a flat 32-bit pointer.

For example, the declaration:

    char __far16 *bufptr;
      

declares the object bufptr to be a far16 pointer to char.

A function declared as:

    [type] __far16 func( [arg_list] );
      

declares a 16-bit function. Any calls to such a function from the 32-bit environment causes the compiler to convert any 32-bit pointer arguments to far16 pointers, and any int arguments from 32 bits to 16 bits. (In the 16-bit environment, an object of type int is only 16 bits.) Any value returned from the function is converted in an appropriate manner.

For example, the declaration

    char * __far16 Scan( char *buffer, int len,
                         short err );
      

declares the 16-bit function Scan(). When this function is called from the 32-bit environment, the buffer argument is converted from a flat 32-bit pointer to a far16 pointer (which, in the 16-bit environment, would be declared as char __far *. The len argument is converted from a 32-bit integer to a 16-bit integer. The err argument is passed unchanged. On returning, the far16 pointer (far pointer in the 16-bit environment) is converted to a 32-bit pointer that describes the equivalent location in the 32-bit address space.

_Seg16

(32-bit only) Watcom C/C++ recognizes the _Seg16 keyword, which has a similar, but not identical, function to the __far16 keyword described above. This keyword is compatible with IBM C Set/2.

In the OS/2 operating system (version 2.0 or higher), the first 512 megabytes of the 4 gigabyte segment referenced by the DS register is divided into 8192 areas of 64K bytes each. A far16 pointer consists of a 16-bit selector referring to one of the 64K byte areas, and a 16-bit offset into that area.

_Seg16 isn't interchangeable with __far16.

A pointer declared as:

[type] * _Seg16 name;

defines an object that's a far16 pointer. Note that the _Seg16 appears on the right side of the *, which is opposite to the __far16 keyword described above.

For example,

    char * _Seg16 bufptr;
      

declares the object bufptr to be a far16 pointer to char (the same as above).

The _Seg16 keyword may not be used to describe a 16-bit function. A #pragma directive must be used instead. A function declared as:

    [type] * _Seg16 func( [parm_list] );
      

declares a 32-bit function that returns a far16 pointer.

For example, the declaration:

    char * _Seg16 Scan( char * buffer, int len, 
                        short err );
      

declares the 32-bit function Scan(). No conversion of the argument list takes place. The return value is a far16 pointer.

__pragma

Watcom C++ supports the __pragma keyword to support in-lining of member functions. The __pragma keyword must be followed by parentheses containing a string that names an auxiliary pragma. Here's a simplified example showing usage and syntax:

#pragma aux fast_mul = \
    "imul eax,edx" \
    parm caller [eax] [edx] \
    value struct;

struct fixed {
    unsigned v;
};

fixed __pragma( "fast_mul") 
    operator *( fixed, fixed );

fixed two = { 2 };
fixed three = { 3 };

fixed foo()
{
    return two * three;
}
      

See the following chapters for more information on pragmas:

• 16-bit Pragmas, in the 16-bit Topics supplement
• 32-bit Pragmas, in this manual

    [type] __based( __segname( "segment" ) ) object_name;

    [type] __based( __segname( "segment" ) ) *object-name;

    int __based( __segname( "_CODE" ) )  ival = 3;
    int __based( __segname( "_CODE" ) ) *iptr;

    char __based( __segname( "GOODTHINGS" ) ) thing;

    [type] __based( segment ) *name;

    __segment           seg;
    char __based( seg ) *cptr;

extern void main()
{
    __segment          screen;
    char __based( void ) *scrptr;

    screen = 0xB800;
    scrptr = 0;
    printf( "Top left character is '%c'.\n",
            *(screen:>scrptr) );
}

    segment :> offset

struct a {
    struct a __based( __self ) *next;
    int             number;
};


extern void PrintLastTwo( struct a far *list )
{
  __segment           seg;
  struct a __based( seg ) *aptr;

  seg  = FP_SEG( list );
  aptr = FP_OFF( list );
  for( ; aptr != _NULLOFF; aptr = aptr->next ) {
    if( aptr->next == _NULLOFF ) {
      printf( "Last item is %d\n",
          aptr->number );
    } else if( aptr->next->next == _NULLOFF ) {
      printf( "Second last item is %d\n",
          aptr->number );
    }
  }
}

    struct a *next;

    Not enough memory to optimize procedure 'xxxx'

export "WCGMEMORY=?"

export "WCGMEMORY=128"