Index of Topics

- " -

The "-fh[q]" (Precompiled Header) Option

- 0 -

0

- 1 -

1
16-bit:  "check_stack" Option
16-bit:  "inline" Option (C only)
16-bit:  "reuse_duplicate_strings" Option (C only)
16-bit:  "unreferenced" Option
16-bit:  A Function that Never Returns
16-bit:  Alias Names
16-bit:  Alternate Names for Symbols
16-bit:  An Example
16-bit:  Assembly Language Considerations
16-bit:  Auxiliary Pragmas
16-bit:  Auxiliary Pragmas and the 80x87
16-bit:  Calling Conventions for 80x87-based Applications
16-bit:  Calling Conventions for Non-80x87 Applications
16-bit:  Code Models
16-bit:  Creating a Tiny Memory Model Application
16-bit:  Data Models
16-bit:  Data Representation
16-bit:  Defining Exported Symbols in Dynamic Link Libraries
16-bit:  Defining Windows Callback Functions
16-bit:  Describing Argument Information
16-bit:  Describing Calling Information
16-bit:  Describing Function Return Information
16-bit:  Describing How Functions Use Memory
16-bit:  Describing the Registers Modified by a Function
16-bit:  Effect of Function Prototypes on Arguments
16-bit:  Forcing a Stack Frame
16-bit:  Forcing Arguments into Specific Registers
16-bit:  Functions with Variable Number of Arguments
16-bit:  Interfacing to Assembly Language Functions
16-bit:  Linking Applications for the Various Memory Models
16-bit:  Loading Data Segment Register
16-bit:  Memory Layout
16-bit:  Memory Models
16-bit:  Mixed Memory Model
16-bit:  Passing Arguments in Registers
16-bit:  Passing Arguments in Reverse Order
16-bit:  Passing Arguments to In-Line Functions
16-bit:  Passing Arguments Using Register-Based Calling Conventions
16-bit:  Passing Values in 80x87-based Applications
16-bit:  Pragmas
16-bit:  Predefined "__cdecl" Alias
16-bit:  Predefined "__pascal" Alias
16-bit:  Predefined "__watcall" Alias
16-bit:  Predefined Aliases
16-bit:  Preserving 80x87 Floating-Point Registers Across Calls
16-bit:  Removing Arguments from the Stack
16-bit:  Returning Floating-Point Data
16-bit:  Returning Function Values in Registers
16-bit:  Returning Structures
16-bit:  Returning Values from Functions
16-bit:  Returning Values in 80x87-based Applications
16-bit:  Setting Priority of Static Data Initialization (C++ Only)
16-bit:  Size of Enumerated Types
16-bit:  Sizes of Predefined Types
16-bit:  Specifying Symbol Attributes
16-bit:  Summary of Memory Models
16-bit:  The ALIAS Pragma (C Only)
16-bit:  The ALLOC_TEXT Pragma (C Only)
16-bit:  The CODE_SEG Pragma
16-bit:  The COMMENT Pragma
16-bit:  The DATA_SEG Pragma
16-bit:  The DISABLE_MESSAGE Pragma
16-bit:  The DUMP_OBJECT_MODEL Pragma (C++ Only)
16-bit:  The ENABLE_MESSAGE Pragma
16-bit:  The ENUM Pragma
16-bit:  The ERROR Pragma (C++ only)
16-bit:  The EXTREF Pragma
16-bit:  The FUNCTION Pragma
16-bit:  The INCLUDE_ALIAS Pragma
16-bit:  The INLINE_DEPTH Pragma (C++ Only)
16-bit:  The INLINE_RECURSION Pragma (C++ Only)
16-bit:  The INTRINSIC Pragma
16-bit:  The LIBRARY Pragma
16-bit:  The MESSAGE Pragma
16-bit:  The ONCE Pragma
16-bit:  The PACK Pragma
16-bit:  The READ_ONLY_FILE Pragma
16-bit:  The TEMPLATE_DEPTH Pragma (C++ Only)
16-bit:  The WARNING Pragma
16-bit:  Tiny Memory Model
16-bit:  Type "char"
16-bit:  Type "double"
16-bit:  Type "float"
16-bit:  Type "int"
16-bit:  Type "long int"
16-bit:  Type "short int"
16-bit:  Using Pragmas to Specify Options
16-bit:  Using the 80x87 to Pass Arguments
16-bit:  Using the 80x87 to Return Function Values

- 2 -

2

- 3 -

3
32-bit:  "check_stack" Option
32-bit:  "inline" Option (C only)
32-bit:  "reuse_duplicate_strings" Option (C only)
32-bit:  "unreferenced" Option
32-bit:  A Function that Never Returns
32-bit:  Alias Names
32-bit:  Alternate Names for Symbols
32-bit:  An Example
32-bit:  Assembly Language Considerations
32-bit:  Auxiliary Pragmas
32-bit:  Auxiliary Pragmas and the 80x87
32-bit:  Calling Conventions for 80x87-based Applications
32-bit:  Calling Conventions for Non-80x87 Applications
32-bit:  Code Models
32-bit:  Data Models
32-bit:  Data Representation
32-bit:  Defining Exported Symbols in Dynamic Link Libraries
32-bit:  Describing Argument Information
32-bit:  Describing Calling Information
32-bit:  Describing Function Return Information
32-bit:  Describing How Functions Use Memory
32-bit:  Describing the Registers Modified by a Function
32-bit:  Effect of Function Prototypes on Arguments
32-bit:  Flat Memory Model
32-bit:  Forcing a Stack Frame
32-bit:  Forcing Arguments into Specific Registers
32-bit:  Functions with Variable Number of Arguments
32-bit:  Interfacing to Assembly Language Functions
32-bit:  Linking Applications for the Various Memory Models
32-bit:  Loading Data Segment Register
32-bit:  Memory Layout
32-bit:  Memory Models
32-bit:  Mixed Memory Model
32-bit:  Passing Arguments in Registers
32-bit:  Passing Arguments in Reverse Order
32-bit:  Passing Arguments to In-Line Functions
32-bit:  Passing Arguments Using Register-Based Calling Conventions
32-bit:  Passing Values in 80x87-based Applications
32-bit:  Pragmas
32-bit:  Predefined "__cdecl" Alias
32-bit:  Predefined "__pascal" Alias
32-bit:  Predefined "__stdcall" Alias
32-bit:  Predefined "__syscall" Alias
32-bit:  Predefined "__watcall" Alias (register calling convention)
32-bit:  Predefined "__watcall" Alias (stack calling convention)
32-bit:  Predefined Aliases
32-bit:  Preserving 80x87 Floating-Point Registers Across Calls
32-bit:  Removing Arguments from the Stack
32-bit:  Returning Floating-Point Data
32-bit:  Returning Function Values in Registers
32-bit:  Returning Structures
32-bit:  Returning Values from Functions
32-bit:  Returning Values in 80x87-based Applications
32-bit:  Setting Priority of Static Data Initialization (C++ Only)
32-bit:  Size of Enumerated Types
32-bit:  Sizes of Predefined Types
32-bit:  Specifying Symbol Attributes
32-bit:  Summary of Memory Models
32-bit:  The ALIAS Pragma (C Only)
32-bit:  The ALLOC_TEXT Pragma (C Only)
32-bit:  The CODE_SEG Pragma
32-bit:  The COMMENT Pragma
32-bit:  The DATA_SEG Pragma
32-bit:  The DISABLE_MESSAGE Pragma
32-bit:  The DUMP_OBJECT_MODEL Pragma (C++ Only)
32-bit:  The ENABLE_MESSAGE Pragma
32-bit:  The ENUM Pragma
32-bit:  The ERROR Pragma (C++ only)
32-bit:  The EXTREF Pragma
32-bit:  The FUNCTION Pragma
32-bit:  The INCLUDE_ALIAS Pragma
32-bit:  The INLINE_DEPTH Pragma (C++ Only)
32-bit:  The INLINE_RECURSION Pragma (C++ Only)
32-bit:  The INTRINSIC Pragma
32-bit:  The LIBRARY Pragma
32-bit:  The MESSAGE Pragma
32-bit:  The ONCE Pragma
32-bit:  The PACK Pragma
32-bit:  The READ_ONLY_FILE Pragma
32-bit:  The TEMPLATE_DEPTH Pragma (C++ Only)
32-bit:  The WARNING Pragma
32-bit:  Type "char"
32-bit:  Type "double"
32-bit:  Type "float"
32-bit:  Type "int"
32-bit:  Type "long int"
32-bit:  Type "short int"
32-bit:  Using Pragmas to Specify Options
32-bit:  Using Stack-Based Calling Conventions
32-bit:  Using the 80x87 to Pass Arguments
32-bit:  Using the 80x87 to Return Function Values
3{r|s}

- 4 -

4
4{r|s}

- 5 -

5
5{r|s}

- 6 -

6
6{r|s}

- 8 -

80x86 Floating Point
80x86 Run-time Conventions

- _ -

The __declspec Keyword

- A -

aa
About This Manual
ad[=<file_name>]
adbs
add[=<file_name>]
adfs
adhp[=<path_name>]
adt[=<target_name>]

- B -

Based Pointers
bc
bd
Benchmarking Hints
bg
bm
br
bt[=<os>]
bw

- C -

C++ Exception Handling
Choosing the Correct Floating-Point Option
Code Generation
Compatibility with Microsoft Visual C++
Compatibility with Older Versions of the 80x86 Compilers
Compiler Diagnostics
Compiler Options - Full Description
Compiler Options - Indexed
Compiler Options - Summarized Alphabetically
Compiler Options - Summarized By Category
Consistency Rules for Precompiled Headers
Creating and Using Precompiled Headers
Creating ROM-based Applications

- D -

d+
d0
d1
d1+
d2
d2i
d2s
d2t
d3
d3i
d3s
d<name>[=text]
db
Debugging/Profiling
Diagnostics
Double-Byte/Unicode Characters

- E -

e<number>
ecc
ecd
ecf
ecp
ecr
ecs
ecw
ee
ef
ei
em
en
Environment Variables
ep[<number>]
eq
er
errno Values and Their Meanings
et
ew
Exception Filters and Exception Handlers
ez

- F -

fc=<file_name>
fh[q][=<file_name>]
fhd
fhr
fhw
fhwe
fi=<file_name>
fo[=<file_name>]
fo[=<file_name>] (preprocessor)
FORCE
fp2
fp3
fp5
fp6
fpc
fpd
fpi
fpi87
fpr
fr[=<file_name>]
ft
fti
fx
fzh
fzs

- G -

g=<codegroup>

- H -

h{w,d,c}

- I -

i=<directory>
In-line Assembly Directives and Opcodes
In-line Assembly Language
In-line Assembly Language Default Environment
In-line Assembly Language Tutorial
In-line Assembly Language using _asm
INCLUDE

- J -

j

- K -

k

- L -

Labels in In-line Assembly Code
LFN
The LFN Environment Variable
LIB
LIBDOS
LIBOS2
LIBPHAR
LIBWIN

- M -

Math Run-Time Error Messages
mc
mf
mh
Mixing and Matching _try/_finally and _try/_except
ml
mm
Modifying the Startup Code
ms

- N -

nc=<name>
nd=<name>
nm=<name>
NO87
The NO87 Environment Variable
nt=<name>

- O -

oa
ob
oc
od
oe=<num>
of
of+
oh
oi
oi+
ok
ol
ol+
om
on
oo
op
Open Watcom C/C++ #include File Processing
Open Watcom C/C++ 80x87 Math Libraries
Open Watcom C/C++ Alternate Math Libraries
Open Watcom C/C++ C Libraries
Open Watcom C/C++ Class Libraries
Open Watcom C/C++ Command Line Examples
Open Watcom C/C++ Command Line Format
Open Watcom C/C++ Compiler Options
The Open Watcom C/C++ Compilers
Open Watcom C/C++ DLL-based Compilers
Open Watcom C/C++ Extended Keywords
The Open Watcom C/C++ Libraries
Open Watcom C/C++ Library Directory Structure
Open Watcom C/C++ Math Libraries
Open Watcom C/C++ Predefined Macros
Open Watcom C/C++ Preprocessor
The Open Watcom C/C++ Run-time Initialization Routines
Open Watcom C/C++ Run-Time Messages
The Open Watcom Code Generator
Optimizations
or
os
ot
ou
ox
oz

- P -

PATH
pil
Precompiled Headers
Preprocessor
p{e,l,c,w=<num>}

- Q -

q

- R -

r
Refining Exception Handling
Resuming Execution After an Exception
ri
ROMable Functions
Run-Time Error Messages

- S -

s
Segment Constant Based Pointers and Objects
Segment Object Based Pointers
Segments/Modules
Self Based Pointers
sg
Source/Output Control
st
Structured Exception Handling
Summary:  80x86 Floating Point
Summary:  80x86 Run-time Conventions
Summary:  C++ Exception Handling
Summary:  Code Generation
Summary:  Compatibility with Microsoft Visual C++
Summary:  Compatibility with Older Versions of the 80x86 Compilers
Summary:  Debugging/Profiling
Summary:  Diagnostics
Summary:  Double-Byte/Unicode Characters
Summary:  Optimizations
Summary:  Preprocessor
Summary:  Segments/Modules
Summary:  Source/Output Control
Summary:  Target Specific
System-Dependent Functions

- T -

t=<num>
Target Specific
Termination Handlers
Throwing Your Own Exceptions
TMP

- U -

u<name>
Use of Environment Variables

- V -

v
Variables in In-line Assembly Code
vc...
vcap
Void Based Pointers

- W -

w<number>
WATCOM
WCC
WCC386
wcd=<number>
wce=<number>
WCGMEMORY
WCL
WCL386
WD
WDW
we
When to Precompile Header Files
WLANG
wo
WPP
WPP386
wx

- X -

x
xd
xds
xdt
xr
xs
xss
xst
xx

- Z -

za
za99
zam
zastd=<standard>
zat
zc
zdl
zd{f,p}
ze
zev
zf
zfw
zf{f,p}
zg
zg{f,p}
zk0u
zku=<codepage>
zk{0,1,2,l}
zl
zld
zlf
zls
zm
zmf
zpw
zp{1,2,4,8,16}
zq
zri
zro
zs
zt<number>
zu
zv
zw
zW (optimized)
zWs
zz

About This Manual

Chapter 1 -

About This Manual.
This chapter provides an overview of the contents of this guide.

Chapter 2 -

Open Watcom C/C++ Compiler Options.
This chapter provides a summary and reference section for all the C and C++ compiler options.

Chapter 3 -

The Open Watcom C/C++ Compilers.
This chapter describes how to compile an application from the command line.  This chapter also describes compiler environment variables, benchmarking hints, compiler diagnostics, #include file processing, the preprocessor, predefined macros, extended keywords, and the code generator.

Chapter 4 -

Precompiled Headers.
This chapter describes the use of precompiled headers to speed up compilation.

Chapter 5 -

The Open Watcom C/C++ Libraries.
This chapter describes the Open Watcom C/C++ library directory structure, C libraries, class libraries, math libraries, 80x87 math libraries, alternate math libraries, the "NO87" environment variable, and the run-time initialization routines.

Chapter 6 -

16-bit:  Memory Models.
This chapter describes the Open Watcom C/C++ memory models (including code and data models), the tiny memory model, the mixed memory model, linking applications for the various memory models, creating a tiny memory model application, and memory layout in an executable.

Chapter 7 -

16-bit:  Assembly Language Considerations.
This chapter describes issues relating to 16-bit interfacing such as parameter passing conventions.

Chapter 8 -

16-bit:  Pragmas.
This chapter describes the use of pragmas with the 16-bit compilers.

Chapter 9 -

32-bit:  Memory Models.
This chapter describes the Open Watcom C/C++ memory models (including code and data models), the flat memory model, the mixed memory model, linking applications for the various memory models, and memory layout in an executable.

Chapter 10 -

32-bit:  Assembly Language Considerations.
This chapter describes issues relating to 32-bit interfacing such as parameter passing conventions.

Chapter 11 -

32-bit:  Pragmas.
This chapter describes the use of pragmas with the 32-bit compilers.

Chapter 12 -

In-line Assembly Language.
This chapter describes in-line assembly language programming using the auxiliary pragma.

Chapter 13 -

Creating ROM-based Applications.
This chapter discusses some embedded systems issues as they pertain to the C library.

Appendix A.  -

Use of Environment Variables.
This appendix describes all the environment variables used by the compilers and related tools.

Appendix B.  -

Open Watcom C/C++ Run-Time Messages.
This appendix lists all of the C/C++ run-time diagnostic messages with an explanation for each.

Open Watcom C/C++ Compiler Options

WCC

the Open Watcom C compiler for 16-bit Intel platforms.

WPP

the Open Watcom C++ compiler for 16-bit Intel platforms.

WCC386

the Open Watcom C compiler for 32-bit Intel platforms.

WPP386

the Open Watcom C++ compiler for 32-bit Intel platforms.

Compiler Options - Indexed

Compiler Options - Summarized Alphabetically

Option:

Description:

0

(16-bit only) 8088 and 8086 instructions (default for 16-bit) (see 0)

1

(16-bit only) 188 and 186 instructions (see 1)

2

(16-bit only) 286 instructions (see 2)

3

(16-bit only) 386 instructions (see 3)

4

(16-bit only) 486 instructions (see 4)

5

(16-bit only) Pentium instructions (see 5)

6

(16-bit only) Pentium Pro instructions (see 6)

3r

(32-bit only) generate 386 instructions based on 386 instruction timings and use register-based argument passing conventions (see 3{r|s})

3s

(32-bit only) generate 386 instructions based on 386 instruction timings and use stack-based argument passing conventions (see 3{r|s})

4r

(32-bit only) generate 386 instructions based on 486 instruction timings and use register-based argument passing conventions (see 4{r|s})

4s

(32-bit only) generate 386 instructions based on 486 instruction timings and use stack-based argument passing conventions (see 4{r|s})

5r

(32-bit only) generate 386 instructions based on Intel Pentium instruction timings and use register-based argument passing conventions (default for 32-bit) (see 5{r|s})

5s

(32-bit only) generate 386 instructions based on Intel Pentium instruction timings and use stack-based argument passing conventions (see 5{r|s})

6r

(32-bit only) generate 386 instructions based on Intel Pentium Pro instruction timings and use register-based argument passing conventions (see 6{r|s})

6s

(32-bit only) generate 386 instructions based on Intel Pentium Pro instruction timings and use stack-based argument passing conventions (see 6{r|s})

aa

(C only) allow non-constant initializers for local aggregates or unions (see aa)

ad[=<file_name>]

generate make style automatic dependency file (see ad[=<file_name>])

adbs

force path separators generated in auto-dependency files to backslashes (see adbs)

add[=<file_name>]

specify source dependency name generated in make style auto-dependency file (see add[=<file_name>])

adhp[=<file_name>]

specify path to use for headers with no path given (see adhp[=<path_name>])

adfs

force path separators generated in auto-dependency files to forward slashes (see adfs)

adt[=<target_name>]

specify target name generated in make style auto-dependency file (see adt[=<target_name>])

bc

build target is a console application (see bc)

bd

build target is a Dynamic Link Library (DLL) (see bd)

bg

build target is a GUI application (see bg)

bm

build target is a multi-thread environment (see bm)

br

build target uses DLL version of C/C++ run-time libraries (see br)

bt[=<os>]

build target for operating system <os> (see bt[=<os>])

bw

build target uses default windowing support (see bw)

d0

(C++ only) no debugging information (see d0)

d1

line number debugging information (see d1)

d1+

(C only) line number debugging information plus typing information for global symbols and local structs and arrays (see d1+)

d2

full symbolic debugging information (see d2)

d2i

(C++ only) d2 and debug inlines; emit inlines as external out-of-line functions (see d2i)

d2s

(C++ only) d2 and debug inlines; emit inlines as static out-of-line functions (see d2s)

d2t

(C++ only) full symbolic debugging information, without type names (see d2t)

d3

full symbolic debugging with unreferenced type names (see d3)

d3i

(C++ only) d3 plus debug inlines; emit inlines as external out-of-line functions (see d3i)

d3s

(C++ only) d3 plus debug inlines; emit inlines as static out-of-line functions (see d3s)

d<name>[=text]

preprocessor #define name [text] (see d<name>[=text])

d+

allow extended -d macro definitions (see d+)

db

generate browsing information (see db)

e<number>

set error limit number (default is 20) (see e<number>)

ecc

set default calling convention to __cdecl (see ecc)

ecd

set default calling convention to __stdcall (see ecd)

ecf

set default calling convention to __fastcall (see ecf)

ecp

set default calling convention to __pascal (see ecp)

ecr

set default calling convention to __fortran (see ecr)

ecs

set default calling convention to __syscall (see ecs)

ecw

set default calling convention to __watcall (default) (see ecw)

ee

call epilogue hook routine (see ee)

ef

use full path names in error messages (see ef)

ei

force enum base type to use at least an int (see ei)

em

force enum base type to use minimum (see em)

en

emit routine name before prologue (see en)

ep[<number>]

call prologue hook routine with number of stack bytes available (see ep[<number>])

eq

do not display error messages (they are still written to a file) (see eq)

er

(C++ only) do not recover from undefined symbol errors (see er)

et

Pentium profiling (see et)

ew

(C++ only) generate less verbose messages (see ew)

ez

(32-bit only) generate Phar Lap Easy OMF-386 object file (see ez)

fc=<file_name>

(C++ only) specify file of command lines to be batch processed (see fc=<file_name>)

fh[q][=<file_name>]

use precompiled headers (see fh[q][=<file_name>])

fhd

store debug info for pre-compiled header once (DWARF only) (see fhd)

fhr

(C++ only) force compiler to read pre-compiled header (see fhr)

fhw

(C++ only) force compiler to write pre-compiled header (see fhw)

fhwe

(C++ only) don't include pre-compiled header warnings when "we" is used (see fhwe)

fi=<file_name>

force file_name to be included (see fi=<file_name>)

fo=<file_name>

set object or preprocessor output file specification (see fo[=<file_name>] (preprocessor)) (see fo[=<file_name>])

fpc

generate calls to floating-point library (see fpc)

fpi

(16-bit only) generate in-line 80x87 instructions with emulation (default)

(32-bit only) generate in-line 387 instructions with emulation (default) (see fpi)

fpi87

(16-bit only) generate in-line 80x87 instructions

(32-bit only) generate in-line 387 instructions (see fpi87)

fp2

generate in-line 80x87 instructions (see fp2)

fp3

generate in-line 387 instructions (see fp3)

fp5

generate in-line 80x87 instructions optimized for Pentium processor (see fp5)

fp6

generate in-line 80x87 instructions optimized for Pentium Pro processor (see fp6)

fpd

enable generation of Pentium FDIV bug check code (see fpd)

fpr

generate 8087 code compatible with older versions of compiler (see fpr)

fr=<file_name>

set error file specification (see fr[=<file_name>])

ft

try truncated (8.3) header file specification (see ft)

fti

(C only) track include file opens (see fti)

fx

do not try truncated (8.3) header file specification (see fx)

fzh

(C++ only) do not automatically append extensions for include files (see fzh)

fzs

(C++ only) do not automatically append extensions for source files (see fzs)

g=<codegroup>

set code group name (see g=<codegroup>)

h{w,d,c}

set debug output format (Open Watcom, Dwarf, Codeview) (see h{w,d,c})

i=<directory>

add directory to list of include directories (see i=<directory>)

j

change char default from unsigned to signed (see j)

k

(C++ only) continue processing files (ignore errors) (see k)

m{f,s,m,c,l,h}

memory model

mf=flat (see mf),

ms=small (see ms),

mm=medium (see mm),

mc=compact (see mc),

ml=large (see ml),

mh=huge (see mh)

(default is "ms" for 16-bit and Netware, "mf" for 32-bit)

nc=<name>

set name of the code class (see nc=<name>)

nd=<name>

set name of the "data" segment (see nd=<name>)

nm=<name>

set module name different from filename (see nm=<name>)

nt=<name>

set name of the "text" segment (see nt=<name>)

o{a,b,c,d,e,f,f+,h,i,i+,k,l,l+,m,n,o,p,r,s,t,u,x,z}

control optimization (see oa) (see of)

pil

preprocessor ignores #line directives (see pil)

p{e,l,c,w=<num>}

preprocess file only, sending output to standard output

"c" include comments

"e" encrypt identifiers (C++ only)

"l" include #line directives

"w=<num>" wrap output lines at <num> columns (zero means no wrap) (see p{e,l,c,w=<num>})

q

operate quietly (see q)

r

save/restore segment registers (see r)

ri

return chars and shorts as ints (see ri)

s

remove stack overflow checks (see s)

sg

generate calls to grow the stack (see sg)

st

touch stack through SS first (see st)

t=<num>

(C++ only) set tab stop multiplier (see t=<num>)

u<name>

preprocessor #undef name (see u<name>)

v

output function declarations to .def file (with typedef names) (see v)

vc...

(C++ only) VC++ compatibility options (see vc...)

w<number>

set warning level number (default is w1) (see w<number>)

wcd=<num>

warning control:  disable warning message <num> (see wcd=<number>)

wce=<num>

warning control:  enable warning message <num> (see wce=<number>)

we

treat all warnings as errors (see we)

wo

(C only) (16-bit only) warn about problems with overlaid code (see wo)

wx

set warning level to maximum setting (see wx)

x

preprocessor ignores environment variables (see x)

xd

(C++ only) disable exception handling (default) (see xd)

xdt

(C++ only) disable exception handling (same as "xd") (see xdt)

xds

(C++ only) disable exception handling (table-driven destructors) (see xds)

xr

(C++ only) enable RTTI (see xr)

xs

(C++ only) enable exception handling (see xs)

xst

(C++ only) enable exception handling (direct calls for destruction) (see xst)

xss

(C++ only) enable exception handling (table-driven destructors) (see xss)

xx

ignore default directories for file search (.,../h,../c,...) (see xx)

z{a,e}

disable/enable language extensions (default is ze) (see za) (see ze)

zastd=<standard>

use specified ISO/ANSI language standard (see zastd=<standard>)

za99

use ISO/ANSI C99 language standard; deprecated, use zastd=c99 (see zastd=<standard>)

zam

disable all predefined old extension macros (keyword macros, non-ISO names) (see zam)

zat

(C++ only) disable alternative tokens (see zat)

zc

place literal strings in code segment (see zc)

zd{f,p}

allow DS register to "float" or "peg" it to DGROUP (default is zdp) (see zd{f,p})

zdl

(32-bit only) load DS register directly from DGROUP (see zdl)

zev

(C only, Unix extension) enable arithmetic on void derived types (see zev)

zf

(C++ only) let scope of for loop initialization extend beyond loop (see zf)

zf{f,p}

allow FS register to be used (default for all but flat memory model) or not be used (default for flat memory model) (see zf{f,p})

zfw

generate FWAIT instructions on 386 and later (see zfw)

zg

output function declarations to .def (without typedef names) (see zg)

zg{f,p}

allow GS register to be used or not used (see zg{f,p})

zk0

double-byte char support for Kanji (see zk{0,1,2,l})

zk0u

translate Kanji double-byte characters to UNICODE (see zk0u)

zk1

double-byte char support for Chinese/Taiwanese (see zk{0,1,2,l})

zk2

double-byte char support for Korean (see zk{0,1,2,l})

zkl

double-byte char support if current code page has lead bytes (see zk{0,1,2,l})

zku=<codepage>

load UNICODE translate table for specified code page (see zku=<codepage>)

zl

suppress generation of library file names and references in object file (see zl)

zld

suppress generation of file dependency information in object file (see zld)

zlf

add default library information to object files (see zlf)

zls

remove automatically inserted symbols (such as runtime library references) (see zls)

zm

place each function in separate segment (near functions not allowed) (see zm)

zmf

place each function in separate segment (near functions allowed) (see zmf)

zp{1,2,4,8,16}

set minimal structure packing (member alignment) (see zp{1,2,4,8,16})

zpw

output warning when padding is added in a struct/class (see zpw)

zq

operate quietly (see zq)

zri

inline floating point rounding code (see zri)

zro

omit floating point rounding code (see zro)

zs

syntax check only (see zs)

zt<number>

set data threshold (default is 32767 for 16-bit and 2147483647 for 32-bit) (see zt<number>)

zu

do not assume that SS contains segment of DGROUP (see zu)

zv

(C++ only) enable virtual function removal optimization (see zv)

zw

Microsoft Windows prologue/epilogue code sequences (see zw)

zW

(16-bit only) Microsoft Windows optimized prologue/epilogue code sequences (see zW (optimized))

zWs

(16-bit only) Microsoft Windows smart callback sequences (see zWs)

zz

remove "@size" from __stdcall function names (10.0 compatible) (see zz)

Compiler Options - Summarized By Category

Summary:  Target Specific

Option:

Description:

bc

build target is a console application (see bc)

bd

build target is a Dynamic Link Library (DLL) (see bd)

bg

build target is a GUI application (see bg)

bm

build target is a multi-threaded environment (see bm)

br

build target uses DLL version of C/C++ run-time library (see br)

bt[=<os>]

build target for operating system <os> (see bt[=<os>])

bw

build target uses default windowing support (see bw)

of

generate traceable stack frames as needed (see of)

of+

always generate traceable stack frames (see of+)

sg

generate calls to grow the stack (see sg)

st

touch stack through SS first (see st)

zw

generate code for Microsoft Windows (see zw)

zW

(16-bit only) Microsoft Windows optimized prologue/epilogue code sequences (see zW (optimized))

zWs

(16-bit only) Microsoft Windows smart callback sequences (see zWs)

Summary:  Debugging/Profiling

Option:

Description:

d0

(C++ only) no debugging information (see d0)

d1

line number debugging information (see d1)

d1+

(C only) line number debugging information plus typing information for global symbols and local structs and arrays (see d1+)

d2

full symbolic debugging information (see d2)

d2i

(C++ only) d2 and debug inlines; emit inlines as external out-of-line functions (see d2i)

d2s

(C++ only) d2 and debug inlines; emit inlines as static out-of-line functions (see d2s)

d2t

(C++ only) d2 but without type names (see d2t)

d3

full symbolic debugging with unreferenced type names (see d3)

d3i

(C++ only) d3 plus debug inlines; emit inlines as external out-of-line functions (see d3i)

d3s

(C++ only) d3 plus debug inlines; emit inlines as static out-of-line functions (see d3s)

ee

call epilogue hook routine (see ee)

en

emit routine names in the code segment (see en)

ep[<number>]

call prologue hook routine with number stack bytes available (see ep[<number>])

et

Pentium profiling (see et)

h{w,d,c}

set debug output format (Open Watcom, DWARF, Codeview) (see h{w,d,c})

s

remove stack overflow checks (see s)

Summary:  Preprocessor

Option:

Description:

d<name>[=text]

precompilation #define name [text] (see d<name>[=text])

d+

allow extended "d" macro definitions on command line (see d+)

fo[=<file_name>]

set preprocessor output file name (see fo[=<file_name>] (preprocessor))

pil

preprocessor ignores #line directives (see pil)

p{e,l,c,w=<num>}

preprocess file

c

preserve comments

e

encrypt identifiers (C++ only)

l

insert #line directives

w=<num>

wrap output lines at <num> columns.  Zero means no wrap.

(see p{e,l,c,w=<num>})

u<name>

undefine macro name (see u<name>)

Summary:  Diagnostics

Option:

Description:

e<number>

set error limit number (see e<number>)

ef

use full path names in error messages (see ef)

eq

do not display error messages (they are still written to a file) (see eq)

er

(C++ only) do not recover from undefined symbol errors (see er)

ew

(C++ only) alternate error message formatting (see ew)

q

operate quietly (see q)

t=<num>

set tab stop multiplier (see t=<num>)

w<number>

set warning level number (see w<number>)

wcd=<num>

warning control:  disable warning message <num> (see wcd=<number>)

wce=<num>

warning control:  enable warning message <num> (see wce=<number>)

we

treat all warnings as errors (see we)

wx

set warning level to maximum setting (see wx)

z{a,e}

disable/enable language extensions (see za) (see ze)

zastd=<standard>

use specified ISO/ANSI language standard (see zastd=<standard>)

za99

use ISO/ANSI C99 language standard; deprecated, use zastd=c99 (see zastd=<standard>)

zq

operate quietly (see zq)

zs

syntax check only (see zs)

Summary:  Source/Output Control

Option:

Description:

ad[=<file_name>]

generate make style auto-dependency file (see ad[=<file_name>])

adbs

force path separators generated in make style auto-dependency file to backslashes (see adbs)

add[=<file_name>]

set source name (the first dependency) for make style auto-dependency file (see add[=<file_name>])

adhp[=<path prefix>]

set default path for header dependencies which result in filename only (see adhp[=<path_name>])

adfs

force path separators generated in make style auto-dependency file to forward slashes (see adfs)

adt[=<target_name>]

specify target name generated in make style auto-dependency file (see adt[=<target_name>])

db

generate browsing information (see db)

ez

generate PharLap EZ-OMF object files (see ez)

fc=<file_name>

(C++ only) specify file of command lines to be batch processed (see fc=<file_name>)

fh[q][=<file_name>]

use precompiled headers (see fh[q][=<file_name>])

fhd

store debug info for pre-compiled header once (DWARF only) (see fhd)

fhr

(C++ only) force compiler to read pre-compiled header (will never write) (see fhr)

fhw

(C++ only) force compiler to write pre-compiled header (will never read) (see fhw)

fhwe

(C++ only) don't include pre-compiled header warnings when "we" is used (see fhwe)

fi=<file_name>

force file_name to be included (see fi=<file_name>)

fo[=<file_name>]

set object or preprocessor output file name (see fo[=<file_name>])

fr[=<file_name>]

set error file name (see fr[=<file_name>])

ft

try truncated (8.3) header file specification (see ft)

fti

(C only) track include file opens (see fti)

fx

do not try truncated (8.3) header file specification (see fx)

fzh

(C++ only) do not automatically append extensions for include files (see fzh)

fzs

(C++ only) do not automatically append extensions for source files (see fzs)

i=<directory>

another include directory (see i=<directory>)

k

continue processing files (ignore errors) (see k)

v

output function declarations to .def (see v)

x

ignore environment variables when searching for include files (see x)

xx

ignore default directories for file search (.,../h,../c,...) (see xx)

zam

disable all predefined old extension macros (keyword macros, non-ISO names) (see zam)

zat

(C++ only) disable alternative tokens (see zat)

zf

(C++ only) let scope of for loop initialization extend beyond loop (see zf)

zg

generate function prototypes using base types (see zg)

zl

remove default library information (see zl)

zld

remove file dependency information (see zld)

zlf

add default library information to object files (see zlf)

zls

remove automatically generated symbols references (see zls)

Summary:  Code Generation

Option:

Description:

ecc

set default calling convention to __cdecl (see ecc)

ecd

set default calling convention to __stdcall (see ecd)

ecf

set default calling convention to __fastcall (see ecf)

ecp

set default calling convention to __pascal (see ecp)

ecr

set default calling convention to __fortran (see ecr)

ecs

set default calling convention to __syscall (see ecs)

ecw

set default calling convention to __watcall (default) (see ecw)

ei

force enum base type to use at least an int (see ei)

em

force enum base type to use minimum (see em)

j

change char default from unsigned to signed (see j)

ri

return chars and shorts as ints (see ri)

xr

(C++ only) enable RTTI (see xr)

zc

place literal strings in the code segment (see zc)

zp{1,2,4,8,16}

pack structure members (see zp{1,2,4,8,16})

zpw

output warning when padding is added in a struct/class (see zpw)

zt<number>

set data threshold (see zt<number>)

zv

(C++ only) enable virtual function removal optimization (see zv)

Summary:  80x86 Floating Point

Option:

Description:

fpc

calls to floating-point library (see fpc)

fpi

in-line 80x87 instructions with emulation (see fpi)

fpi87

in-line 80x87 instructions (see fpi87)

fp2

generate floating-point for 80x87 (see fp2)

fp3

generate floating-point for 387 (see fp3)

fp5

optimize floating-point for Pentium (see fp5)

fp6

optimize floating-point for Pentium Pro (see fp6)

fpd

enable generation of Pentium FDIV bug check code (see fpd)

Summary:  Segments/Modules

Option:

Description:

g=<codegroup>

set code group name (see g=<codegroup>)

nc=<name>

set code class name (see nc=<name>)

nd=<name>

set data segment name (see nd=<name>)

nm=<name>

set module name (see nm=<name>)

nt=<name>

set name of text segment (see nt=<name>)

zm

place each function in separate segment (near functions not allowed) (see zm)

zmf

(C++ only) place each function in separate segment (near functions allowed) (see zmf)

Summary:  80x86 Run-time Conventions

Option:

Description:

0

(16-bit only) 8088 and 8086 instructions (see 0)

1

(16-bit only) 188 and 186 instructions (see 1)

2

(16-bit only) 286 instructions (see 2)

3

(16-bit only) 386 instructions (see 3)

4

(16-bit only) 486 instructions (see 4)

5

(16-bit only) Pentium instructions (see 5)

6

(16-bit only) Pentium Pro instructions (see 6)

3r

(32-bit only) 386 register calling conventions (see 3{r|s})

3s

(32-bit only) 386 stack calling conventions (see 3{r|s})

4r

(32-bit only) 486 register calling conventions (see 4{r|s})

4s

(32-bit only) 486 stack calling conventions (see 4{r|s})

5r

(32-bit only) Pentium register calling conventions (see 5{r|s})

5s

(32-bit only) Pentium stack calling conventions (see 5{r|s})

6r

(32-bit only) Pentium Pro register calling conventions (see 6{r|s})

6s

(32-bit only) Pentium Pro stack calling conventions (see 6{r|s})

m{f,s,m,c,l,h}

memory model (Flat,Small,Medium,Compact,Large,Huge) (see mf)

zdf

DS floats i.e.  not fixed to DGROUP (see zd{f,p})

zdp

DS is pegged to DGROUP (see zd{f,p})

zdl

Load DS directly from DGROUP (see zdl)

zff

FS floats i.e.  not fixed to a segment (see zf{f,p})

zfp

FS is pegged to a segment (see zf{f,p})

zgf

GS floats i.e.  not fixed to a segment (see zg{f,p})

zgp

GS is pegged to a segment (see zg{f,p})

zri

Inline floating point rounding code (see zri)

zro

Omit floating point rounding code (see zro)

zu

SS != DGROUP (see zu)

Summary:  Optimizations

Option:

Description:

oa

relax aliasing constraints (see oa)

ob

enable branch prediction (see ob)

oc

disable <call followed by return> to <jump> optimization (see oc)

od

disable all optimizations (see od)

oe[=<num>]

expand user functions in-line.  <num> controls max size (see oe=<num>)

oh

enable repeated optimizations (longer compiles) (see oh)

oi

expand intrinsic functions in-line (see oi)

oi+

(C++ only) expand intrinsic functions in-line and set inline_depth to maximum (see oi+)

ok

enable control flow prologues and epilogues (see ok)

ol

enable loop optimizations (see ol)

ol+

enable loop optimizations with loop unrolling (see ol+)

om

generate in-line 80x87 code for math functions (see om)

on

allow numerically unstable optimizations (see on)

oo

continue compilation if low on memory (see oo)

op

generate consistent floating-point results (see op)

or

reorder instructions for best pipeline usage (see or)

os

favor code size over execution time in optimizations (see os)

ot

favor execution time over code size in optimizations (see ot)

ou

all functions must have unique addresses (see ou)

ox

equivalent to -obmiler -s (see ox)

oz

NULL points to valid memory in the target environment (see oz)

Summary:  C++ Exception Handling

Option:

Description:

xd

disable exception handling (default) (see xd)

xdt

disable exception handling (same as "xd") (see xdt)

xds

disable exception handling (table-driven destructors) (see xds)

xs

enable exception handling (see xs)

xst

enable exception handling (direct calls for destruction) (see xst)

xss

enable exception handling (table-driven destructors) (see xss)

Summary:  Double-Byte/Unicode Characters

Option:

Description:

zk{0,1,2,l}

double-byte char support:  0=Kanji,1=Chinese/Taiwanese,2=Korean,l=local (see zk{0,1,2,l})

zk0u

translate double-byte Kanji to UNICODE (see zk0u)

zku=<codepage>

load UNICODE translate table for specified code page (see zku=<codepage>)

Summary:  Compatibility with Microsoft Visual C++

Option:

Description:

vc...

VC++ compatibility options (see vc...)

vcap

allow alloca() or _alloca() in a parameter list

Summary:  Compatibility with Older Versions of the 80x86 Compilers

Option:

Description:

r

save/restore segment registers across calls (see r)

fpr

generate backward compatible 80x87 code (see fpr)

zz

generate backward compatible __stdcall conventions by removing the "@size" from __stdcall function names (10.0 compatible) (see zz)

Compiler Options - Full Description

Target Specific

bc

1. The presence of one of LibMain or DLLMain implies that the DLL startup code and libraries should be used.
2. The presence of WinMain or wWinMain implies that the GUI startup code and libraries should be used.
3. The presence of main or wmain implies that the default startup code and libraries should be used.

bd

bg

bm

br

bt[=<os>]

DOS

when the host operating system is DOS,

OS2

when the host operating system is OS/2,

NT

when the host operating system is Windows NT/Windows 95,

QNX

when the host operating system is QNX, or

LINUX

when the host operating system is Linux.

Target name

Additional operation

DOS

Defines the macros _DOS and MSDOS.

WINDOWS

Same as specifying one of the "zw" options.  Defines the macros _WINDOWS (16-bit only) and __WINDOWS_386__ (32-bit only).

NETWARE

(32-bit only) Causes the compiler to use stack-based calling conventions.  Also defines the macro __NETWARE_386__.

NT

Defines the macro _WIN32.

QNX

Defines the macro __UNIX__.

LINUX

Defines the macro __UNIX__.

bw

of

of+

sg

st

zw

zW (optimized)

zWs

Debugging/Profiling

d0

d1

d1+

d2

d2i

d2s

d2t

d3

d3i

d3s

ee

en

ep[<number>]

et

h{w,d,c}

s

Preprocessor

d<name>[=text]

d+

fo[=<file_name>] (preprocessor)

pil

p{e,l,c,w=<num>}

u<name>

Diagnostics

e<number>

ef

eq

er

ew

q

t=<num>

w<number>

wcd=<number>

wce=<number>

we

wo

wx

za

zastd=<standard>

C compiler value

Description

c89

C 1989 standard (default)

c99

C 1999 standard

C++ compiler value

Description

c++98

C++ 1998 standard (default)

c++0x

experimental, some features of new C++ standards

za99

ze

1. The requirement for at least one external definition per module is relaxed.
2. When using the C compiler, some forgiveable pointer type mismatches become warnings instead of errors.
3. In-line math functions are allowed (note that errno will not be set by in-line functions).
4. When using the C compiler, anonymous structs/unions are allowed (this is always permitted in C++).
   
   Example:
   
        struct {
            int a;
            union {
                int   b;
                float alt_b;
            };
            int c;
        } x;
   
   In the above example, "x.b" is a valid reference to the "b" field.
5. For C only, ISO function prototype scope rules are relaxed to allow the following program to compile without any errors.
   
   Example:
   
        void foo( struct a *__p );
   
        struct a {
            int b;
            int c;
        };
   
        void bar( void )
        {
            struct a x;
            foo( &x );
        }
   
   According to a strict interpretation of the ISO C standard, the function prototype introduces a new scope which is terminated at the semicolon (;).  The effect of this is that the structure tag "a" in the function "foo" is not the same structure tag "a" defined after the prototype.  A diagnostic must be issued for a conforming ISO C implementation.
6. A trailing comma (,) is allowed after the last constant in an enum declaration.
   
   Example:
   
        enum colour { RED, GREEN, BLUE, };
7. The ISO requirement that all enums have a base type of int is relaxed.  The motivation for this extension is conservation of storage.  Many enums can be represented by integral types that are smaller in size than an int.
   
   Example:
   
        enum colour { RED, GREEN, BLUE, };
   
        void foo( void )
        {
            enum colour x;
   
            x = RED;
        }
   
   In the example, "x" can be stored in an unsigned char because its values span the range 0 to 2.
8. The ISO requirement that the base type of a bitfield be int or unsigned is relaxed.  This allows a programmer to allocate bitfields from smaller units of storage than an int (e.g., unsigned char).
   
   Example:
   
        struct {
            unsigned char a : 1;
            unsigned char b : 1;
            unsigned char c : 1;
        } x;
   
        struct {
            unsigned a : 1;
            unsigned b : 1;
            unsigned c : 1;
        } y;
   
   In the above example, the size of "x" is the same size as an unsigned char whereas the size of "y" is the same size as an unsigned int.
9. Enable all predefined macros which name is not ISO/ANSI C/C++ compliant.  The following macros are defined. 
   
        
        _near, near
        _far, far, SOMDLINK (16-bit)
        _huge, huge
        _based
        _segment
        _segname
        _self
        _cdecl, cdecl, SOMLINK (16-bit)
        _pascal, pascal
        _fastcall
        _fortran, fortran
        _inline
        _interrupt, interrupt
        _export
        _loadds
        _saveregs
        _stdcall
        _syscall, SOMLINK (32-bit), SOMDLINK (32-bit)
        _far16

zq

zs

Source/Output Control

aa

ad[=<file_name>]

adbs

add[=<file_name>]

adhp[=<path_name>]

adfs

adt[=<target_name>]

db

ez

fc=<file_name>

fh[q][=<file_name>]

fhd

fhr

fhw

fhwe

fi=<file_name>

fo[=<file_name>]

fr[=<file_name>]

ft

fti

fx

fzh

fzs

i=<directory>

k

v

x

xx

• current directory "." is ignored when searching for include files
• adjacent ..\h directory is ignored when searching for include files
• don't do recursive search for parent directories when searching for include files
• adjacent ..\c directory is ignored when searching for source file

zam

zat

zf

zg

zl

zld

zlf

zls

Code Generation

ecc

ecd

ecf

ecp

ecr

ecs

ecw

ei

em

j

ri

xr

zc

zp{1,2,4,8,16}

zpw

zt<number>

zv

80x86 Floating Point

FPC

1. not IEEE floating-point
2. not tailorable to processor
3. uses coprocessor if present; simulates otherwise
4. 32-bit/64-bit accuracy
5. runs somewhat faster if coprocessor present
6. faster emulation (fewer bits of accuracy)
7. leaner "math" library
8. fatter application code (calls to library rather than in-line instructions)
9. application cannot trap floating-point exceptions
10. ideal for ROM applications

FPI, FPI87

1. IEEE floating-point
2. tailorable to processor (see fp2, fp3, fp5, fp6)
3. uses coprocessor if present; emulates IEEE otherwise
4. up to 80-bit accuracy
5. runs "full-tilt" if coprocessor present
6. slower emulation (more bits of accuracy)
7. fatter "math" library
8. leaner application code (in-line instructions)
9. application can trap floating-point exceptions
10. ideal for general-purpose applications

fpc

1. Speed of floating-point emulation is favoured over code size.
2. An application containing floating-point operations is to be stored in ROM and an 80x87 will not be present in the system.

fpi

fpi87

fp2

fp3

fp5

fp6

fpd

1. You may test the __chipbug variable in your code in all floating-point and memory models and take appropriate action (such as display a warning message or discontinue the application).
2. Alternately, you can use the "fpd" option when compiling your code.  This option directs the compiler to generate additional code whenever an FDIV instruction is generated which tests the low order bit of __chipbug and, if on, calls the software workaround code in the math libraries.  If the bit is off, an in-line FDIV instruction will be performed as before.

Segments/Modules

g=<codegroup>

nc=<name>

nd=<name>

nm=<name>

nt=<name>

zm

1. Since each function is placed in its own segment, functions that are not required by an application are omitted from the executable by the linker (when "OPTION ELIMINATE" is specified).
2. This can result in smaller executables.
3. This benefit applies to both small and large code models.
4. This option allows you to create granular libraries without resorting to placing each function in a separate file.

1. The "near call" optimization for static functions in large code models is disabled (e.g., the function foo in the example above will never be "near called".  Static functions will always be "far called" in large code models.
2. Near static functions will still be "near called" (e.g., the function foo1 is "near called" in the example above).  However, this can lead to problems at link time if the caller function ends up in a different segment from the called function (the linker will issue a message if this is the case).
3. The "common epilogue" optimization is lost.
4. The linker "OPTION ELIMINATE" must be specified when linking an application to take advantage of the granularity inherent in object files/libraries compiled with this option.
5. Any assumptions about relative position of functions are invalid.  Consider the following code which attempts to determine the size of a code region by subtracting function addresses:
   
   Example:
   
        region_size = (unsigned long)&function2 - (unsigned long)function1;
   
   When "zm" is in effect, region_size may be extremely large or even a negative value.  For the above code to work as intended, both function1 and function2 (and every function intended to be located between them) must reside in a single code segment.

zmf

1. All functions in a module will reside in the same physical segment in an executable.
2. The "near call" optimization for static functions in large code models is not disabled (e.g., the function foo in the example above will be "near called".  Static functions will always be "near called" in large code models.
3. The problem associated with calling "near" functions goes away since all functions in a module will reside in the same physical segment (e.g., the function foo1 is "near" in the example above).

1. The size of a physical segment is restricted to 64K in 16-bit applications.  Although this may limit the number of functions that can be placed in the segment, the restriction is only on a "per module" basis.
2. Although less constricting, the size of a physical segment is restricted to 4G in a 32-bit application.

80x86 Run-time Conventions

0

1

2

3

4

5

6

3{r|s}

• The compiler will pass arguments in registers whenever possible.  This is the default method used to pass arguments (unless the "bt=netware" option is specified).
• All registers except EAX are preserved across function calls.
• When any form of the "fpi" option is used, the result of functions of type "float" and "double" is returned in ST(0).
• When the "fpc" option is used, the result of a function of type "float" is returned in EAX and the result of a function of type "double" is returned in EDX:EAX.
• The resulting code will be smaller than that which is generated for the stack-based method of passing arguments (see "3s" below).
• The default naming convention for all global functions is such that an underscore character ("_") is suffixed to the symbol name.  The default naming convention for all global variables is such that an underscore character ("_") is prefixed to the symbol name.

• The compiler will pass all arguments on the stack.
• The EAX, ECX and EDX registers are not preserved across function calls.
• The FS and GS registers are not preserved across function calls.
• The result of a function of type "float" is returned in EAX.  The result of a function of type "double" is returned in EDX:EAX.
• The resulting code will be larger than that which is generated for the register method of passing arguments (see "3r" above).
• The naming convention for all global functions and variables is modified such that no underscore characters ("_") are prefixed or suffixed to the symbol name.

4{r|s}

5{r|s}

6{r|s}

mf

ms

mm

mc

ml

mh

zd{f,p}

zdl

zev

zf{f,p}

zfw

zg{f,p}

zri

zro

zu

Optimizations

oa

ob

oc

od

oe=<num>

oh

oi

oi+

ok

ol

ol+

om

on

oo

op

or

os

ot

ou

ox

oz

C++ Exception Handling

xd

• Destruction of objects is caused by direct calls to the appropriate destructors
• Destructor functions are implemented with direct calls to appropriate destructors to destruct base classes and class members.

xdt

xds

• Destruction of objects is caused by direct calls to the appropriate destructors.
• Destruction of base classes and class members is accomplished by interpreting tables.
• This option, in general, generates smaller code, with increased execution time and with more run-time system routines included by the linker.

xs

• Tables are interpreted to effect destruction of temporaries and automatic objects; destructor functions are implemented with direct calls to appropriate destructors to destruct base classes and class members.

xst

• Destruction of temporaries and automatic objects is accomplished with direct calls to appropriate destructors; destructor functions are implemented with direct calls to appropriate destructors to destruct base classes and class members.
• This scheme will execute faster, but will use more space in general.

xss

• Tables are interpreted to effect destruction of temporaries and automatic objects; destruction of base classes and class members is accomplished by interpreting tables.
• This option, in general, generates smaller code, with increased execution time.

Double-Byte/Unicode Characters

zk{0,1,2,l}

zk, zk0

These options cause the compiler to process strings for Japanese double-byte characters (range 0x81 - 0x9F and 0xE0 - 0xFC).   The characters in the range A0 - DF are single-byte Katakana.

zk1

This option causes the compiler to process strings for Traditional Chinese and Taiwanese double-byte characters (range 0x81 - 0xFC).

zk2

This option causes the compiler to process strings for Korean Hangeul double-byte characters (range 0x81 - 0xFD).

zkl

This option causes the compiler to process strings using the current code page.  If the local character set includes double-byte characters then string processing will check for lead bytes.

zk0u

zku=<codepage>

Compatibility with Microsoft Visual C++

vc...

vcap

Compatibility with Older Versions of the 80x86 Compilers

r

fpr

zz

The Open Watcom C/C++ Compilers

• Command line syntax (see Open Watcom C/C++ Command Line Format)
• Environment variables used by the compilers (see Environment Variables)
• Examples of command line syntax (see Open Watcom C/C++ Command Line Examples)
• Interpreting diagnostic messages (see Compiler Diagnostics)
• #include file handling (see Open Watcom C/C++ #include File Processing)
• Using the preprocessor built into the compilers (see Open Watcom C/C++ Preprocessor)
• System-dependent macros predefined by the compilers (see Open Watcom C/C++ Predefined Macros)
• Additional keywords supported by the compilers (see Open Watcom C/C++ Extended Keywords)
• Based pointer support in the compilers (see Based Pointers)
• Notes about the Code Generator (see The Open Watcom Code Generator)

Open Watcom C/C++ Command Line Format

compiler_name

is one of the Open Watcom C/C++ compiler command names. 

WCC

is the Open Watcom C compiler for 16-bit Intel platforms.

WPP

is the Open Watcom C++ compiler for 16-bit Intel platforms.

WCC386

is the Open Watcom C compiler for 32-bit Intel platforms.

WPP386

is the Open Watcom C++ compiler for 32-bit Intel platforms.

file_spec

is the file name specification of one or more files to be compiled.  If file_spec is specified as the single character ".", an input file is read from standard input and the output file name defaults to stdin.obj.
If no drive is specified, the default drive is assumed.

If no path is specified, the current working directory is assumed.

If the "xx" option was not specified and the file is not in the current directory then an adjacent "C" directory (i.e., ..\c) is searched if it exists.

If no file extension is specified, the compiler will check for a file with one of the following extensions in the order listed:

.CPP

(C++ only)

.CC

(C++ only)

.C

(C/C++)

If a period "." is specified but not the extension, the file is assumed to have no filename extension.

If only the compiler name is specified then the compiler will display a list of available options.

options

is a list of valid compiler options, each preceded by a slash ("/") or a dash ("-").  Options may be specified in any order.

extra_opts

is the name of an environment variable or file which contains additional command line options to be processed.  If the specified environment variable does not exist, a search is made for a file with the specified name.  If no file extension is included in the specified name, the default file extension is ".occ".  A search of the current directory is made.  If not successful, an adjacent "OCC" directory (i.e., ..\occ) is searched if it exists.

Open Watcom C/C++ DLL-based Compilers

WCCD

is the DLL version of the Open Watcom C compiler for 16-bit Intel platforms.

WPPDI86

is the DLL version of the Open Watcom C++ compiler for 16-bit Intel platforms.

WCCD386

is the DLL version of the Open Watcom C compiler for 32-bit Intel platforms.

WPPD386

is the DLL version of the Open Watcom C++ compiler for 32-bit Intel platforms.

Environment Variables

WCC

used with the Open Watcom C compiler for 16-bit Intel platforms
Example:

     C>set wcc=-d1 -ot

WPP

used with the Open Watcom C++ compiler for 16-bit Intel platforms
Example:

     C>set wpp=-d1 -ot

WCC386

used with the Open Watcom C compiler for 32-bit Intel platforms
Example:

     C>set wcc386=-d1 -ot

WPP386

used with the Open Watcom C++ compiler for 32-bit Intel platforms
Example:

     C>set wpp386=-d1 -ot

Open Watcom C/C++ Command Line Examples

Benchmarking Hints

Pentium Pro

-onatx -oh -oi+ -ei -zp8 -6 -fpi87 -fp6

Pentium

-onatx -oh -oi+ -ei -zp8 -5 -fpi87 -fp5

486

-onatx -oh -oi+ -ei -zp8 -4 -fpi87 -fp3

386

-onatx -oh -oi+ -ei -zp8 -3 -fpi87 -fp3

286

-onatx -oh -oi+ -ei -zp8 -2 -fpi87 -fp2

186

-onatx -oh -oi+ -ei -zp8 -1 -fpi87

8086

-onatx -oh -oi+ -ei -zp8 -0 -fpi87

Pentium Pro

-onatx -oh -oi+ -ei -zp8 -6 -fp6

Pentium

-onatx -oh -oi+ -ei -zp8 -5 -fp5

486

-onatx -oh -oi+ -ei -zp8 -4 -fp3

386

-onatx -oh -oi+ -ei -zp8 -3 -fp3

Compiler Diagnostics

1. the variable x should have been assigned a value, and
2. the variable y has probably been incorrectly typed and should have been entered as x.

Open Watcom C/C++ #include File Processing

1. If the file specification enclosed in quotation marks ("file-spec") or angle brackets (<file-spec>) contains the complete drive and path specification, that file is included (provided it exists).  No other searching is performed.   The drive need not be specified in which case the current drive is assumed.
2. Next, if the "xx" option was not specified and the file specification is enclosed in quotation marks then the current directory is searched.
3. Next, if the file specification is enclosed in quotation marks, the directory of the file containing the #include directive is searched.
4. Next, if the "xx" option was not specified and the current file is also an #include file then the directory of the parent file is searched next.  This search continues recursively through all the nested #include files until the original source file's directory is searched.
5. Next, if the file specification enclosed in quotation marks ("file-spec") or in angle brackets (<file-spec>), each directory listed in the "i" path is searched (in the order that they were specified).
6. Next, if the "x" option was not specified, each directory listed in the <os>_INCLUDE environment variable is searched (in the order that they were specified).  The environment variable name is constructed from the current build target name.  The default build targets are:

   DOS

   when the host operating system is DOS,

   
   OS2

   when the host operating system is OS/2,

   
   NT

   when the host operating system is Windows NT/95,

   
   QNX

   when the host operating system is QNX, or

   
   LINUX

   when the host operating system is Linux.

   
   For example, the environment variable OS2_INCLUDE will be searched if the build target is "OS2".  The build target would be OS/2 if:
   1. the host operating system is OS/2 and the "bt" option was not specified, or
   2. the "bt=OS2" option was explicitly specified.
7. Next, if the "x" option was not specified, each directory listed in the INCLUDE environment variable is searched (in the order that they were specified).
8. Finally, if the "xx" option was not specified and the file specification is enclosed in quotation marks then an adjacent "H" directory (i.e., ..\h) is searched if it exists.

Open Watcom C/C++ Preprocessor

Open Watcom C/C++ Predefined Macros

1. The __X86__ identifies the target as an Intel environment.
2. The __I86__, M_I86 and _M_I86 macros identify the target as a 16-bit Intel environment.
3. The __386__, M_I386 and _M_I386 macros identify the target as a 32-bit Intel environment.
4. The _M_IX86 macro is identically equal to 100 times the architecture compiler option value (-0, -1, -2, -3, -4, -5, etc.).  If "-5" (Pentium instruction timings) was specified as a compiler option, then the value of _M_IX86 would be 500.

1. The __DOS__, _DOS and MSDOS macros are defined when the build target is "DOS" (16-bit DOS or 32-bit extended DOS).
2. The __OS2__ macro is defined when the build target is "OS2" (16-bit or 32-bit OS/2).
3. The __QNX__ and __UNIX__ macros are defined when the build target is "QNX" (16-bit or 32-bit QNX).
4. The __NETWARE__ and __NETWARE_386__ macros are defined when the build target is "NETWARE" (Novell NetWare).
5. The __NT__ macro is defined when the build target is "NT" (Windows NT and Windows 95).
6. The __WINDOWS__ macro is defined when the build target is "WINDOWS" or one of the "zw", "zW", "zWs" options is specified (identifies the target operating system as 16-bit Windows or 32-bit extended Windows but not Windows NT or Windows 95).
7. The _WINDOWS macro is defined when the build target is "WINDOWS" or one of the "zw", "zW", "zWs" options is specified and you are using a 16-bit compiler (identifies the target operating system as 16-bit Windows).
8. The __WINDOWS_386__ macro is defined when the build target is "WINDOWS" or the "zw" option is specified and you are using a 32-bit compiler (identifies the target operating system as 32-bit extended Windows).
9. The __LINUX__ and __UNIX__ macros are defined when the build target is "LINUX" (32-bit Linux).

__cplusplus

Open Watcom C++ predefines the macro __cplusplus to identify the compiler as a C++ compiler.

__WATCOMC__

Open Watcom C/C++ predefines the macro __WATCOMC__ to identify the compiler as one of the Open Watcom C/C++ compilers.
The value of the macro depends on the version number of the compiler.  The value is 100 times the version number (version 8.5 yields 850, version 9.0 yields 900, etc.).  Note that for Open Watcom 1.0, the value of this macro is 1200, for Open Watcom 1.1 it is 1210 etc.

__WATCOM_CPLUSPLUS__

Open Watcom C++ predefines the macro __WATCOM_CPLUSPLUS__ to identify the compiler as one of the Open Watcom C++ compilers.
The value of the macro depends on the version number of the compiler.  The value is 100 times the version number (version 10.0 yields 1000, version 10.5 yields 1050, etc.).  Note that for Open Watcom 1.0, the value of this macro is 1200, for Open Watcom 1.1 it is 1210 etc.

__CPPRTTI

Open Watcom C++ predefines the __CPPRTTI macro to indicate that C++ Run-Time Type Information (RTTI) is in force.   This macro is predefined if the Open Watcom C++ "xr" compile option is specified and is not defined otherwise.

__CPPUNWIND

Open Watcom C++ predefines the __CPPUNWIND macro to indicate that C++ exceptions supported.  This macro is predefined if any of the Open Watcom C++ "xs", "xss" or "xst" compile options are specified and is not defined otherwise.

_INTEGRAL_MAX_BITS

Open Watcom C/C++ predefines the _INTEGRAL_MAX_BITS macro to indicate that maximum number of bits supported in an integral type (see the description of the "__int64" keyword in the next section).  Its value is 64 currently.

_PUSHPOP_SUPPORTED

Open Watcom C/C++ predefines the _PUSHPOP_SUPPORTED macro to indicate that #pragma pack(__push) and #pragma pack(__pop) are supported.

_STDCALL_SUPPORTED

Open Watcom C/C++ predefines the _STDCALL_SUPPORTED macro to indicate that the standard 32-bit Win32 calling convention is supported.

Open Watcom C/C++ Extended Keywords

__near

Open Watcom C/C++ supports the __near keyword to describe functions and other object names that are in near memory and pointers to near objects.
Open Watcom C/C++ predefines the macros near and _near to be equivalent to the __near keyword.

__far

Open Watcom C/C++ supports the __far keyword to describe functions and other object names that are in far memory and pointers to far objects.
Open Watcom C/C++ predefines the macros far, _far and SOMDLINK (16-bit only) to be equivalent to the __far keyword.

__huge

Open 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.
Open Watcom C/C++ predefines the macros huge and _huge to be equivalent to the __huge keyword.

__based

Open Watcom C/C++ supports the __based keyword to describe pointers to objects that appear in other segments or the objects themselves.  See the section entitled Based Pointers for an explanation of the __based keyword.
Open Watcom C/C++ predefines the macro _based to be equivalent to the __based keyword.

__segment

Open Watcom C/C++ supports the __segment keyword which is used when describing objects of type segment.  See the section entitled Based Pointers for an explanation of the __segment keyword.
Open Watcom C/C++ predefines the macro _segment to be equivalent to the __segment keyword.

__segname

Open Watcom C/C++ supports the __segname keyword which is used when describing segname constant based pointers or objects.  See the section entitled Based Pointers for an explanation of the __segname keyword.
Open Watcom C/C++ predefines the macro _segname to be equivalent to the __segname keyword.

__self

Open Watcom C/C++ supports the __self keyword which is used when describing self based pointers.  See the section entitled Based Pointers for an explanation of the __self keyword.
Open Watcom C/C++ predefines the macro _self to be equivalent to the __self keyword.

__restrict

Open Watcom C/C++ provides the __restrict type qualifier as an alternative to the ISO C99 restrict keyword; it is supported even when C99 keywords aren't visible.  This type qualifier is used as an optimization hint.   Any object accessed through a restrict qualified pointer may only be accessed through that pointer and the compiler may assume that there will be no aliasing.

_Packed

Open Watcom C/C++ supports the _Packed keyword which is used when describing a structure.  If specified before the struct keyword, the compiler will force 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

Open Watcom C/C++ supports the __cdecl keyword to describe C functions that are called using a special convention.
Notes:

1. All symbols are preceded by an underscore character.
2. Arguments are pushed on the stack from right to left.  That is, the last argument is pushed first.  The calling routine will remove the arguments from the stack.
3. Floating-point values are returned in the same way as structures.  When a structure is returned, the called routine returns a pointer in register AX/EAX to the return value which is stored in the data segment (DGROUP).
4. For the 16-bit compiler, registers AX, BX, CX and DX, and segment register ES are not saved and restored when a call is made.
5. For the 32-bit compiler, registers EAX, ECX and EDX are not saved and restored when a call is made.

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

__pascal

Open 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.
Open Watcom C/C++ predefines the macros pascal, _pascal and _Pascal to be equivalent to the __pascal keyword.

__fortran

Open 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 "_" which is appended to the function name for certain calling conventions.
Open Watcom C/C++ predefines the macros fortran and _fortran to be equivalent to the __fortran keyword.

__interrupt

Open Watcom C/C++ supports the __interrupt keyword to describe a function that is an interrupt handler.
Example:

     #include <i86.h>

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

The code generator will emit 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 will emit instructions to establish addressability to the program's data segment since the DS segment register contents are unpredictable.  The function will return using an "IRET" (16-bit) or "IRETD" (32-bit) (interrupt return) instruction.

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

__declspec( modifier )

Open Watcom C/C++ supports the __declspec keyword for compatibility with Microsoft C++.  The __declspec keyword is used to modify storage-class attributes of functions and/or data.  There are several modifiers that can be specified with the __declspec keyword:  thread, naked, noreturn, farss, dllimport, dllexport, __pragma( "string" ), __cdecl, __pascal, __fortran, __stdcall, and __syscall.  These attributes are a property only of the declaration of the object or function to which they are applied.  Unlike the __near and __far keywords, which actually affect the type of object or function (in this case, 2- and 4-byte addresses), these storage-class attributes do not redefine the type attributes of the object itself.  The __pragma modifier is supported by Open Watcom C++ only.  The thread attribute affects data and objects only.  The naked, noreturn, farss, __pragma, __cdecl, __pascal, __fortran, __stdcall, and __syscall attributes affect functions only.  The dllimport and dllexport attributes affect functions, data, and objects.  For more information on the __declspec keyword, please see the section entitled The __declspec Keyword.

__export

Open Watcom C/C++ supports the __export keyword to describe functions and other object names that are to be exported from a Microsoft Windows DLL, OS/2 DLL, or Netware NLM.  See also the description of the "zu" option.
Example:

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

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

__loadds

Open 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 will be placed in a Microsoft Windows or OS/2 1.x Dynamic Link Library (DLL).  See also the description of the "nd" and "zu" options.
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 upon entry to the function.

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

__saveregs

Open 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 segment registers.
Open 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.
Notes:

1. All symbols are preceded by an underscore character.
2. All C symbols (extern "C" symbols in C++) are suffixed by "@nnn" where "nnn" is the sum of the argument sizes (each size is rounded up to a multiple of 4 bytes so that char and short are size 4).  When the argument list contains "...", the "@nnn" suffix is omitted.
3. Arguments are pushed on the stack from right to left.  That is, the last argument is pushed first.  The called routine will remove the arguments from the stack.
4. When a structure is returned, the caller allocates space on the stack.  The address of the allocated space will be pushed on the stack immediately before the call instruction.  Upon returning from the call, register EAX will contain address of the space allocated for the return value.  Floating-point values are returned in 80x87 register ST(0).
5. Registers EAX, ECX and EDX are not saved and restored when a call is made.

__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.
Notes:

1. Symbols names are not modified, that is, they are not adorned with leading or trailing underscores.
2. Arguments are pushed on the stack from right to left.  That is, the last argument is pushed first.  The calling routine will remove the arguments from the stack.
3. When a structure is returned, the caller allocates space on the stack.  The address of the allocated space will be pushed on the stack immediately before the call instruction.  Upon returning from the call, register EAX will contain address of the space allocated for the return value.  Floating-point values are returned in 80x87 register ST(0).
4. Registers EAX, ECX and EDX are not saved and restored when a call is made.

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

__far16

(32-bit only) Open 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 will automatically be converted to 16-bit integers, and 32-bit pointers will be converted to far16 pointers before calling a special thunking layer to transfer control to the 16-bit function.
Open 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 will generate 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 will cause 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 return value from the function will have its return value 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 will be 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 will be converted from a 32-bit integer to a 16-bit integer.  The err argument will be passed unchanged.  Upon returning, the far16 pointer (far pointer in the 16-bit environment) will be converted to a 32-bit pointer which describes the equivalent location in the 32-bit address space.

_Seg16

(32-bit only) Open Watcom C/C++ recognizes the _Seg16 keyword which has a similar but not identical function as the __far16 keyword described above.  This keyword is compatible with IBM C Set/2 and IBM VisualAge 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.

Note that _Seg16 is not interchangeable with __far16.

A pointer declared as,

     [type] * _Seg16 name;

defines an object that is 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 will take place.  The return value is a far16 pointer.

__pragma

Open 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 is a simplified example showing usage and syntax.
Example:

     #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 chapters entitled 16-bit:  Pragmas and 32-bit:  Pragmas for more information on pragmas.

__int8

Open Watcom C/C++ supports the __int8 keyword to define 8-bit integer data objects.
Example:

     static __int8 smallInt;

Also supported are signed and unsigned 8-bit integer constants.  The __int8 data type will be unsigned by default if the compiler is invoked with the -j switch.

__int16

Open Watcom C/C++ supports the __int16 keyword to define 16-bit integer data objects.
Example:

     static __int16 shortInt;

Also supported are signed and unsigned 16-bit integer constants.

__int32

Open Watcom C/C++ supports the __int32 keyword to define 32-bit integer data objects.
Example:

     static __int32 longInt;

Also supported are signed and unsigned 32-bit integer constants.

__int64

Open Watcom C/C++ supports the __int64 keyword to define 64-bit integer data objects.
Example:

     static __int64 bigInt;

Also supported are signed and unsigned 64-bit integer constants.

signed __int64

Use the "i64" suffix for a signed 64-bit integer constant.
Example:

     12345i64
     12345I64

unsigned __int64

Use the "ui64" suffix for an unsigned 64-bit integer constant.
Example:

     12345Ui64
     12345uI64

The run-time library supports formatting of __int64 items (see the description of the printf library function).

Example:

     #include <stdio.h>
     #include <limits.h>

     void main()
     {
         __int64 bigint;
         __int64 bigint2;

         bigint2 = 8I64 * (LONG_MAX + 1I64);
         for( bigint = 0;
              bigint <= bigint2;
              bigint += bigint2 / 16 ) {
             printf( "Hello world %Ld\n", bigint );
         }
     }

Restrictions

switch

An __int64 expression cannot be used in a switch statement.

bit fields

More than 32 bits in a 64-bit bitfield is not supported.

Based Pointers

• the based pointer is in the segment described by another object,
• the based pointer, used as a pointer to another object of the same type (as in a linked list), refers to the same segment,
• the based pointer is an offset to no particular segment, and must be combined explicitly with a segment value to produce a valid pointer.

Segment Constant Based Pointers and Objects

Segment Object Based Pointers

• a constant value (e.g., the segment containing screen memory),
• the result of the library function _bheapseg,
• the segment portion of another pointer value, by casting it to the type __segment.

Void Based Pointers

Self Based Pointers

The __declspec Keyword

__declspec( thread )

is used to define thread local storage (TLS).  TLS is the mechanism by which each thread in a multithreaded process allocates storage for thread-specific data.  In standard multithreaded programs, data is shared among all threads of a given process, whereas thread local storage is the mechanism for allocating per-thread data.
Example:

     __declspec(thread) static int tls_data = 0;

The following rules apply to the use of the thread attribute.

• The thread attribute can be used with data and objects only.
• You can specify the thread attribute only on data items with static storage duration.  This includes global data objects (both static and extern), local static objects, and static data members of classes.  Automatic data objects cannot be declared with the thread attribute.  The following example illustrates this error:
  
  Example:
  
       #define TLS __declspec( thread )
       void func1()
       {
           TLS int tls_data;            // Wrong!
       }
  
       int func2( TLS int tls_data )   // Wrong!
       {
           return tls_data;
       }
• The thread attribute must be used for both the declaration and the definition of a thread local object, whether the declaration and definition occur in the same file or separate files.  The following example illustrates this error:
  
  Example:
  
       #define TLS __declspec( thread )
       extern int tls_data;    // This generates an error, because the
       TLS    int tls_data;    // declaration and the definition differ.
• Classes cannot use the thread attribute.  However, you can instantiate class objects with the thread attribute, as long as the objects do not need to be constructed or destructed.  For example, the following code generates an error:
  
  Example:
  
       #define TLS __declspec( thread )
       TLS class A     // Wrong! Classes are not objects
       {
           // Code
       };
       A AObject;
  
  Because the declaration of objects that use the thread attribute is permitted, these two examples are semantically equivalent:
  
  Example:
  
       #define TLS __declspec( thread )
       TLS class B
       {
           // Code
       } BObject;      // Okay! BObject declared thread local.
  
       class C
       {
           // Code
       };
       TLS C CObject;  // Okay! CObject declared thread local.
• Standard C permits initialization of an object or variable with an expression involving a reference to itself, but only for objects of non-static extent.  Although C++ normally permits such dynamic initialization of an object with an expression involving a reference to itself, this type of initialization is not permitted with thread local objects.
  
  Example:
  
       #define TLS  __declspec( thread )
       TLS int tls_i = tls_i;            // C and C++ error
       int j = j;                         // Okay in C++; C error
       TLS int tls_k = sizeof( tls_k );  // Okay in C and C++
  
  Note that a sizeof expression that includes the object being initialized does not constitute a reference to itself and is allowed in C and C++.

__declspec( naked )

indicates to the code generator that no prologue or epilogue sequence is to be generated for a function.  Any statements other than "_asm" directives or auxiliary pragmas are not compiled.  _asm Essentially, the compiler will emit a "label" with the specified function name into the code.
Example:

     #include <stdio.h>

     int __declspec( naked ) foo( int x )
     {
         _asm {
     #if defined(__386__)
             inc eax
     #else
             inc ax
     #endif
             ret
         }
     }

     void main()
     {
         printf( "%d\n", foo( 1 ) );
     }

The following rules apply to the use of the naked attribute.

• The naked attribute cannot be used in a data declaration.  The following declaration would be flagged in error.
  
  Example:
  
       __declspec(naked) static int data_object = 0;

__declspec( noreturn )

indicates to the C/C++ compiler that function does not return.
Example:

     #include <stdio.h>

     int __declspec( noreturn ) foo( int x )
     {
         x = -x;
         exit( x );
     }

     void main()
     {
         foo( 0 );
     }

foo is defined to be a function that does not return.  For example, it call exit to return to the system.  In this case, Open Watcom C/C++ generates a "jmp" instruction instead of a "call" instruction to invoke foo.

The following rules apply to the use of the noreturn attribute.

• The noreturn attribute cannot be used in a data declaration.  The following declaration would be flagged in error.
  
  Example:
  
       __declspec(noreturn) static int data_object = 0;

__declspec( farss )

indicates to the C/C++ compiler that function suppose SS != DS.  Function uses far pointer to access automatic variables on the stack.  It is alternative to -zu compiler option and can be used per function.
Example:

     __declspec( farss ) char * foo( char *s );

The following rules apply to the use of the farss attribute.

• The farss attribute cannot be used in a data declaration.

__declspec( dllimport )

is used to declare functions, data and objects imported from a DLL.
Example:

     #define DLLImport __declspec(dllimport)

     DLLImport void dll_func();
     DLLImport int  dll_data;

Functions, data and objects are exported from a DLL by use of __declspec(dllexport), the __export keyword (for which __declspec(dllexport) is the replacement), or through linker "EXPORT" directives.

Note:  When calling functions imported from other modules, it is not strictly necessary to use the __declspec(dllimport) modifier to declare the functions.  This modifier however must always be used when importing data or objects to ensure correct behavior.

__declspec( dllexport )

is used to declare functions, data and objects exported from a DLL.  Declaring functions as dllexport eliminates the need for linker "EXPORT" directives.  The __declspec(dllexport) attribute is a replacement for the __export keyword.

__declspec( __pragma( "string" ) )

is used to declare functions which adhere to the conventions described by the pragma identified by "string".
Example:
     #include <stdio.h>

     #pragma aux my_stdcall "_*" \
             __parm __routine [] \
             __value __struct __struct __caller [] \
             __modify [__eax __ecx __edx];

     struct list {
         struct list *next;
         int         value;
         float       flt_value;
     };

     #define STDCALL __declspec( __pragma("my_stdcall") )

     STDCALL struct list foo( int x, char *y, double z );

     void main()
     {
         int a = 1;
         char *b = "Hello there";
         double c = 3.1415926;
         struct list t;

         t = foo( a, b, c );
         printf( "%d\n", t.value );
     }

     struct list foo( int x, char *y, double z )
     {
         struct list tmp;

         printf( "%s\n", y );
         tmp.next = NULL;
         tmp.value = x;
         tmp.flt_value = z;
         return( tmp );
     }

It is also possible to modify the calling convention of all methods of a class or just an individual method.

Example:

     #pragma aux my_thiscall "_*" \
             __parm __routine [__ecx] \
             __value __struct __struct __caller [] \
             __modify [__eax __ecx __edx];

     #define THISCALL __declspec( __pragma("my_thiscall") )

     class THISCALL IWatcom: public IUnknown{
         virtual int method_a( void ) = 0;
         virtual int method_b( void ) = 0;
         virtual int __cdecl method_c( void ) = 0;
     };

In this example, any calls generated to the virtual methods 'method_a' or 'method_b' will use the THISCALL ( my_thiscall ) calling convention.  Calls generated to 'method_c' will use the prefefined __cdecl calling convention.

It is also possible to forward define the class with modifiers for occasions where you do not want to change original source code.

Example:

     #pragma aux my_thiscall "_*" \
             __parm __routine [__ecx] \
             __value __struct __struct __caller [] \
             __modify [__eax __ecx __edx];

     #define THISCALL __declspec( __pragma("my_thiscall") )
     class THISCALL IWatcom;

     class IWatcom: public IUnknown{
         virtual int method_a( void ) = 0;
         virtual int method_b( void ) = 0;
         virtual int __cdecl method_c( void ) = 0;
     };

The __pragma modifier is supported by Open Watcom C++ only.

__declspec( __cdecl )

is used to declare functions which conform to the Microsoft compiler calling convention.

__declspec( __pascal )

is used to declare functions which conform to the OS/2 1.x and Windows 3.x calling convention.

__declspec( __fortran )

is used to declare functions which conform to the __fortran calling convention.
Example:

     #include <stdio.h>

     #define DLLFunc __declspec(dllimport __fortran)
     #define DLLData __declspec(dllimport)

     #ifdef __cplusplus
     extern "C" {
     #endif

     DLLFunc int  dll_func( int, int, int );
     DLLData int  dll_data;

     #ifdef __cplusplus
     };
     #endif

     void main()
     {
       printf( "%d %d\n", dll_func( 1,2,3 ), dll_data );
     }

__declspec( __stdcall )

is used to declare functions which conform to the 32-bit Win32 "standard" calling convention.
Example:

     #include <stdio.h>

     #define DLLFunc __declspec(dllimport __stdcall)
     #define DLLData __declspec(dllimport)

     DLLFunc int  dll_func( int, int, int );
     DLLData int  dll_data;

     void main()
     {
       printf( "%d %d\n", dll_func( 1,2,3 ), dll_data );
     }

__declspec( __syscall )

is used to declare functions which conform to the 32-bit OS/2 __syscall calling convention.

The Open Watcom Code Generator

Precompiled Headers

When to Precompile Header Files

• You always use a large body of code that changes infrequently.
• Your program comprises multiple modules, all of which use the same first include file and the same compilation options.   In this case, the first include file along with all the files that it includes can be precompiled into one precompiled header.

Creating and Using Precompiled Headers

The "-fh[q]" (Precompiled Header) Option

Consistency Rules for Precompiled Headers

• The current compiler options must match those specified when the precompiled header was created.
• The current working directory must match that specified when the precompiled header was created.
• The name of the first #include directive must match the one that was specified when the precompiled header was created.
• All macros defined prior to the first #include directive must have the same values as the macros defined when the precompiled header was created.  A sequence of #define directives need not occur in exactly the same order because there are no semantic order dependencies for #define directives.
• The value and order of include paths specified on the command line with -i options must match those specified when the precompiled header was created.
• The time stamps of all the header files (all files specified with #include directives) used to build the precompiled header must match those that existed when the precompiled header was created.

The Open Watcom C/C++ Libraries

Open Watcom C/C++ Library Directory Structure