Lattice_C_Compiler_CPM 86 Lattice C Compiler CPM

Lattice_C_Compiler_CPM-86 Lattice_C_Compiler_CPM-86

User Manual: Lattice_C_Compiler_CPM-86

Open the PDF directly: View PDF .
Page Count: 272

Download
Open PDF In Browser	View PDF

@

LATTICE,INC.
P. O. BOX 3072

·GLENÉLLYN·LLNOIS

60138·

3l2/858ñ9!5OU1NX9lO29l-2l9O

BULLETIN

TECHNICAL

TB841101.001
November
DATE:
1, 1984
PRODUCT:
8086/8088 C Compiler
Known
Bugs
SUBjECT:
in Version

2.14

and
Recently
bugs concerning the Version 2.14 libraries
three
Two
of these pertain
to the
startup modules have come to light.
and
the other concerns
sensing and use of the 8087 co-processor,
under MS-DOS 1 in
the use of the "malloc'° and "getmem" functions
P models of the compiler.
some
the s and
code was
In addition
oMtted
from the file " main.c".

1. Floating

Point

Bugs
8087

cjf the

(a) Sensing

The technique employed in the run-time
library to sense
of the 8087 co-processor
does not work in
the
presence
V2.14
because the 8087 is not initialized prior to the
need
You
Correcting
this problem is rather easy.
test.
add
a line of code to the
only
°'c.asm" provided with
and
compiler
reassemble this
the
the
to replace
current
"c.obj".

file

In

the

file

"c.asm"
CALL

just prior

to

you

Then reassemble
follows:

find

a

line:

JLAIN

this line,
DB

will

file

insert

ODBh,OE3h

"c.asm"

;

for

the fcülowing
FNINIT

each of the

"c.asm"

the appropriate
-- (i.e., \lc\s, to\lc\d,
\lc\p, or
same
directory
as
the
Copy

in
appropriate

--

Use

the

memory

mcdel.

command

1

line
instruction
models

memory

model

\lc\l)
"dos.mac"

as

subdirectory
that
is
for
the

so

it

@

LATTICE,1NC.
P. O. BOX 3Q72 ·GL£N

masm

ELLYN ·ILLNO1S

60138

W

·

312/858-7950·TWX9lO291-2

c;

into "c.obj".

to assemble "c.asm"

"DB"
a
here as
pseudo-op
is specified
instruction
than an "FFNIT' instruction since many
assemblers
rather
do
handle
not properly
floating point instructions.
Should your assembler be able to handle such instructions,
be
sure to use an "FNINIT" instruction rather than "FINIT"
Qr
else the assembler will generate a "WAIT" instruction
to the °'FINIT" and resulting
wait
programs will
prior
on machines not containing
endlessly
a co-processor.
The

(b)

Floating

Point

in the

D

arid

L

Mdels

In attempting
accidentally
the
correct

to repair an earlier bug concerning the 8087
To
broke its use in the D and L models.
problem
to patch
the
you can use "debug"
as
follows.
"lcmd.lib" and
"lcml.lib"
libraries
Each
(Underlined
portions
are what you must type.
line
be
entered with a carriage
must
return.)
we

(i)

Patching
>debuq
-eA97A
-eA9CC

lcmd.lib
lcmd.lib
10.12
78.76

-W
-SI
>

(ii)

Patching
Aebug
-eBB71
-eBBC7

lcml.lib
Icínl.Iíb
12.14

3D.3B

-W

-g
>

(C}

Bug

in

8087

Library

Under certain
Cxd55
function

Divide

circumstances
will return
2

Routine
the floating point
the incorrect
value

division

when

an

@

LATTICE, INC.
P. O. BOX 3072

·

GLEN ELLYN

·

LUNOIS

60138

·

is
present since this function
This bug
restore the DI register.
future release .
8087

(2) Ma1loc

and

Getmem

under

MS-DOS

312/858-7950

fails
will be

·

TWX

9lO29l-2l90

to
save and
repaired
in a

1

model
P
functions
The S and
allocation values
library memory
and
in
"getmem" will n"nccs

Major

Language

2.2.1
2.2.2
2.2.3
2.2.4
2.2.5
2.2.6
2.2.7
2.2.8

Pre-processor
Features
Arithmetic
objects
Derived Objects
Storage Classes
Scopc'
of Identifiers

Arbitíary

from the Standard
LimIt3tions

Control

Library

I/O

Level
Level
Level

and

Utility
3.3.1
3.3.2
3.3.3
3.3.4

2-5
2-6
2-6
2-B

2-8
2-9

l

Manual

Memory
Memory
Memory

Allocation
Allocation
Allocation

Functiom

System

I/O FUnction8 and Macros
Level
Level I I/O Functiom
Direct Console K/O Functions
program Exit Functiom
2

Functions
Memory

and

Macros

Utilities lqacro8

Character Type
String Utility

Utility

Macros

2-ll
2-ll

Functions
Functions

mmory Allocation
3
2

Reference

2-3

2-G

Flow
C

2-l
2-4

Features

Initializers
Expression Evaluation

Portable

3.2.1
3.2.2
3.2.3
3.2.4
J.3

Definition
of Mfferenc"."s

3.1.1
3.1.2
3.1.3
3.2

I-L

Comparison to the
3

CONTENTS

Introduction

Summary

2.2

OF

Functions

3-l
3-2
3-6
3-12
3-lS
3-15
3-40
3-49
3-56
3-59
3-59
3-63
3-64
3-83

Section

4

4.1

Compiler

4.2.1
4.2.2
4.2.3
4.2.4
4.2.5
4.2.6
4.2.7

4-l
4-3
4-7
4-8
4-9
4-13
4-15

l

2

Program Linking
Program Execution
Function Extract Utility
object Module Dissassembler

Data Elements
Names
External
Include File Processing
Operations and
Arithmetic
Floating
Point Operations
Fields
Bit
Register Variables

Compiler

4.3

4.3.1
4.3.2
4.3.3
4.3.4
4.4

Memory

4.4.1
4.4.2
4.4.3
4.4.4
4.4.5
4.4.6

4.5.1
4.5.2
4.5.3
4.5.4
4.5.4
5

Phase
Phase

Conversions

Error

Code

4-18
4-19
4-20
4-20
4-21
4-22
4-23
4-23

l

2

Processing
Generation

4-23
4-24
4-25
4-25

Models

Áddressing

Model
Choo8ing the Memory
Compiling the Memory
Models
Linking Program8
Code
Generation for Pointer Operations
The
-s option for Four-byte Pointers
Creating an Array Greater than 64K

Program Structure

object Code Conventiom
Linkage Conventions
Function Call Conventiom
Assembly Language Interface
Stack Overflow Detection

System Library

4-28
4-29
4-30
4-30
4-32
4-33
4-34
4-36
4-37
4-38
4-40
4-44

Implementation

I/O
Device I/O
Memory
Allocation
Program Entry/Exit
Special Functions

File

4-18

Processing

Run-time

4.5

5.1
5.2
5.3
5.4
5.5

Phase
Phase

Machine Dependencies

4.2

Section

Implementation

Instructions

Operating
4.1.1
4.1.2
4.1.3
4.1.4
4.1.5
4.1.6

Run-time

and

5-l
5-2
5-4
5-5
5-5

Lattice

8086/8088

SECTION

I:

C

Compiler

Introduction

Introduction

a
provides
This
document
functional
an
description
of
C compiler,
a portable
implementation
of the Lattice
compiler for
makes
Ca
programming language called
high
no
the
level
It
either programming fundamentals or how
attempt
to discuss
to
C
made
progEam
in
Extensive
reference
is
to the
itself.
The
C,
by
Proqramming Language,
text
Brian W. Kernighan
definitive
and
Englewood
New
(Prentice-Hall,
Dennis M. Ritchie
Cliffs,
Inc.,
C
1978).
This
description
of Lattice
incomplete
jersey,
is
and
Ritchie
without
the Kernighan
is called,
which
text, as
also provides an excellent
to the language.
tutorial introduction

it

l.l

Documentation

manual
is divided
into
five
sections.
First,
this
introduction.
Second, the
language accepted by the compiler,
which differs from the standard in only a few minor details,
is
The
described.
section
presents the portable
third
library
and
functions
in functional
groups with
calling sequences
and
examples.
Fourth,
the details of the compiler
run-time
execution
for
program
are presented
this implementation,
including
detailed
operating
instructions,
machine dependencies,
and
the operating
program structure.
system interfaces
Fifth,
in terms of the portable
functions
are described
library
(file
naming conventions,
provided with
etc.) and the special functions
implementation.
this
The

this document is intended to serve as a reference manual, each
topic
presented in full technical
is
is usually
detail as
Some
encountered.
reference to'sections
not yet encountered is
unavoidable,
but thege references
are gpecificalIy noted.
as

it

an overview
of the compiler,
to
get
read the first portion
of
each of the major suMections
in the implementation
description
summary
(Section
4),
language
the
beginning
the
at
of
the
language
at
definition (Section 2), and the function summaries
and
beginning
the
of
the
(Section
3),
the
library groups
introductions
in the system
to the subsections
interface
messages
information
(Section
S).
Error
in
are described
Appendix A and error reporting
procedures in Appendix B. Method8
C
of converting
for CP/M microcomputer
gygtems
programs written
a
in Appendix c.
of
are de3cribed
files Mipped with
C
D.
contained
in
Appendix
Lattice are

list

I-l

Lattice

8086/8088

C

Compiler

Language

Definition

2:

SECTION

Language

Definition

Lattice portable C compiler accepts a program written in the
programming
determines
language,
the elementary
actions
and
by
specified
that
eventually
translates
those
program,
actions
into machine language instructions.
Although the
final
is highly machine-dependent,
the actual
result of these processes
by
accepted
the compiler
language
is, for the most Dart,
independent
of any sYstem
This
or implementation
details.
by
C
section
the Lattice
compiler
presents the language defined
and
(K&R)
The
C
using
the Kernighan
Ritchie
Programming
text
a reference
point.
Since this language
conforms
Lanquaqe as
closely
to that described in the text, only the major differences
The
presented.
major features of the language are then
are
discussed,
not in any attempt at completeness, but simply for the
sake of showing them from a different perspective.
Finally, a
comparison with the Kernigban and Ritchie "C Reference Manual" is
made
how
more
precisely
implementation
the Lattice
to show
differs from the standard.
The
C

first

2.1

Summary

of Differences

There
that appear in a discussion
are two classes of differences
The
of an implementation
of a programmÍng language.
first class
is that of actual semantic differences;
that is, variations
which
The
second
to differ.
cause the meaning of language constructs
a reflection of the practical
is merely
class
limitations Eachto
which all programs
including
compilers
are subject.
--of
subsections
the following
presents the respective
details for
the Lattice implementation
of C.
2.1.1

Differences

from the Standard

Deviating
from a standard has its own peculiar
set of perils and
On
rewards.
the one hand,
the differences
create problems for
who
have
on
those
conformed to the standard in the past;
the
other,
they may make
easier for those who take advantage of
them
in the future.
of
the
differences
Most
listed below were
and
prompted by a desire to make the language both more portable
The
more
comprehensible.
majority
of
vast
not
programs will
these Potential
troublespots;
those that do will
in
encounter
be
improved by adjusting
most cases
to conform to them.
Here,
then, is a summary
of the major differences:

life

normally can be nested in the Lattice
compiler;
A compile-time
the standard,
option forces
they cannot.
mode.
compiler back to the standard non-nesting

o

Comments

o

Pre-processor
using arguments must be
macro substitutions
on
a single
specified
line; for example, when max(a,b) is
used,
the
invocation
text from max to the final closing
parenthesis
must be defined within a single input line.

in
the

2~1

Lattice

o

8086/8088

C

Compiler

Definition

Language

The

dollar sign (S) is permitted as an embedded
(i.e., not
first) character in identifiers.
string
constants refer
to the same
Identically written
that is, only one copy of the
static storage location;
by
the compiler.
This is in contrast
to
string is generated
the
statement in Kernighan and Ritchie
that all strings
are
when
written
distinct, even
identically.
Multiple
character
constants are accepted by this compiler;
a
in
the

o

o

the standard,
single character
only
enclosed in single
The
resulting
quotes is legal.
value may be @9,FE or long,
and
its exact value is machine-dependent.
o

and
union member
In processing
structure
declarations,
the
each
a separate
compiler
builds
names
of member
for
Thus, identical names may be used for
(or union).
structure
members
in different structures,
even though both the offset
and
the attributes may be different in each
declaration.
The
being referenced
determines
which
structure
specific
member
(and
name
therefore
which offset and
of
set
attributes) is meant. The typing sorules for structure member
refeEences are strictly enforced
that the patticular list
be determined.
names
can
of valid member
In other
words,
expression
in front of the . or -> operators
the
must be
identifiable by the compiler as a structure or pointer to a
of a definite type.
strueture

iist

o

conversion
(by assignment)
is
but
legal
Implicit pointer
generates a warning message;
occurs whenever any value
this
other
than a pointer of the same type or the constant
zero
be used
A cast operator
can
is assigned to a pointer.
to
A more
the warning.
eliminate
stringent
requirement
is
enforced
for
where
the
expression
to
initializers,
must
a pointer
evaluate to a pointer
of the same
initialize
type or to the constant zero; any other value is an error.

o

a
function
argument
of union appears as
If a structure
&,
without
being preceded by the address-of
the
operator
and
a
message
assumes
compiler
warning
that
generates
the
was
intended.
address of the aggregate

o

An

o

The

A

&;
operator
array name may be preceded by the address-of
the meaning,
however, is not that of a pointer
to the first
element
but of a pointer
to the array.
This construct
allows initialization
of pointers
to arrays.
an
following
constant
expression
may
statement
not contain the sizeof operator
completed in less than a single line.

more

differences
important
2-2

tif

conditional
and

must

and
systematic
detailed
explanation
of
the
is presented in Section 2.3,
but some of
the
above
items
deserve immediate clarification.

be

above
most

Lattice

8086/8088

C

Compiler

Language

Definition

and
names
a
intent behind making the structure
union member
class
of
for each structure
separate
is
twofold.
identifiers
names
of member
is greatly
increased,
First, nowthe flexibility need
since
the programmer
not worry about a possible conflict
of names between different structures.
Second, the requirement
that the compiler be able to determine the type of the structure
and
being referenced generally
improves the clarity of the code,
as
disallows
such questionable
constructs
The

int

*p;

© D

U

p->xyz

=

4;

Those
who
which is considered an error by this compiler.
grumble
accomplish
about
that one can.
the
this restriction should Cnote
by
equivalent
using a cast:
sequence in Lattice

((struct
The

parentheses

ABC

")p)->xyz

4;

are required

tightly than the cast.
prohibited
unconditionally
for what
clearly visible
nicely.
purpose

=

since the -> operator
more
binds
idea is not that such code should be
but that any such constructs
should be
they are;
the cast operator serves this

The

Exactly
intent
is present in the pointer
the same
conversion
By using
a cast
warning.
the programmer can eliminate
operator,
is then explicitly intentional, and
the warning;
the conversion
of sloppy coding.
not simply the result
In addition,
there is a
more
important
Although many C programs
reason for the warning.
make
be
the implicit assumption that pointers
may
of all types
types)" and
in
stored
retrieved
int variables (or other pointer makes
without
no
the language itself
of
guarantee
difficulty,
this. On word-addressed machines, in fact, such conversions will
the warning message
not always work properly;
provides a gentle
(and
non-fatal)
reminder of this fact.
oí union is used
the warning generated when a structure
function
without
the address-of
argument
is
operator
intendeCi to remind programmers that this compiler does not allow
be
such
an
a
passed
function
aggregate to
to
-- only pointers to
objects.

Finally,
as
a

Arbitrary Limitationg
Although the definition of
2.1.2

a programming language
is an idealized
by a
number
abstraction,
is constrained
any real implementation
Thé
of factors,
not the least of which is practicality.
Lattice
compiler
imposes the following
arbitrary restrictions on the
language
accepts:

it

o

maximum
size,
in bytes,
of any declared object is the
positive
largest
integer which can be represented as an int.
maximum
This implies,
for example, a
size of 32767 bytes for
The

2-3

Lattice

8086/8088

C

Compiler

Definition

Language

The
l6—bit int machines.
total size of all objects declared
with
the same
storage class is also 6ubject to the same

restriction.

o

The maximum
value of the constant expression defining
size of a single subscript
of an array is one less than
pQsitive
largest
int (32766 for a 16-bit int).

o

The

the
the

total size of the formal
limited to a maximum of 256

of

formal

parameters for any function
is
number
bytes.
Thus, the maximum
depends on their sizes.

parameters
size

maximum

o

The

o

Macros with
arguments.

o

The

maximum

string constant
arguments are limited to

level

of

a

of Finclude

file

is
a

256

bytes.

maximum

nesting

number

of

8

is 4.

limitations are impomd because of the way objects are
represented
internally by the compiler; our hope is that they are
reasonably
large enough
for most real programs.

These

2.2

Major

Language Features

material
presented in this section is meant
some
to clarify
of the
language feature8 which are not always fully defined
in
the Kernighan and Ritchie text.
These are features which depend
made
on"
implementation
decisions
in the design of the compiler
Those
of the language definition.
or on interpretations
itself,
features
which are specifically machine dependent
language
are
described
elsewhere in this manual.
The

2.2.1

Pre-processor

Lattice

The
commands

Features

compiler supports the full set of pre-processor
and
Most
described
in
Kernighan
Ritchie.
commands
implementations
perform the pre-processor
concurrently
and
analysis
with lexical
syntactic
of the source
file, because
an
additional
compilation
step can be avoided by this technique.
a
of the compiler
incorporate
Other versions
separate
prephase in order to reduce the size of the first
phases
processor
of the
compiler.
In either case,
the analysis
of
the precommands
C
is largely
independent of the compiler's
processor
language
analysis.
tdefine
Thus,
text substitutions
are not
commands,
any
performed
generally
for
of
the pre-processor
although
nesting
of macro definitions
is
possible
since
substituted
text is always re-scanned for new #define symbols.
C

exception

which
is processed
Dccurs for the #if command,
As noted in the
of differences,
sizeof cannot
and
must
apDear
the expression
áif expressions, These
a single
result
ftom a
line.
restrictions
and
desire
simple,
to keep #if expressions
because the prehas
no
information
about the size of declared
processor generally
An

differently.,
be
used
in
entirely on

2-4

list

8086/8088

Lattice

Compiler

C

Language

Definition

a symbol
One other
objects.
clarification should be noted:
defined
in a
expression which has not been
in an
appears
command,
a value
as
of zero had been
is interpreted
tdefine
and
usage
permits
seems
with #ifdef
consistent
This
specified.
Otherwise,
the use of symbols which may or may not be defined.
#if expressions support the full range of operations described in
Section 15 of Appendix A of Kernighan and Ritchie.

if

tifit

if

has
command,
the
2.1.1,
as
in Section
noted
contained
text must all be
that the macro invocation
on a single
input line.
Because the compiler uses a text buffer
may
occasionally
a particularly complex macro
fixed
size,
of
this
usually,
however,
cause a line buffer overflow condition;
when
in the
more
reference occurs
than one macro
error
occurs
and
be
can
circumvented by placing the macros
same
source line,
on different
lines.
Circular
definitions such as

The

Qdefine

limitation

tdefine
tdefine

A
B

B
A

by
be detected
used,
the compiler if either A or B is ever
will
of C,
more
as will
Like many other implementations
subtle loops.
compiler supports nested macro
the Lattice
definitions, so that
if the line

tdefine
is followed

later
tdefine

XYZ
by
XYZ

definition

the new
forgotten.

In other

#undef

12

43

takes
words,

effect, but the
after encountering

old

one

is

not

XYZ

To completely
undefine
definition (12) is restored.
each
The
rule is that
additional
tundef is required.
tundef
before
the
must be matched by a corresponding

the former
XYZ,

an

tdefine
symbol is
2.2.2

truly "forgotten".

Arithmetic

objects

objects are supported
Six types
of arithmetic
with
pointers,
these objectb
compiler;
along
entities which can be manipulated in a C program.
short or 8hort int
char
unsigned or unMgned
long or long int

float

double

or long

by

the Lattice
the
represent
The
types are:

int

float

2-5

Lattice

8086/8088

C

Compiler

Note that in this implementation,
a separate
data type.

Definition

Language
unsigned

is not

a

modifier

but

size of integers
natural
for the target machine (the machine
which code is being generated) is indicated
for
by a plain
int
type specifier;
short
type will be identical
to either
or
this
on
depending
long,
machine.
the architecture
of the target
Although
the size of all these objects is technically
machinedependent, the Lattice
compiler assumes
the target machine has an
and
B-bit,
that the fundamental
I6-bit, or 32-bit architecture
quantity
is an B-bit byte.
storage
Only in connection with bit
become
important.
fields does this assumption ever
The

compiler
follows the standard pattern
for conversions
between
the various arithmetic
"usual
arithmetic
the so-called
types,
The
conversions"
described in the Kernighan and Ritchie
text.
exception
only
byte-oriented
to this occurs in connection with
machines,
where expansion of char to int uiay be avoided
both
and
in an
operacds
expression are char,
the target
machine
and
logical
operations.
supports byte-mode arithmetic
The

if

2.2.3

Derived

objects

leading
Lattice C compiler supports the standard extensions
various
kinds
objects,
including
pointers,
of derived
to
and
and
functions,
unions.
Declarations
of
structures
arrays,
be
may
these
although
complex,
types
not all
arbitrarily
declarations
in a legal object.
result
of
For example,
arrays
The
functions
returning
aggregates are
or functions
illegal.
and
compiler checks for these kinds of declarations
also verifies
that structures
or unions do not contain instances of themselves.
objects which are declared as arrays cannot have an array
length
of zero, unless they are formal parameters or are declared extern
assumed
2.2.4).
(see Section
to be the same
All pointe,rs are with
On
one
exception.
size
usually,
that of a plain int
--machines,
pointers which point to objects
word-addressed
which
as
can
to require twice
appear on any byte boundary are assumed
much
storage as pointers
to objects which must be word-aligned.
The

that the size of aggregates (arrays
by
alignment
requirements.
affected
For
Note

structures)
example, the

and

may

be

array

{
struct
short

i;
xtl0];

char c;
}

will
be

occupy
aligned on

2.2.4

Storage

40

bytes

an

even

on machines which require
byte address.

short

objects

to

Classes

Declared objects are assigned by the compiler to storage
offsets
which are
bases.
storage
to one of several different
relative
The
base
on
assigned storage
depends
the explicit storage
class
2-6

Lattice
specified
declaration,
External

8086/8088
in
as

C

Language Definiticm

Compiler

the declaration,
follows:

or

on

the

context

of

the

object is classified as external
the extern
and
in its declaration,
the
is present
keyword
object is not later defined in the source file (that
is not declared outside the body of any
is,
is
Storage
function
without the extern keyword).
for external
items because they are
not allocated
and
be
assumed
must
to exist in some other file,
a
during
included
the linking
process that builds
set of object modules into a load module.

if

An

it

Static

is classified as static
the static
object
is
is present in its declaration
keyword
or
without an
declared outside the body of any function
is
Storage
specifier.
explicit storage class items
of
in the data section
allocated
for
static
object
module;
the
are
all such locations
expression
unless an initializer
initialized to zero declaration
2.2.6).
is included in the
(see Section
declared
outside
the body of any
Static
items
function
without the static keyword are visible in
defined.
other files,
that is, they are externally
as
Note that string constants are allocated
static
and
items,
are treated as unnamed
static arrays of
char.

Auto

object is classified as auto
the auto keyword
is declared
is present in its declaration,
or
inside
without an explicit
the body of any function
storage class specifier (it is illegal to declare an
object
the body of a function).
auto outside
for auto items using
Storage is presumably allocated
a
during execution of the function
stack mechanism
in'which
they are defined.

Formal

An

if

An

if

An

if it

if it

is a formal
is classified as formal
of the functions
in the source
to one
18 presumably
allocated
formal
for
Storage
items when a function
call is made during execution
of the program.
object
parameter

if it

file.

no
assumption
the
phase of the compiler makes
Note that
declarator.
tbe validity
of the reqister
class
about
storage
but storage is
Items which are declared register
are so flagged,
against either the auto or the formal
allocated
for them anyway
The
implementation
of register
base.
storage
is machinedependent and may not be supported in some cases.

first

option is used, the implicit
Note also that
the x compile-time
storage class for items declared outside the body of any function
changes from static to extern.
This allows a single header file
used
When
for all external
data definitions.
the main
to be

if

2-7

Lattice

8086/8088

C

Compiler

Language

Definition

and
so
is compiled,
the x option is not used,
the
function
various objects are defined and made externally
visible; when the
functions
the x option
other
causes the same
are compiled
as
declarations
defined
references
to be interpreted
to objects
elsewhere.

2.2.5

Scope

of

Identifiers

almost exactly to the scope rules
Lattice compiler conforms
in Appendix A of the Kernighan and, Ritchie
discussed
text
(pp.
The
205-206).
in connection with structure
only exception arises
member
and
names,
2.1)
union
where (as noted in Section
the
names
for each structcre
compiler
keeps separate lists of member
this means that additional
classes of nm-conflicting
or union;
Two
identifiers occur for the various structures and unions.
points are worth clarifying.
additional
The

when
identifiers are declared at the beginning of a
internal
(other than
the first
block
to a function
statement
any
following
the fanction
name), storage for
block immediately
base
against the current
of auto
auto items declared is allocated
When
the next available
the statement block terminates,
storage.
preceding
those
offset
is
reset to its value
auto storage
be
may
reused by later
Thus,
that
declarations.
stQrage space
and
Rather than generate explicit allocate
local declarations.
operations,
the compiler
dealLcxmte
to
uses this mechanism
the function;
the
compute the totsl auto storage required by
is called.
allocated
whenever the function
resulting storage isfunctions
more
storage
With this scheme,
will allocate possibly
needed
be
inner
(in the event that
those
statement
than will
need
run-time
dynamic
but the
for
blocks
are not executed),
allocation witjÁn the function is avoided.

First,

an
is
Second, when
identifier with a previous declaration
redefined
locally in a statement block with the extern storage
in
the
the previous definition is superseded
class
specifier,
with
fashion but the compiler also verifies compatibility
normal
done
This is
any
preceding
extern definitions of the same name.
in accordance with the principle expressr"d in the text, namely
which refer to the same
that
all functions in a given program
Within a source
external
identifier refer to the same object.
declarations
the compiler also verifies that all external
file,
The
in tjLE!e.
point is that in this particular case
agree
-an
where a local block redefines
extern
identifier uponas termination
-- the
does
of
disappear
declaration
not
effectively
item
external
since the compiler now has an additional
the block,
declarations.
for which
must verify equivalent

it

2.2.6

IrÜtialiµers

objects
which
Section
2.2.4)
begins
program
used
to define

2-8

in
are of the static storage class (as defined
the
are guaranteed to contain binary zeros when
expression
is
execution,
unless an initializer
The
Lattice
compiler
a different initial
value.

8086/8088

Lattice

C

Compiler

Language

Definition

in
expressions described
the full range of initializer
supports
and
the initialization
of
Ritchie,
but
Kernighan
restricts
be
An arithmetic
object may
somewhat.
pointers
initialized with
that evaluates
constant which,
an expression
to an arithmetic
is converted to that of the target
type,
not of the appropriate
object.

if

used
is more
expression
to initialize a pointer
restricted:
evaluate
to the int constant zero or to a pointer
OE exactly
a pointer
yielding
the same type as the
include
pointer
being initialized.
This pointer expression can
object,
declared static or extern
the address
of a previously
a
but
plus or minus an int constant,
cannot incorporate
cast
conversion)
because pointer conversions
(type
operator,
are not
a cast
evaluated
operator
at compile time (exception:
can be
used
a
variable"
This
but not on
name).
on an makes
int constant
impossible
to an
to initialize a pointer
restriction
an
is allowed to be used on
unless
the & operator
array
array
&
is
name,
name
without
the preceding
because the array
automatically
converted to a pointer
element of the
to the
as
noted
in Section
2.1,
the Lattice
Accordingly,
array.
name
so
that
the & operator on an
compiler
accepts
array
declarations
such as
The

it must
expression

it

it

first

int
can

be

being
must

a[5]0

("pa) [5]

=

&a;

a pointer
to a structure
(or union) is
Note that
used
name
the structure
to generate an address
preceded by the & operator.

made.

initialized,
be

if

be
may
complex objects
(arrays and structures)
initialized
expressions,
bracketed,
comma-separated lists of initializer
an
with
arithmetic
each expression corresponding
to
or pointer
A closing
be
used to
element
of
the aggregate.
brace can
A
and
see
Appendix
of
Kernighan
Ritchie
terminate
the
early;
be
may
under
this
for
examples.
Unions
not
initialized
implementation,
containing
although the first part of a structure
be
a
may
the expression
ends before
union
initialized
A character
reaching the union.
array may be initialized with a
need
be
enclosed in braces; this is the
not
string constant which
braces around the
only
exception
of
to the rule requiring
initializers for an aggregate.
More
by

list

if

list

list

expressions
for auto objects can only be applied
Initializer
and
arithmetic
types (not to aggregates),
or pointer
entirely equivalent to assignment statements.
simple
2.2.7

Expression

to
are

Evaluation

by
of
the standard operators
the Lattice
are supported
compiler,
in the standard order of precedence (see p. 49
of
and
Kernighan
Ritchie). Expressions are evaluated using. an
parsing
technique
which
reduces
complex
precedence
operator
'to a sequence of unary and
expressions
binary
operations
involving
Operations
involving
only
at most two operands.

All

2-9

Lattice

8086/8088

Compiler

C

Language

Definition

operands
(including
constant
are
floating point constants)
by
evaluated
the compiler immediately,
but no special effort
is
re-order
operands in order to group constants.
Thus,
to
expressions
such as
made

C

-

'A'

+

'a'

must be parenthesized
constant part:
C

+

('a' -

so

that

the compiler

can

evaluate

the

'A')

least
at
If
intermediate

one
operand in an operation
is not constant,
the
by
a
expression
is represented
result
temporary
known
The
location,
as a temporary.
storage
temporary is then
an
into" the larger expression and becomes
"plugged
operand of
binary or unary operation;
another
the process continues
until
has
The
the entire expression
been evaluated.
lifetimes of
and
temporaries
assignment
locations
to storage
their
are
internal
determined
by a subroutine
to the first phase of the
which
recognizes
generated
temporaries
compiler,
identically
recomputation
within a straight-line block of code and eliminates
common
sub-expressions
equivalent
results.
of
Thus,
are
and
For
evaluated
example,
in the
recognized
only
once.
statement

a[i+l]

b{i+l);
i+l will

=

used
be evaluated
the expression
for
once and
operations.
Expressions which produce a result
subscripting
used
and
as
is never
which have no side effects, such

both
that

i+j;
are discarded

by

this

same

subroutine.

analysis
of code examined by
the temporary
Within
the block
subroutine,
operations
which produce a temporary result
are noted
be
remembered
and
may
so
operations
equivalent
that
later
Two
conditions
(other than function
as
noted above.
deleted,
have
undetermined side
effects)
cause the
calls, which may
and
no
longer check for
the
subroutine
to discard an operation
(I)
either
operation
of
equivalent
its operands
later:
(2)
or
appears directly as a result of a subsequent operation;
a
through
a
operation
defines an indirect (i.e.,
subsequent
one
as
of the
for
the same type of object
pointer)
result
based
The
on
the
is
original operands.
latter condition
compiler's
assumption that pointers
to
are always used to refer
an
so
for example,
the correct
that,
type of target object,
made
using an int pointer
only objects of type
assignment is
int
be
changed.
Only when the programmer
indulges
in tjLEe
can
using a pointer
punning
to inspect an object as
were a
is this assumption invalid, and
is hard to
different -- type
-sub-expression
detection
a case where the common
conceive ofprob"1em
will
Such
practice.
with this somewhat
dubious
cause a

if

if

if

if it
it

2-ID

8086/8088

Lattice

inspections
modules in

any

C

Language

Compiler

are generally
case.

better

left

to

assembly

Definition
language

detection,
which
the exception of this common sub-expression
previous,
equivalent
a
operation
with
an
one,
replace
they
expressions
ate evaluated in strict left-to-right order as
of course,
where that is prevented by
except,
are encountered,
make
operator precedence or parentheses.
It is best not to since any
the
about the order of evaluation,
assumptions,
however,
phase
code
the sequence
free to re-order
is generally
generation
The
most
exceptions
important
operations.
of many
are the
the
'for which The
logical OR (||) and logical AND (&&) operators, evaluation.
guarantees left-to-right
language
definition
code
on
expression
effects
generation
phase may have other
assumptions about pointer
some
favorable
evaluation;
usually,
though these can be shut off by a compileassignments are made,
Check
section of this manual
for
the implementation
time option.
with
may

full details.
2.2.8

Control

Flow

and
the Lat"tice
a rich
offers
set of statement flow constructs,
Some
minor
the full complement of them.
compiler
supports
points
of clarification are noted here.
First of all, the
contain (I) at least
compiler does verify that switch statements
and
(3) not more
one
(2) no duplicate
case values;
case entry;
the first phase of the
In addition,
than one "default"
entry.
involving
recognizes certain
compiler
statement flow constructs
and
may discard
certain
portions
of code
constant
test values,
(Even
ultimately
discarded are fully
those portions
accordingly.
eliminated.)
analyzed,
lexically and syntactically, before being
only the code for
statement has a constant test value,
If an
is
retained;
clause (the then or else portion)
the appropriate
while,
do, and for statements with. zero test values are entirely
discarded.
C

if

makes
a special
phase generally
code generation
effort to
flow.
In particular,
generate
sequences for control
efficient
is kept to a minimum
of branch instructions
the size and number
and
by
switch
analysis
of the flow within a function,
extensive
of
to determine the most efficient
statements
are analyzed
Check
the
machine language constructs.
possible
several
section of this manual
for the details regarding
impleñentation
this particular code generator.
The

2.3

Comparison

to the Kernighan

&

Ritchie

"C

Reference

Manual"

language
precise
-most
definition of A the C programming
of the Kernighan and Ritchie
generally
available
is in Appendix
C.
section
This
Manual.
Reference
text, whichin isthe entitled
of
saíne
order defined in the text, a series
presents,
amendments
to that 'manual;
this C commentary
or annotations
language
of the Lattice
explicitly states any deviations
Because
described.
implementation
from the features
this
and
Ritchie
implementation
is
close
to the Kernighan
very
The

2-ll

8086/8088

Lattice
standard,
sections
can

Compiler

Language

of the sections appjY exactly as
Any
section
riot be commented
upon.
to be fully valid for the language
compiler.
many

will
assumed

be

Lattice
CRM

C

C

2.1

Definition

written;
these
not listed here
accepted by the

Colnment6

Lattice

allows comments
that is,.each
to be nested,
be matched by a corresponding
before
the
*/
This feature makes
out"
easy to "comment
The
c
of code which themselves contain comments.
large sections
in
compile-time
option
forces the compiler to process comments
non-nesting mode.
the standard,
The

compiler

encountered must
/"
comment
terminates.

2.4.3

Character

it

constant8

extensions
constants ate provided.
to character
First, more
be enclosed
may
in single quotes;
the result
than one character
be
and
may
int or long, depending on the number of characters,
Second,
the first character
its value is machine-dependent.
following
the next one
the backslash in an escape sequence is x,
as a hexadecimal
value.
Thus,
or two digits are interpreted
Two

if

'\xf9'
generates
CRM

a

character

with

the value

0XF9.

2.5 Strings

identically wíitten string
Lattice compiler recognizes
(Note that
constants and oñiY generates one copy of the string.
used
strings
to initialize char arrays -- not char * -- are not
generated,
because they are really just shorthand for a
actually
The
same
\X
of single-character
constants.)
comma-separated
be
can
employed in strings, where
convention
described above
more
useful.
is generally
The

list

CRM
See

it

2.6 Hardware characteristics
the

implementation

section

of

this

manual

for

hardware

characteristics.
CRt'l

7.1 primary

expressions

Lattice and compiler always enforces the rules for the use of
unions
for
the simple reason
that
cannot
structures
names
otherwise
determine
which
is
intended.
list of member
a
Recall
separate
from Section 2.1 that the compiler maintains
for each type of structure
Therefore,
of members
or union.
list primary
be
must
expression preceding the . or -> operator
the
immediately recognizable
as a structure
to a structure
or pointer
of a specific type.
The

it

2-12

Lattice
CRM

8086/8088

C

Compiler

Language

Definition

7.2 Unary operators

to an
requirement
that the & operator can only be applied
is relaxed slightly to allow application
to an array" name
lvalue
(wtÜch is not considered an lvalue).
Note that the meaning of
is a pointer
such a construct
to the array itself, which is'quite
The
to the first element of the array.
different from a pointer
difference
between a pointer
to an array and to an array's
first
when
in an
is used
the pointer
is only
important
element
expression
with an int offset, because the offset must be sealed
by
the pointer
(multiplied)
the size of the object to which
points.
In this case the target object size is the size of the
the
rather than the size of a single element,
whole
array,
pointer
points to the array as a whole.
The

if

CRPf

7.6 Relational

operators

the right-hand
of different types are compared,
pointers
operand;
operand
is converted
to the type of the left-hand
and
one
of the integral
types causes a
comparison
of a pointer
Both of these are
conversion
type.
of the integer to the pointer
value and
operations
of questionable
are certainly machinedependent.

When

CRM

7.7 Equality

The

same

CRM

8.1 Storage

operators

conversions

noted above are applied.

class-specifiers

omitted from
the storage class-specifier,
This is
function,
is taken to be extern.
in fact (as the
not plainly inaccurate;
11.2),
the presence or absence of extern
whether an object is being defined or
is critical
to determining
As
in Section 2.2.4 of this document,
noted
referenced.
in some
then the declared object either exists
extern is ptesent,
same
no
storage
other
file;
file or is defined later in the declared
object
is being
specifier
is present,
then the
class
and
the static
defined
will be visible in other files.
specifier is present, Thethe object is also defined but is not made
externally
only exception to these rules occurs for
visible.
statement body
functions,
where
is the presence of a defining
is being defined.
that determines whether the function
The

text

states

if

that

a declaration
outside a
somewhat
misleading,
oUt
in CRM
text points

if

if

if
If

it

Lattice
compiler
outside
declarations
Declarations
option.
are not affected.

The

CRM
The

8.5 Structure

and

be
for
forced to assume
extern
all
by means
of the x compile
time
function
which explicitly specify static or extern
can

a

union declarations

members
quite
compiler treats the names of structure
and
The
names
of members
from Kernighan and Ritchie.
not conflict with each other or with the identifiers used

Lattice

differently
do
tags

2-13

Lattice

8086/8088

Compiler

C

Language

DefinitÁon

and
ordinary
variables.
Both structure
union tags are in the
so
class of names,
that the same tag cannot be used for both
and
A
a
is
a
union.
of members
separate
structure
name
may
maintained
for each structure;
thus, a member
not appear
used
be
in
twice in a particular structure,
but the same name may
within
several different structures
the same scope.

for

same

list

CRM

8.7

Type

Although

name8

a

specifier,

structure

union

or

refer to
it
definitions cannot
must

structure
the sequence

{

(struct
is not permitted,

struct

int

may
appear
known
an already
be wade
inside a

high,

}

*)

low;

};

low;

in

a
type name
that
tag,
is,
Thus,
type name.

x

but
HL

O O 0

HL

(struct

{

int
")

high,

x

is acceptable.
CRM

l0.l

function

External

definitions

declared
noted
in the text,
formal parameters
float are
as double;
interpreted
actually
similarly, formals áeclared char
as
Lattice
compiler
co.nsistency,
the
For
or short ate read
int.
a function
declared
applies
the same rules to functions:
to
return
float is assumed to return double, and char or short
functions
to return int.
AS

CRM

10.2 External

data

definitions

data
Lattice compiler applies a simple isrule to external actual
the
declarations:
the keyword extern
present,
storage
will be allocated elsewhere, and the declaration as anis
a reference
Otherwise,
simply
is interpreted
to
actual
which allocates
storage (unless the x option
definition
has
CRM
comments
on
8.1).
been used; see the
The

if

it.

CRM

12.3 Condi-tional

compilation

2.2.1
this
of
noted
in Section
may
expression
following
not contain
#if
must
appear on a single input line.
As

Crm

it

document,
the sizeof

the constant
and
operator,

12.4 Line control

need
Although the filename for #line is denoted as identifier,
The
of C identifiers.
not conform
to the characteristics
supplied;
the
compiler
takes whatever string of characters
is
requirement
for the filename is
only
that
cannot
lexical
contain any white space.

it

it

2-14

Lattice
CRM

8086/8088

14.1 Structures

C

Compiler
and

Language

Definition

unions

escape from typing rules described in the text is explicitly
by
the Lattice
compiler.
In a reference
not allowed
to a
the name on the right must be a member
structure
or union member,
of
the aggregate named or pointed to by the expression
of the
This implementation,
however, does not attempt to enforce
left.
any
on
reference to union members,
such as requiring
restrictions
member
before allowing
a value
to be assigned to a particular
to be examined via that member.
The

it

Future versions of the compiler may support structure
assignment,
the
but
value of other operations
passing
(such as
aggregates
them
seems
from functions)
questionable.
directly to or returning

2~15

Lattice

8086/8088

Section
Portable

3:

Library

C

portable

Compiler

Library

Functions

Functions

In order to provide real portability, a C programming environment
ñOit
way
only a wellmust provide
-- inbuta machine-independent
-The
a library of useful
as well.
defined
language
functions
C compiler
provided
with
Lattice
portable
the
attempts
to
library
Álthough not all of the features
of
this requirement.
by
these
functions
can be implemented on every system supported
be able to
must
provide
basic
the compiler,
the
systems
all
and
allocation,
functions
of memory
ch.3racter
file input/output,
manipulation;
otherwise,
string
the compiler itself could not be
An
important
benefit
implemented.
side
of presenting
the
functions
from a machine-independent
viewpoint
is that
helps
the programmer think of them as such.

fulfill

it

descriptions
in this
presented
to the function
referring
remember
seccion,
that the compiler assumes
that a function will
an
otherwise.
is explicitly declared
return
int value unless
be
Any
must
any
function
which
other kind of value
returns
usage
in advance of its first
as
declared
that kind of function
in the same file.

when

it

3.1

Memory

Allocation

Functions

standard library provides memory
allocation
capabilities at
The
higher level functions
several
different levels.
call the
interfaces
but provide easier
lower levels to perform the work,
The
amount
in exchange for the extra overhead.
actual
of memory
on the size
available
is system-dependent and usually depends
of
made
most
the program.
available'
for
In
systems the memory
by
used
dynamic allocation
is the same memorjj'
these functions
for
and
the run-time
stack (used
for function
auto variables).
calls
number
On
a
default
these systems
of bytes is reserved
for
the
and
is used by
the remainder of the memory
the memory
stack,
functions.
In order to allow programs to adjust the
allocation
amount
of memory
reserved for the stack (and
thus
the amount
available
dynamic allocation),
the main
for
program usually
the default
stack
size;
supports a special =n option to override
Check
a program may
altermatively,
define the size internally.
manual
The
implementation
for details.
the
section of the
user
is.
cautioned
that o,n. many systems there ,i,s, no, check aqainst
the
and
o_f,
overrunninq
destroying
portions
stack
its allotted size
the memory
pooI.
The

All" of the memory
functions
allocation
return
of type char *, but is guaranteed to be properly
any
object.

a

pointer
aligned

which is
to store

3-I

Lattice
3.1.1

8086/8088
Level

3

C

Memory

Compiler

portable

Library

Functions

Allocation

functions
described in this section provide a ÚNIX-compatible
memory-allocation
of memory
obtained may br
facility. The blocks
released
in any order,
but it is an error to release
somethinq
by
thcsc>
Recause
one
of these functions.
not obtained
calling
keep
use
overhead
locations
of allocation
functions
track
to
The
sizes,
the free function does not require a size auíument.
however, decrease the efficiency
with which thesr·
overhead does,
use
memory.
functions
the available
If many small allocmtinn':
memory
the available
are requested,
will be more efficié"ntly
2
used
the level
functions
instead.
are
utilized
The

if

3~ 2

—

Lattice

8086/8088

C

Compiler

Portable

Library

Functions

name

malloc

UNIX-compatible

--

memory

allocation

SYNOPSIS
p

=

malloc(nbytes);

char *p;
unsigned

block
nbytes;

number

pointer
of bytes

requested

DESCRIPTION

Allocates

in a way that is compatible with
block of memory
primary difference
between malloc and getmem
is
a structure
that
the former allocates
at the front of each
can
This
block.
result
in very inefficient use of memory
when
making many small allocation
requests.
UNIX.

a

The

returns
p

=
=

null
pointerif

not enough
space available
to block of nbytes of memory

otherwise

CAUTIONS

Return value must be checked for NULL.
declared
char " and a cast operator
as
pointer
to some other kind of object,
be

The
used

in:

function
should
a
defining

if

char *mal1oc();

int "pi;
0 D O
pi = (int

*)malloc(N);

3-3

8086/8088

Lattice

C

Compiler

Portable

Library

Functions

NAME

calloc

allocate

--

memory

and

clear

SYNOPSIS
p

=

calloc(ne1tf

char *p;
unsigned
unsigned

eltsiz);
block

ne.lt;

eltsiz;

pointer
of elements
element size in bytes
number

and
clears (sets to all zeros) a block of memory.
Allocates
by
The
the product of the two
size of the block is specified
convenient
this calling technique is obviously
parameters;
Typically,
the second argument is a
for allocating arrays.
sizeof expression.
RETURNS
p

=
=

NULL

jr

pcñnter

not enough
space available
otherwise
to block of memory

CAUTIONS
The
function
should
Return value must be checked for NULL.
be declared
a pointer
defining
to
char * and a cast used
as
some
in:
other kind of object,

if

"calloc();
struct buffer "pb;

char

D U e
pb
=

3-4

(struct

buffer

")calloc(4, sizeof(struct buffer));

Lattice

8086/8088

C

Compiler

Library

Portable

Functions

name

free

UNIX-compatible

--

release

memory

function

SYNOPSIS

ret

free(cp);

=

return code
block pointer

int ret;

char *cp;
DESCRIPTION

by
allocated
that was previously
Releases a block of memory
The
is
pointer should be char " and
malloc
or calloc.
checked for validity;
that is, verified to be an element of
the memory
pool.
RETURNS

ret

0

=
=

-I

if
if

successful
invalid
block

pointer

cautions
Remember

to cast

the pointer

back

to char

"u

as

in:

char "malloc();

int "pi;
* * 0
= (int

pi

P P

if

*

*) malloc(N);

(free((char

*)pi)

!=

D)

{

...

error

...

}

3-5

P

Lattice
3.1.2

8086/8088
Level

2

C

Memory

Compiler

portable

Library

Functions

AlloCation

The
arid
functions
described in this section provide an efficient
memory
3
convenient
allocation
Like
the level
capability.
and
functions,
allocation
de-allocation
requests may be made in
and
by
any
order,
is an error to free memory
not obtained
The
means
of one of these functions.
must retain both the
caller
pointer
and the size of the block foF use when
is
freed;
length may lead to wasted memory
failure to providecan the correct
when
functions
length
(the
detect an incorrect
is
too
An additional
large,
but not when
is too small).
convenience
sizmem
by
be
used
function,
is provided
the
which can
to
determine the total amount
of memory
available.

it

it

it

it

2 functions
level
maintain a linked
of the blocks
of
released by calls to rlsmem,
called the free space list.
by
memory
Initially,
this list is null, and getmem acquires
As
sbrk.
blocks
are
calling the level l memory allocator
when
a
released by the program,
the free space
list isis created;
block
adjacent
freed,
is
to one already on the
combined with any adjacent blocks.
Thus, the size of the largest
be smaller
may
than the total amount
free
available
of
block
due
memory,
to breakage.
The

memory

list

list

3-6

it

Lattice

8086/8088

Compiler

C

Portable

Library

Functions

NAME

getml

getmem,

--

get

a

memory

block

SYNOPSIS
p
p

=
=

getmem(nbytes);
getml (lnbytes);

char "p;
unsigned nbytes;
long lnbytes;

block

pointer
of bytes requested
long number
of bytes requested

number

DESCRIPTION

Gets a block of memory
from the free memory
pool.
the
size
is not
pool
is empty
or a block of the requested
memory
more
is obtained via the level I function
available,
sbrk.

If

RETURNS
p

=
=

null

if

pointer

not enough
to memory

space available
block otherwise

CAUTIONS

Return value must be checked for NULL.
declared char * and a cast used
some
as
in:
other kind of object,

if

be

The

defining

function
should
a pointer
to

char *getmem();
struct xyz "px;
O 0 O
px
= (struct

xyz ")getmem(sizeof(struct

XYZ));

3-7

Lattice

8086/8088

Compiler

C

Portable

Library

Functions

name

rlsmem,

rlsml

--

release

a

memory

block

synopsis
ret
ret

=
=

rlsmem(cp, nbytes);
rlsml(cp,
lnbytes);

int ret;

char *cp;
unsigned nbytes;
long lnbytes;

return code
block pointer
size of block
size of block

freed

to

be

as

long

integer

description
the memory
block by placing
the new block is adjacent to
are combined.

Releases

list.

If

they

it
a

on

a

block

free
block
the

on

list,

returns
ret

=
=

0

-I

if successful
block is not
if supplied
getml
or if it overlaps
list

one

obtained by getmem
of the blocks on

or
the

cautions
value should
Return
size is not supplied,

3-8

checked for
the block may

be

etror.
not be

If

freed

the correct
proDer}y.

Lattice

8086/8088

C

Compiler

Portable

Lib'rary

Functions

NAME

allmem,

bldmem

--

allocate

level

2 memory

pool

SYNOPSIS

ret
ret

=
=

allmem();
bldmem(n);

int ret;
int n;

code

return

maximum

of I kilobyte

number

blocks

DESCRIPTION
The

bldmem
function
uses the level
up
allocate
to n I kilobyte
blocks of
then all availabTe memory
is allocated.
The

alhnem function

Subsequent

getmem

merely
and

getml

calls bldmem
calls memory
will

pool.
this memory
All of the
a call to getmem
following
calls
rstmem
the
function

described

can

below.

1
function
iíiemory.

with

n

If

sbrk
is

to
0,

n

set to

CL

make
be

allocations
from
by
getmem
allocated
by
a
freed
call to

RETURNS

ret

=
=

-I

0

if first sbrk fails
if successful

CAUTIONS

Should
program.

be

called

only

once

during

the

lifetime

of

the

3-9

Lattice

8086/8088

Compiler

C

portable

Library

Functions

NAME
sizmem

get

--

memory

pool size

SYNOPSIS

bytes

=

sizmem();
number

long bytes;

of bytes

DESCRIPTION

of unallocated
bytes in the memory
pool
and
getmem
getml.
Note that
getml
by
dynamically
expand the pool
calling sbrk whenever bya
the value returned
Therefore,
request cannot be honored.
sizmem
how
much
memory
indicate
is
does not necessarily
used
available.
actually
afterbe calling a.llmem, however,
If
pool size will
returned.
the actual memory
Returns
used

the

by

number

getmern

and

RETURNS

bytes

=

(long)

number

of bytes

in

mermry

pool

CAUTIONS

Note that this function
declared long before

it

3-ID

returns
is used.

a

long integer,

and

must

be

Lattice

8086/8088

C

Compiler

Portable

Library

Functions

NAME
rstmem

--

reset

memory

pool

SYNOPSIS

rstmem();
DESCRIPTION

the ,l,ey.e,l. ? memory
pool to its initial
state.
All
by
and
made
allocated
getml
to getmem
after
calls
by
was
allmem
called is released
allocated
rstmem; memory
before
allmem was called
is not affected.
This
function
makes
make
number
a certain
possible to
of initial sbrk,
and
getmem,
then to initialize a memory
or getml calls,
pool
Any
made
by calling allmem.
allocations
after the call to
by
allmem are freed
rstmem, but the preceding sbrk or getmem
calls are not affected.
Resets

memory

it

CAUTIONS

This

any
function
cannot be used
files have been opened
the immediately preceding allmem call for access using
because these
functions
any of the leve} 2 I/O functions,
opened
buffers.
Files shÓuld be
to allocate
use getmem
allrnem
before the
call to avoid this problem.

after

if

3-ll

Lattice
3.1.3

8086/8088
Level

l

C

Memory

Compiler

portable

Library

Functions

Allocation

memory
defined
level
of
two functions
at the lowest
allocation
which perform the basic
operations
are primitives
needed
they are used
to implement a more sophisticated
facility;
by
the level 2 functions
for that purpose.
sbrk treats the total
amount
as
a single
available
of memory
block, from which portions
a
creating
of a specific size may be allocated
at the low end,
new
block of smaller size.
rbrk merely resets the block back to
The
"break point" mentioned here shouZd
not
its original size.
be
used
confused with the breakpoint
in debugging;
concerjt
this
term simply refers to the address of the low end of the block
of
by sbrk.
memory
manipulated
The

3-12

8086/8088

Lattice

Compiler

C

Portable

Library

Functions

NAME

sbrk,

lsbrk

set

--

memory

break point

SYNOPSIS
p
p

=
=

sbrk(nbytes);
lsbrk(lnbytes);

char *p;
unsigned nbytes;
long In bytes;

points

address
to low allocated
of bytes to be allocated
long number
of bytes to be allocated

number

DESCRIPTION

Allocates
possible.

block

of memory
of the requested
size,
UNIX
memory
functions
form the basic
allocator.
first time one of them is called,
will
Then
allocate
memory.
the largest available
block of high
end
low
the requested number
of bytes is subtracted
from the
of the block for use by the caller.
a

if

These
The

it

returns
p
p

=
=
=

cannot
fulfilled
-l if request
request cannot
fulfilled
if
pointer
to low address of block
0

be
be

(sbrk only)
(lsbrk only)
successful

if

CAUTIONS

consistency
with the UNIX function,
sbrk returns
the request,
although the rest
cannot
of
satisfy
NULL.
memory
allocators
Both functions
return
should
*
and
used
a cast
declared
a
char
defining
pointer
some
other kind of object.
For

-l theif

it

if

be

to

3-13

Lattice

8086/8088

C

Compiler

portable

Library

Functions

NAME

rbrk

--

reset

memory

break point

SYNOPSIS

rbrk();
DESCRIPTION

the
This
space block.
Resets

point.

memory

break point to
returns

effectively

its
all

original

memory

to

startingthe

free

CAUTIONS

Like
are

3-14

if

any
cannot be used
rstmem above, this function
files
and
being accessed using the .l.eye.l. E I/O functions.

open

Lattice
3.2

8086/8088
I/O

and

System

C

Compiler

Portable

Library

Functions

Functions

standard library provides 1,/0 functions
at several different
levels,
with single character 2ÉÉ and put functions and formatted
and
l/O at the highest levels,
direct
byte stream T/Q
functions
The
the lowest levels.
major system dependency
at
arises
in
where
some
connection
with text files,
certain
systems perform
accommodate
translations
the
particular
to
text
file
usc"d
representation
in the local
environment.
Although
the
translation
is generally
transparent
at the higher levels,
I/O at
the lowest levels,
binary data,
I/O involving
must
particularly
be
Check
cjf the translation.
aware
the implementation
section of
manual
for the details
appropriate
to a particular
sYstem.
this
The

Three general classes of I/O functions
are provided.
First, the
2
functions
level
define a buffered text file
interface
which
macros
implements
as
the single character
I/O functions
rather
Second,
than function calls.
the level l functions define a byte
stream-oriented
interface,
primarily
useful for manipulation
file
most
of disk files,
of the same functions
though
are applicable
to devices (such as the user's console) as well.
FinaZZy, since
most
one
common
of the
is with the user's console,
I/O interfaces
T/O
a
special set of functions
allows single character
directly
as
well as formatted and string I/O.
to the user's terminal,
discussed in this section are concerned with
system functions
Additional
system functions
program exit.
are described in the
implementation
section of the manual.
The

3.2.1

Level

2

I/O Functions

and

Macros

a buffered
These functions
provide
a
interface
using
special
by
manipulated internally
structure,
the functions,
to which a
pointer
called the file pointer
is defined.
This structure
is
most
defined
in the standard I/O header file (called stdio.h
on
be
must
(by
means
which
systems)
generally
included
of a #include
.l.eye,l.
2 features
statement)
in the source file where
are being
The
used
spécíÉy"the
used.
pointer
is
to
file be
file upon which
Some
operations
performed.
functions
require a file
are to
such
as
pointer,

FILE "fp;
to be explicitly included in the calling sequence; others imply a
specific
In particular, the file pointers
stdin
file pointer.
and
by
and
stdout
the use of several
functions
are implied
used
gYgtems
these
that on most
macros;
are sci commonly
files
they
automatically
before the main
function
of a
are opened
Other file pointers must be declared
program begins execution.
by
the programmer and initialized by calls to the topen function.
The

functions
with
text
are designed to work primarily
uses
usual C convention for line termination
a single
end
character,
the newline
indicate
a
the
to
of
line.
(\n), environments use a
many
Unfortunately,
operating
multiple

files.

level

,2.

The

3-15

Lattice

8086/8088

C

Compiler

Portable

Library

Functions

character
sequence -- usually carriage
return/line feed, but
occdsionally
In order to allow all
even more exotic delimiters.
C
the Lattice
programs to work with text files in the same way,
functions
the standard newline convention
support
but may
-mode
on
a text
depending
the system
so
translation
-- perform
end-of-line
that
sequences
will conformand to local conventions.
This
but may
transparent
translation is usually beneficial
Normally,
cause problems when working with binary
files.
all
the level 2 functions
in the
are opened
files accessed through
mode,
may
translated
but
the
override
programmer
this
text, by ordefining
mode
location
the external

int

_fmode

=

0X8000;

in one
of im functions
in the program
(this statement mustbe
the body of the function
in order
appear outside
to
itself
The
fmode
an
considered
external
value
is
at
definition).
1
when
the"
open
passed to
the level
function
is
or creat
file
—
opened
mode;
opened.
in the text
(jx8000,
zero, the file is
mode.
is opened
the
in the binary,
Note
or untranslated
fmodé
and
is defined as above, the stdin,
that
stdout,
stderr
áZsO
be
opened
in the
files opened for the main function will fmode can be
binary mode.
this is undesirable,
initialized
and
Gx8000
before"specific
with
then set to
fopen calls are
zero
made;
this way,
in
in different
different files may be opened manual
modes.
Check
the implementatior:
section of this
for more
modes.
information
about the file access

file
if

If

if

If

actual I/O operations
are petformed by the level 2 functions
through calls to the level l L/O functions
described in the next
The
section.
normal moU of buffering,
designed
to supDort
sequential
operations,
performs read and write functions
in 512byte blocks.
The

Normally

the

,l.ey.e_l.

2
functions
acquire buffers
via the level
the file is on a device
other
than 3
disk.
setbuf function
allows a private
buffer
assumes
This function
attached.
that the buffer
is
to be
the
size,
which
is defined via the BUFSIZ
in
standard
constant
stdio.h.
If formodesome reason operating the level 2 I/O functionsbe
can
in the buffered
is not desirable,
the setnbf function
is done automatically
called.
This
for non-disk files
or
setbuf is called with a NULL buffer pointer.

memory

2

allocator unless
Alternatively, the

if

cjf
some
below,
In the descriptions
the function
calls are
The
implemented as macros;
actually
these are noted explicitly.
be aware
the
should
cf
is
the distinction
reason
programmer
and
may,
because most macros
involve the conditional
operator
more
conditions,
under certain
evaluate an argument expression
This can cause unexpected results
than once.
that expression
involves side effects,
such as increment or decrement
operators
or function
calls.

if

3-16

Lattice

8086/8088

Compiler

C

Library

Portable

Functions

NAME
a

buffered

fopen(name,

mode);

fopen

--

open

file

SYNOPSIS

fp

=

FILE "fp;
char "name;
char "mode;

file
file

pointer

for

specified

name
mode

file

access

DESCRIPTION
mode
a
for buffered access; the translated
is the
file
mode
as
default
but may be overridden
described
in the
The
introduction
NULL-terminated
to this section.
string
which
specifies
the filename must conform
to local
file
The
as a
naming conventions.
access mode is also specified
and
be one
may
of
the
following:
string,

Opens

to
to
to
r+ to
w+ to
a+ to
r

w
a

read
write

a

append

update
create
append

a

file
file
a file
a file
(read and write)
a file
for update
to and update a file
to

The

mode
character must be specified
in lower case.
option adds to the end of an existing
or creates
file,
the w option discards any data in the file,
one;
On most systems,
no more
exists.
already
than 16
and
(including
stdin,
stdout,
stderr,
those are
for main) can be opened
using fopen.

if

When
may
modes,

file

end

The
a

a
new

iffilesit

opened

file is opened for update, both reading and writing
performed on the file pointer.
In order to switch
an
fseek or rewind must be executed.
Opening the
append
be
forces all data to
written
to
to the current
of file, regardless
of previous seeks.
a
be

RETURNS

"fp

=
=

NULL

file

if

error
pointer
for

specified

file

if

successful

CAUTIONS
The

return code must be checked for NULL;
the error
return
be generated
mode
an
was
invalid
specified
the
or
be
created, or too many files
file was not found, could not
were already open.
may

if

if

3-17

Lattice

8086/8088

C

Compiler

Portable

í,ibrary

Functions

NAME

freopen

--

reopen

a

buffered

file

SYNOPSIS

fpr

* freopen(name,

*fpr;
*name;

FILE
char
char
FILE

*mode;

*fp;

mode,

fp);

file
file

pointer
name
mode

access
current

file

re-opening

after
pointer

DESCRIPTION
a buffered
file; that is, attaches a new file to a
used
previously
pointer.
This function
is useful
for
file
which must open several files,
but only one at a
programs
The
up
time; this avoids using
file pointers unnecessarily.
previous
automatically
closed
before
the file
file is The
and
mode
name
is reused.
pointer
arguments are the same
as those for fopen.
Reopens

RETURNS

fpr

=
=

NULL

fp'if

error
ifsuccessful

CAUTIONS
TPie

return code should be checked for
defined for fopen may occur.

NULL;

the

3-18
t*

same

errors

Lattice

8086/8088

C

Compiler

Portable

Library

Functions

NAME

fclose

--

close

a

buffered

file

SYNOPSIS

ret

=

fclose(fp);

int ret;

return code
fike pointer

FILE "fp;

for

file

to

be

closed

DESCRIPTION

Completes
the processing of a file and releases all related
resources.
If the file was being written, any data which
has
and
accumulated in the buffer is written
to the file,
the level I close function
is called for the associated
file
The
descriptor.
buffer associated with the file block
is
freed.
is automatically
fclose
called for all open
files
when
a program calls
the exit function
3.2.4)
(see Section
is good programming
but
or when the main program returns,
As
practice
the last buffer
is
to close files explicitly.
an
data may be lost
not written
until fclose is called,
output file is not properly closed.

it

if

RETURNS

ret

=
=

—I
0

if error
if successful

3-19

Lattice

8986/8088

C

Compiler

Portable

Library

Functions

NAME

getchar

gete,

--

get character

from

file

SYNOPSIS
c
c

=
=

int

FILE

getc(fp);
getchar();
c;

"fp;

next

file

input character
pointer

or

EOF

DESCRIPTION

Gets the next character
the case of getchar).
end—of-file
or error.

from the indicated
value EOF (-I)

The

file

(stdin,
is returned

in
on

RETURNS
c

=
=

character
eoe

if end-of-file

or error

CAUTIONS

These are implemented

3-20

as

macros,

so

beware

of side effects.

8086/8088

Lattice

Compiler

C

portable

Library

Functions

NAME

putc,

putchar

--

i'"hírí('"t("r

put-

to flit"'

SYNOPSIS

r
r

=
=

fp);
putc(c,
putchar(c);
SÉ'ñt,
ass character
charaí"ter to Y)("? output
file pointer

int r;
char c;
FILE "fp;

same

nr prr()r

í""odé

DESCRIPTION

t s t h e character
case tjf putchar) .
file or error.
E'u

The

to the indicated
va 1(1€" EOF

(-I)

(stdout,
filerett.irned
is

on

i n r Pip
ond-nS-

RETURNS
r

=
=

character
sent
eof
error or

if

if successful
end-of-file

CAUTIONS

These are implemented

as

macros,

so

beware

of sick' rffec"ts.

3-21

8086/8088

Lattice

Compiler

C

Portable

Library

Functions

NAME

fgetc,

fputc

--

get/put

a

character

SYNOPSIS

r
r

G

=
=

fgetc(fp);
fputc(c,
fp);

int r;

return character or
character
to be sent
file pointer

char c;
FILE *fp;

code

(fputc)

DESCRIPTION
a
(fgetc)
(fputc)
These fjmctions
single
get
or put
Since they are functions,
character
to the indicated
file.
recommended
use
for
rather
they
than
the
are often
and
macros
corresponding
in two
putc)
(getc
of
types
made
(2)
many
and/or
calls are
the
situations: (I)
used
is concerned about the amount
of memory
in
programmer
The
is the usual one:
tradeoff
the macr,o expansions.
the
more
quickly
because
macro executes
saves a function
is
call; the function requires less memory since its code
present in the program only once.

if

if

it

RETURNS
r

3-22

=
=

if

character
eof
error

if

successful
(c, for
or end-of-file

fputc)

Lattice

8086/8088

C

Compiler

Portable

Library

Functions

NAME

ungetc

push character

--

back

on

input

file

SYNOPSIS

r

=

ungetc(c,

fp);

int r;

return character
character
to be
file pointer

char c;
FILE "fp;

or

pushed

code
back

DESCRIPTION
back

Pushes

character
obtained
supplied

The
a character
to the specified
input
file.
most
supplied
must be the character
recently
by
a getc
in which case fp should be
(or getchar,
as stdin)
invocation.

RETURNS

r

=
=

character
successful
EOF
previous character

if

if

does not match

3-23

Lattice

8086/8088

C

Compiler

Portable

Library

Functions

from/to

a

NAME

fread,

fwrite --

read/write

blocks

of data

file

SYNOPSIS

naet
nact

=

fread(p,

=

fwrite(p,

s, n, fp);
s, n, fp);

int
int
int

actual number
of blocks read or written
pointer
to first block of data
size of each block,
in bytes
number
of blocks to be read or written
file pointer

nact;
*p;
s;
n;
FILE *fp;
char

DESCRIPTION
of
These functions
(fwrite)
blocks
r ead (fread) or write
Each
data írom or to the specified
block is of size s
file.
by t£?s;
d and
blocks
f rom
at A—
are stored contiguously
statt
n specif les the number
that location.
of blocks (of size s)
—
that are to be read
or wrntten.
RETURNS
rjgo

t

=

actual
may

be

number

of blocks ( c) f size S) read or written;
less than n
error or end-cf-tile occerte"í

if

CAUTIONS
be checked to
va lúe
mu s t
verify thatand t h e correct
The
of blocks was processed.
feof macros
ferror
i
be used
the return
value
to determine the cause
than n.

Return
number

ca n

less

3-24

if

s

Lattice

8086/8088

C

Compiler

Portable

Library

Functions

name

fgets

gets,

--

get

a

string

SYNOPSIS
p

=

p

=

gets(s);
fgets(s,

n, fp);
returned string pointer
buffer for input string
number
of bytes in baffler
file pointer

char "p;
chat 's;
int n;
FILE *fp;
DESCRIPTION

The
input
Gets an
string
from a file.
specified
file
(stdin,
in the case of gets) is read until a newline
is
have
been
encountered
characters
read
(fgets
only)or n-l
Then, gets
replaces the newline with a NULL
whi)e
byte,
fgets passes the newline through with a NULL byte appended.
RETURNS
p

=
=

NULL
s

if

if

end
of
successful

file

or error

CAUTIONS

For gets,
buffer must

there
is no length
large enough
to

be

parameter,

accommodate

so

the

the

input

string.

3-25

Lattice

8086/8088

C

Compiler

Portable

Library

Functions

NAME

fputs

puts,

--

put

a

string

SYNOPSIS

r
r

=
=

puts(s);
fputs(s,

int r;

char *s;
FILE "fp;

fp);
return
output

file

code

string
pointer

pointer

DESCRIPTION

Puts an output string
Characters
to a file.
to the specified
(stdout,
are written
file
NULL
puts)
byte is encountered.
until a
not written, but puts appends a newline.
RETURNS

r

3-26

=

EOF

if end-of-file

or error

The

from the"string
in the case of
NULL
byte
is

Lattice

8086/8088

C

Compiler

Portable

Library

Functions

NAME

scanf,

fscanf,

sscanf

--

perform

formatted

input

conversions

SYNOPSIS
n
n
n

=
=
=

scanf(cs,
fscanf(fp,
sscanf(ss,

...ptrs...);
cs, ...ptrs...);
cs, ...ptrs...);

int n;
FILE *fp;
char *ss;
char "cs;
---- ...ptrs...;

of input items matched, or EOF
pointer
(fscanf only)
input string
(sscanf only)
format control
string
pointers
for return of input values
number

file

DESCRIPTION

These functions
perform formatted input
obtained
from three types of files:
L)
2)
3)

conversions

on

text

the stdin
file (scanf);
the specified
file (fmanf);
string
the specified
(sscanf).

string
contains
control
format
specifiers
and/or
characters
to be matched from the input;
the
of pointer
specify where the results
arguments
of the conversions
are
to go. Format specifiers
are of the form

The

list

B("]{rÍ](llX
where

I)
2)
3)
4)

"
means
the optional
that the conversion
is to be
performed, but the result
value not returned;
number
,n. is a decimal
the optional
a maximum
specifying
field width;
the optiona!
I (e,l.) is used to indicate
a ,lgng int
or
""'
lorg float (í.e., double) result
is desired;
X
one
is
of the format
indicators
type
from the
following
list:
d
o
x
h
c
s

f

integer
-- decimal
integer
-- octal
integer
-- hexadecimal
integer
-- short
character
-- single
string
-- character
number
-- floating point

format
in lower
white
type must be specified
case.
in the control
characters
ignored;
space
string are
characters
other
than format specifiers
to
are expected
The
match the next non-white space
in the input.
characters
The

3-27

Lattice

8086/8088

C

Compiler

portable

Library

Functions

scanned
input
is
through white space to loccíté
the next
input
item in all cases except the c specifier, where the
input
is
character
next
returned without this initial
scan.
See
and
a
more
Ritchie
the Kernighan
text for
detailed
explanation
of the formatted
input functions.
RETURNS
n

=

number

which
single
=

E.O.F.

if

of input items successfully
matched,
i.e.,
valid
text data was found;
this includes
items in the control
string
character
end-of-file or error is encountered during

for

all
scan

CAUTIONS

of the
input values must be pointers
to the result
Make
match
locations.
up
sure that the format specifiets
with
properly
the result
locations.
the assignment
If
remember
suppression
feature
(") is used,
a
that
pointer
must not be supplied for that specifier.

All

3-28

Lattice

8086/8088

C

Compiler

Portable

Library

Functions

NAME

printf, fprintf,

sprintf --

formatted

genetate

output

SYNOPSIS

printf(cs, ..-arqs...);
fprintf(fp, cs, ...args.-.);
n = sprintf(ds, cs,
...args...);
number
n;
of characters
(spíintf only)
int
FILE *fp;
file pointer (fprintf)
char "ds;
destination
string pointer
{sprintf)
char *cs;
string
format control
be
formatted
list of arguments to
---- ...args...;
DESCRIPTION
Tbese
send

I)
2)
3)

functions
the resulting

perform formatted
text to:

the stdout file (printf);
the specified
file (fprintf);
the specified
output string

output

and

conversions

or

(sprintf).

contains ordinary characters,
which are
string
control
and
sent without modification
to the appropriate
output,
format specifiers
of the form

The

%[-][m][.p)[l]X
where

l)
2)
3)

4)
5)

optional

the

-

indicates

justified (rightm justified
the optional
field is
minimum
field width;
the optional
: £ field is
number
decimal
specifying

is to be
the field
is the default);
number
a decimal
specifying

left
a

a
the character
. followed
a
the precision"of
floating
number
of characters
to be
or the maximum
by

image
point
printed
from a string;
item to be
the optional
l
(el) indicates
that
the
formatted is io6g; and
X
is one
of the
format
indicators
from the
type
Íollowing

list:

d
u
x
o
s
c

f
e
g

----------

decimal signed integer
decimal unsigned integer
hexadecimal integer
octal integer
character
string
single character
fixed decimal floating point
exponential
floating point
use
e or f format,
whichever

is shorter
3-29

8086/8088

Lattice

C

Compiler

Portable

Library

Functions

Characters
in lower case.
format type must be specified
which ate not part
of a format
string
the control
be
a *
may
output;
are sent to the appropriate
specifier
and
by
See
the Kernighan
using
the sequence
sent
mote
detailed
explanation
a
Ritchie
for
of
the
text
formatted
output functions.

The

in

u.

RETURNS
n

=

number

including

placed in ds
of characters
the NULL byte terminator

(sprintf

only),

not

CAUTIONS
no check of the size
of the output string
For sprintf,
area
be
must
so
large enough
is made,
to contain the resulting
must
up
specifiers
format
the
match
image.
In all cases,
properly
with the supplied values for formatting.

it

3-30

Lattice

portable

Compiler

C

8086/8088

Library

Functions

NAME

fseek

seek

- --

to

a

new

f i Ip posit iíjn

SYNOPSIS

ret

=

fseek (fp,

int ret;

return

;
code

pointer
desired file
of fset mode

file

FILE "fp;
long pos;

int

mode)

pos,

mode;

position

DESCRIPTION
s
in the specified
t o a new position
(Section 3.2.2)
description
function
lseek
of the of fset mode argument.

Seek

le.
for the

fi

S ee
the
meaninq

RETURNS

re t

=
=

0

-l

if
if

successful
error

CAUTIONS
1f

m,ode

f i íe9"
incorrect.

! ingis

be

specified,
accessed

the file position
i n the translated

established
mode

may

f or
be

4

3-31

8086/8088

Lattice

C

Compiler

Portable

Library

Functions

NAME

ftell --

return

current

file

position

SYNOPSIS

pos

=

fte"1l(fp);
current
file
file pointer

long pos;
FILE *fp;

position

DESCRIPTION
o f
that is,
Returns the currient file position,
the number
f rom
the beginning of the file to the byte at which
bytes
the next read or write operation
will transfer data.
RETURNS
pos

=

current

file

position

(long)

CAUTIONS

f i Le p'j'íitio!1
returned takes account M
the buffering
used ci"! the ti2c: , -sr the file position
retutmed is a logic"a]
f i t?
positzot: rather than the actual position.
Note tha li
mode
Le x t
may
transZation
le posit.ion
cause an incorrect
fi
!:u be
tetut"neci, since the nurnbeí
of characters
in the buf fer
i s not r)ec¿!ssari iy the number
that will he actmally
read or
written because of the translation.
'I'híú

3- 32

Lattice

8086/8088

C

Portable

Compiler

Functions

Library

NAME

feof

ferror,

check

--

error/end

if

of

file

SYNOPSIS

ret
ret

=
=

feof(fp);
ferror(fp);

int ret;

return

file

FILE *fp;

code

pointer

DESCRIPTION
These

condition

a non-zero
macros generate
is true for the specified

value

file.

if

the

indicated

RETURNS

ret

=
=

if

error
non-zero
not
zero

if

(ferror)

or

end

of

file

(feof)

3-33

Lattice

8086/8088

C

Compiler

Portable

Library

Functions

NAME

clrerr --

'clear

error

flag

for

file

SYNOPSIS

clrerr(fp);
FILE "fp;

file

pointer

DESCRIPTION

Clears

the error

flag

for

the specified
file.
EOE returns
for
is called.

flag will remain set, forcing
the file, until this function

3-34

Once

set,
functions

the
on

Lattice

8086/8088

C

Compiler

Portable

Library

Functions

NAME

fileno --

file

return

number

for

file

pointer

SYNOPSIS

fn

=

fileno(fp);

int fn;
FILE *fp;

file
file

number

associated

with

pointer

file

pointer

DESCRIPTION

Returns the
the specified

file number, used
file pointer.

for

the level

l

I/O

calls,

for

RETURNS

fn

=

file

number

(file

desc;riptor)

for

level

,1

calls

CAUTIONS

Implemented

as

a

macro.

U+ 3 5

Lattice

8086/8088

C

Compiler

Portable

Library

Functions

NAME

rewind

--

rewind

a

file

SYNOPSIS

rewind(fp);
FILE

file

"fp;

pointer

DESCRIPTION

the file
Resets
beginning of the

position

file.

CAUTIONS

Implemented

3-36

as

a

macro.

of the

specified

file

to

the

8086/80R9

C

fflush --

flush

Lattice

Compiler

Portable

Library

Functions

NAME

output

buffer

for

file

SYNOPSIS

fflush(fp);
file

FILE *fp;

pointer

DESCRIPTION

Flushes
forces

it

the output buffer
to be written.

of the specified

file,

that

is,

CAUTIONS

This macro
for writing

must be used only
or appending.

on

files

which have

been

opened

3_37

Lattice

8086/8088

C

Compiler

Library

portable

Functions

NAME

setbuf

--

change

buffer

for

level

2

file

I/O

SYNOPSIS

setbuf(fd,buf);
FILE "fd;
char "buf;
DESCRIPTION
whose
This
function
attaches a private
buffer to the file
The
descriptor
is fd.
length of the buffer
is assumed
to be
same
as
the
bufsiz,
which is defaulted
to the constant
BUFSIZ
in stdio.h..

If

same

the
as

buffer
setnbf.

pointer

is

NULL,

then

this

function

is

the

CAUTIONS
must
buf
bufsiz.

—

3-38

be

large

enough

to handle

the data specified

in

Lattice

80'86/8088

C

Compiler

Portable

Library

Functions

NAME

setnbf

--

set

file

unbuffered

SYNOPSIS

setnbf(fp);
FILE *fp;

file

pointer

DESCRIPTION
Changes

mode
the buffering
for the specified
file pointer
mode
from the default
SH-byte block mode to the unbuffered
used
for devices (including
the user's console).
In this
mode,
read and write oDerations are performed using single
characters.
CAUTIONS

Although

the unbuffered mode may be used without
difficulty
more
files, sothe standard buffering mode isbe generally
used
this function
should only
for
those
efficient,
known
be
devices.
to
"files" which are definitely
on

3-39

8086/8088

Lattice

Level

3.2.2

I

C

Compiler

Portable

Library

Functions

I/O Functions

functions
provide a basic,
low-level
I/O interface
which
a file
allows
to be viewed as a stream of
randomly
addressable
Operations are performed on the file using the functions
bytes.
by
described
in this section;
a
the file is specified
file number
such as
or file t, 0
s==t, <0
string to compare
second string
to compare
result
>0

if
first

*t;

if

if

s

0
0
0

match
if strings
string
less than
first string
it first
greater than
if

string
second string

second

CAUTIONS

The
result
of
the comparison
characters
are considered signed,
is greater than 127.

3-68

depend

may

if

any

of the

on

whether
characters

Lattice

8086/8088

C

Compiler

Library

Portable

Functions

NAME

stcu

d

--

convert

unsigned

integer

to decimal

string

*

SYNOPSIS

length

=

stcu

d(out,

int length;
char *out;
unsigned in;
int outlen;

in,

outlen);

output string
output string
input value
sizeof(out)

length

(excluding

NULL)

DESCRIPTION

into a string of decimal digits
Converts an unsigned integer
terminated
Leading zeros are not copied
with a NULL byte.
the input value is zero, only a
to the output string, and
single 0 character
is produced.

if

RETURNS

length

=

number

including

placed in output
of characters
the NULL terminator

string,

not

CAUTIONS

If

the output string
is too small
rightmost
digits are returned.

for

the

result,

only

the

3-69

Lattice

8086/8088

Compiler

C

Library

Portable

Functions

NAME

gtci

d

convert

--

Mgned integer

to decimal

string

SYNOPSIS

length

8tci

=

in,

d(out,

outlen);

output string length
output 8tring
input value
sizeof(out)

int length;
"out;
int in;
int outlen;

char

(excluding

NULL)

DESCRIPTION
an
into
integer
Converts
terminated
with a NULL byte.
is preceded
the output string
copied to the output string.

a
by

string
of decimal
digits
the integer is negative,
a
Leading zeros are not

If

-.

RETURNS

length

=

of characters
placed in output
including
the NULL terminator

number

string,

not

CAUTIONS

the
If
returned
returned.

3-70

output
length

string
may

be

is too small
zero,
or a

for

the result,
may
string

partial

the
be

Lattice

8086/8088

C

Compiler

Portable

Library

Functiom

NAME

stchi --

convert

hexadecimal

string

to integer

SYNOPSIS

count

=

stchi(p,

r);

int count;
char "p;

number

input
result

int *r;

of characters

scanned

string

integer

DESCRIPTION

Converts a hexadecimal string into an integer.
when
a non-hex character
terminates
only
is
Valid hex characters
are D-9, A-F, and a-f.

The
procms
encountered.

RETURNS

count

=

"

if

0
number

input string dom not begin with
scanned
of charactem

a

hex

digit

CAUTIONS
No

check for

overflow

is

made

during

the processing.

3

'//

Lattice

8086/8088

C

Compiler

portable

Library

Functions

MAME

stcdi

--

convert

decimal

string

to integer

SYNOPSIS

count

=

stcd

—

i(p, r);

int count;
*p;
int "r;

number

input
result

char

of characters

string

scanned

integer

DESCRIPTION
a
decimal
Converts
string into an integer.
when
terminates
a
non-decimal
character
is
decimal characters
are 0-9. The first character

The

found.
may

be

+

process
Valid
or -.

RETURNS

count

"

"

if

0

digit
number

input

string

of character8

does not begin with
scanned

CAUTIONS
No

check

for

overflow

is

T

3—72

made

during

proceming.

a

decimal

8086/8088

Lattice

C

Compiler

Portable

Library

Functions

NAME

stpblk

--

skip

blanks

(white

space)

SYNOPSIS
q

=

stpblk(p);
updated string

char *q;
char "p;

initial

string

pointer
pointer

past

white

DESCRIPTION

Advances the string
pointer
(space, tab, or newline).

space

characters

RETURNS
q

=

updated

string

pointer

(advanced past white

space)

CAUTIONS
Must

be

declared

char *,

as

the stp

prefix

indicates.

3-73

Lattice

8086/8088

Compiler

C

Pcntable

Library

Functions

NAME

stpsym

--

get

a

symbol from

a

string

SYNOPSIS
p

=

stpsym(s,

char *p;
char "s;
char "sym;
int symlen;

sym,

symlen);
points to next character
input string
output string
sizeof(sym)

in

s

DESCRIPTION
The
Breaks out the next symbol from the input string.
first
of the symbol must be alphabetic
cbaracter
(upper or lower
and
be
must
the remaining characters
alphanumeric.
case),
is not advanced past any initial white
Note that the pointer
The
is the NULLoutput string
space in the input string.
terminated
symbol.
RETURNS
p

=

pointer

to next character

(after

symbol)

in input

string

CAUTIONS

Must be declared char
valid symbol characters
will contain an initial

3-74

",

as
the stp
are found,
null byte.

prefix
p
will

indicates.
equal s,

and

no
If sym

the

tok

If
in

string

3-75
and

In

The

Functiom

no

notE6é

token other
which
18

s,
including

8

Library

not

pointer
NULL-terminated
in
character8

8tring. string.
of

in

input

the

but

Portable

up

a

in
brk); to

8tring
gtring
string

a

Lattice

name

output
initial
The
any

character
char

the
character
be

declared
token

string.
pointer
=

SYNOPSIS

characters
an

to

=
int char
char
char
char

initial

next

"p; "s; "tok; "brk;
toklen;
8tptok(8,

p

areNULL

",

included
past

of
out

as

break

the
get

stptok

byte.
the found,

token.

in
string
that
character8

C

8086/8088

string
white

token

all

--

stp
(after

the

next

tok,

will
prefix
p

space

a

token

token)

Note

is
input
output
Uxeof(tok)
break
point8
toklen,

Compiler

is

from in defines

from

,

that

break
a

the s

next

8tring

list

to
input

char

indicates.
equal

characters
the

be

input
firstwords,
Breaks
consists
cannot
advanced
token.

DESCRIPTION

p

contain

valid
Must
will

RETURNS CAUTIONS

Lattice

8086/8088

Compiler

C

Portable

Library

Functions

name

stpchr

find

--

specific

character

in string

synopsis
p

=

char
char
char

stpchr(s,

C);

*p;
*s;
c;

points to c in
points to string
character
to be

8

(or is
being
located

NULL)
scanned

DESCRIPTION

Scans the specified
string to findNULL the first occurrence
character.
the specified
the
terminator
byte is
a NULL
pointer
is returned.

If

first,
RETURNS
p

=
=

NULL

if

pointer

c

not

to

found in s
c found in

first

8

(from

left)

CAUTIONS

Must

3—76

be

declared

char %

as

the stp

prefix

indicates.

of

hit

8086/8088

Lattice

Compiler

C

Portable

Library

Functions

NAME

stpbrk

--

find

break character

in

string

SYNOPSIS
p

=

5tpbrk(8,

b);

char "p;
char "s;
char "b;

points
points

poinu

to element of b in s
to string being scanned
to break character
string

DESCRIPTION
Scans

the specified
8tring
to find the
occurrence of a
b 18 a
from the break 8tring b.
character
In other words,
NULL
terminated
of characters
being sought.
the
NULL
8 is hit
a
terminator
byte
pointer
for
is
returne
->

LCl
LC2

->
->

file.Q
file.OBj

and
LCl reads a C source file,
which must have a .C extension,
an
(provided
there
intermediate
produces
are no fatal errors)
LC2
.Q
an
extension.
reads
a
file of the same name with
intermediate
created by LCl and produces an object file
of
file
The
.Q
the same name with an .OBJ extension.
file is deleted by
LC2
when
Each
completes its processing.
phase normally
creates
its output file on the same drive and directory as the

it

4-l

Lattice
input
function,
functions
program

8086/8088

Compiler/Run-time

Implementation

a source
Note that
file defines more than one
does its resulting
object
Individual
be
when
a
broken
cannot
out from the object
file
see
linked;
Section 4.3.2 for more information.

file.
is

Compiler

C

if

so

file.

must be supplied as input to the linker in order to
Two
produce an executable
special
program filefiles must also
be
in the linking process, in addition
involved
to any .OBJ files
The
created
by the user.
linking process can be diagrammed as
follows:
The

.OBJ

file

filenames used depends upon
the memory
that the actual
see
Section 4.4 for more
selected;
information.
In this
and
discussion
in the example below,
the S model will be used to
illustrate the linking process.)
(Note

model

CS.OBJ

+

user.OBj

+

+

...

LCS.LIB

->

LINK

->

user.ExE

special
LCS.LIB.
the
are
files required
First, LINK
as
the first module on
the
must be specified
file CS.OBJ command;
execution
this module defines the execution entry andC
any
using
for
the Lattice
program generated
exit points
as
compiler.
Second,
the
the
file LCS.LIB must be specified
and
I/O library
this file asdefines all of the run-time
library;
The
C package.
functions
incladed
part of the Lattice
user
must
also specify at link time the names of any .OBJ files
which
as well
as
the name of the .EXE file
which
are to be included,
will be created by the linker.
To
illustrate the program generation and sequence, the following
commands
execute the Fahrenheitnecessary to compile,
link,
to-Celsius
This example assumes
sample program (FTOC.C).
that
LC2,
and
of the .EXE files (LCl,
LINK) reside on the same
all
commands
be
The
shown
in upper case,
disk
and directory.
will
although
lower
(Note:
the
case commands
will work as well.
described
here are for
version
of the
prompts
linker
I.I0
Microsoft
linker; for LINK.EXE versions other than l.l, and for
use
with linkers other than the Microsoft
linker, appropriate
be
The

CS.OBJ

documentation
should
responses are correct.)
STEP

I:

Execute

consulted.

first

the
LCl

Note that
the command
STEP

2:

Generally,

phase of the compiler

the

by

default

typing

FTOC

the

.C

will

extension
is not supplied
(although
work properly
even
is).

if it

When

is
issued
the MS-DOS
prompt
after LCI
completed its processing,
execute the second phase
the compiler with
LC2

Again,
4-2

and

no

has

of

FTOC

extension

is specified;

LC2

supplies

the

.Q

Lattice

8086/8088

C

Compiler

Compiler/Run-time

Implementation

extension.
the prompt is issued after
processing,
the linker is invoked

3:

STEP

When

LINK

LC2
by

has

completed
typing

its

CS+FTOC,FTOC,NUL,LCS

as
is specified
the
Note that CS (meaning CS.OBJ)
is required
object module on the LINK command;
for
this
Then
C
FTOC
the linking of any
(meaning
program.
FTQC.OBJ,
which was just produced by LC2) is specified
The
as an
additional
object module.
second FTOC causes
FTQC.EXE,
NUL
the run file
8kips
to be named
the
generation
of a link map, and LCS cause8 LINK to search
LCS.LIB for external
references.

first

4:

STEP

Execute

the

.EXE

file

by

typing

FTOC
The

program
and
values
console.

writes

their

a

list

Celsius

of Fahrenheit
equivalents
to

temperature
the user's

instructions
compiling,
Detailed
for
linking, andSee executing
Section
sections.
programs
are presented in the following
discussion
of the processing performed by
4.3 for a detailed
the
compiler pbases.
presenting

the various command
line formats,
the term field
describe a sequence of non-white space characters
be
shown
in the
Optional
enclosed in
line.
fields will
the
square brackets
II: the brackets are not to be included when
command
actual
is typed.
Examples are provided at the end
of
each
section.
In

will

be

used
to
command

Versions
of Lattice
version
2.0 recognize
The
name
can
filenames.

C

designed to take
of MS-DOS
advantage
2
the full Version
pathnames for
all
be specified
on
the command
line, as in:

LCl b: \lowleve1\file
(which
specifies
b: \lowlevel\file.c
specified
in tinclude
statements,

be

#include
See

option

4.1.1
The

-id

Phase

first

produces
quadruples,
discussion

for
as

compilation),
in

or

it

can

"b: \headers\stdio.h"

below for

further

uses of

command

line

pathnames.

I
phase of the compiler reads a C source
intermediate
records
file of logical
See
Section 4.3.1 for a more
or quads.
The
of
format
the processing performed.

an

file
'

and

called
detailed
of
the
4—3

Lattice

8086/8088

C

Compiler

Compiler/Run-time

Implementation

first phase of the compiler is:
LCl {=stack]
[>listfile] filename [options]
various command
in the order
are shown
line specifiers
command.
shown
to invoke

command

the

they
in the
Required specifier
in
appear
are
specifiers
emphasized
Optional
in
enclosed
type.
are shown
The
brackets.
first two options are part of the general command
line options for all C programs (see Section 4.1.4). This allows
expressions
in batch files, such as:
the use of

The
must

if

Lcl

íl
if errorlevel l

=stack

goto errs

The

used
the number
of
to override
first option for is the
bytes
a
reserved
stack (see Section 4.5 for
C
description
complete
of the structure
of
programs).
The
2048
is
is
(decimal)
which
default
bytes,
present,
the stack
sufficient for most programs.
If
be
override
size
the first field after the
field must
as
an
name
is specified
of the first phase (LCl).
number
by
a decimal
(for example,
equals
sign followed
=4096
a value
specifies
of 4096 decimal bytes).
Since
the compiler
to process C statements,
uses recursion
heavily-nested
to use
statements
cause the compiler
more
stack
straightforward,
than
linear
space
sequences.
If a source program with many embedded
the
statements
(ifs within ifs within ifs, etc.) causesSTACK
a
execution
with
phase to terminate
first
OVERFLOW
compile
error
message, the program should
successfully
LCl is re-execmted using an
increased
Some
be
may
experimentation
stack size,
such as 4096.
On
required
size.
stack
to determine the necessary
the stack
size
systems which are cramped for memory,
be
may
a
trimmed down in an attempt to eliminate
Not
enough memory
there is no
however,
guarantee,
error;
that
the compilation
will be successful,
particularly
the stack size is reduced below 1024 bytes.

It

if

if

>listfile

second option is used to direct the
first phase
messages
include
to a specified
file. and These
message
any
the compiler sign-on
error or warning
be
The
messages
may
which
generated.
full filename
including
extension,
must be specified,
the
any.
If This
and
already exists,
is truncated
reused.
option
is
useful
for reviewing
long lists
of error
messages.
The

messages

file

filename

it

if

be
This
is
tbe only command
which must
line field
specifies
the name of the C sour=fi1e
present;
The
be
filename
is
should
which
to be compiled.
phase
specified
without the .C extension;
the first
supplies
the extension automatically.
Note that only
some
files with a .C extension can be compiled;
is specified,
ignores
other extension
the compiler

it

if

4~4

it

Lattice

8086j8088

C

Compiler

Cowpíler/Run-time

Implementation

(tinclude
to find name.C.
files, on the
with
extensions.)
harA,
must be fully specified
and
The
directory
default
drive
(hereafter
drive/directory) are used unless a pathname preceding
another
the filename specifies
the
drive/directory;
and
quad
as
directory
file is created ° Ekethesanie drive
ased
is
the source
(see
Eá~mnless
-o option
be either
may
Alphabetic
characters
below).
upper or
lower case in filenames.
and

other

tries

options

as
a hyphen followed
Compile time options are specified
The
by a single
must be typed in lower
letter.
letter
the corresponding
upper case option will have no
case;
effect. Each option andmust be specified separately, withbe
a
(that is, they cannot
separate hyphen
letter certain
UNIX
combined as
they can
for
programs).
Current options include:

-a

Causes

the compiler to assume
worst-case aliasing, that
based
on
favorable
to abandon any optimizations
assumptions
about pointers.
Normally,
the compiler
assumes
objects referenced
that
through pointers
are
in
not the same as objects being referenced
directly
the same section of the program;
option
cancels
this
The
that assumption.
-a option additionally forces all
assignment statements to be performed (i.e., the actual
memory)
execution
before
of
the
store
to
next
Normally,
the code generated for assignment
statement.
be
may
loaded to a register,
but
causes a value to
the -a flag now forces the
not be stored immediately;
This is important only in (I) unions,
store operation.
inspected
where a value is stored and then immediately
via another member;
(2) realor passed to a function
as
time processing where shared data values are used
and
"lock" words,
immediate execution of an assignment
and
statement is critical to subsequent actions;
(3)
memory-mapped
I/O assignments,
where values
must be
in the same "memory" location.
stored repeatedly

is,

it

-b

Forces byte alignment
first phase normally
pointers,
structures,

for all offset calculations.
aligns all objects which are
or unions on a wc>rd boundary.

The

not

The
to be processed without nesting.
be
may
that comments
normally assumes
allows
large
sections of code to be
this
commented
This option allows the user
out very easily.
mode
non-nesting
to force the compiler to the standard,
of operation.

-c

Causes

comments

Lattice
nested;

compiler

-d

Causes

debugging

information

to

be

included

in the quad

Specifically, line separator quads are interspersed with the normal quads.
This allows the second
phase
to collect information
relating input line numbers to program section offsets.
If this option is
file.

4—5

Lattice

8086/8088

C

Compiler

used,

the

Compiler/Run-time

Implementation

object
produced will contain line numand
be processed
by
can
records,
the object
Module Disassembler
intermixed
to produce an
source
machine code listing
code and
(see Section
4.1.6
below).
Note that the -d option does not affect
the
size of the function
itself, only the object file.

file

ber/offset

-iprefix

Specifies
that #include files are to be searched for by
prepending the filename with the string prefix,
unless
is already
in the #include
the filename
statement
by
Up
a drive
prefixed
to 4
or directory
identifier.
be
may
strings
specified.
Note that when
different
an
tinclude
unprefixed
filename is
encountered,
the
is
cutrent
searched;
then
drive/directory
specified
are searched using prefixes
drive/directories
in
options,
in the same left-to-right
order as they
command
were supplied orí the
line. The drive/directory
specification should followNo DOS 2.0 naming conventions
intervening
(see
example below).
blanks
are
permitted
in the string following
the i.

-i

-i

—mM

the compiler to generate code for the specified
The
as
a single
model.
model can be specified
either
naming the model;
upper- or lower-case,
letter,
used
from (J to 3 may be
(S=0,
or a numeric indicator
The
P=l,
0=2,
model specifier must be adja¿ent
L=3).
—m (no
(See
intervening
blanks).
Section 4.4.2).
to the
Causes

memory

up to 39 characters
the compiler to retain
symbols, including
#define symbols.
symbol retention
length is 8 characters.

-n

Causes

-oprefix

Specifies
that the output file (the .Q or quad file) is
.C
to be formed by prependíng the input filename (the
The
which is being compiled} with prefix.
drive
is specified
by a single alphabetic
character,
either
Thus
followed by a colon.
-ob:
upper
or lower case,
Any
drive
with b:
causes prepending
or directory
prefixes
attached to the input filename are discarded
No
intervening
before
the prepending is performed.
in the string following
blanks are permitted
the o.

identifier
all
default

for
The

file

.

-8
-x

Changes

pointers

the way
in the D

code
and

L

is
generated
for
four-byte
models; see Section 4.4.5.

the default
class
for
external
storage
(made
declarations
outside the body of a function)
from
The
external
reference.
usual
to external
definition
an
an
meaning of
declaration
for
which
exteroal
to define
present is
explicit storage class andis not
make
in other
for
the object
storage
visible
The
-x option
files:
i.e., external
definition.
be
as
treated
they were
to
causes such declarations
by
preceded
that is,
the extern keyword,
the object
Changes

it

if

4-6

Lattice

8086/8088
being
option
BDS

C

C

Compiler

Compiler/Run-time

Implementation

declared
is present in some other
This
is provided for use on programs written
for
the
see
compiler;
Appendix C for more information.

file.

EXAMPLES
LCl

xyzfile

-b: \headers\

command
This
executes the first phase of the compiler
XYZFILE.Q
as
using file XYZFILE.C
input,
creating
Any
in the current directoryr
binclude files not found
in the current drive/directoty will be searched for in
B: \HEADERS.
the directory
Note the trailing backslash
on
attached to the
the prefix
is not
flag;
assumed
by
automatically
the compiler.

file

-i

LCl

-ob:

XYZ

it

-X

command
This
executes the first phase of the compiler
XYZ.C
as
using
input,
creating
file XYZ.Q on B:
a
external
declarations
without
sets
storage
all
as extern
declarations.
class to be interpreted

file

it

LCl

=4096

>tns.err

;

tris

command
This
executes the
using file TNS.C as input,
logged-in
disk;
currently
4096
and
decimal
bytes,
contain all of the messages

phase

4.1.2

first

phase of the compiler
creating
file TNS.Q on the
causes the stack size to
TNS.ERR
create a
to
generated by the compiler.

it

file

2

The

by
second phase
of the compiler reads a quad
the
file created MS-DOS
phase and creates an object file in the standard
See
format.
Section 4.3.2 for a more detailed
discussion
of the
The
processing
performed.
format of the command
the
to invoke
second phase of the compiler is:

first

LC2
The
The

filename

(options]

format is very similar
phase.
to that for the first
and
stack size override
options can a}so be
used,
but they are generally
less useful and
not be described here
in any detail.
phase of the compiler does any
Note that neither
so
processing
of the standard input,
the < option has no effect
phase
C
on
either
(see Section 4.1.4 for the general
program
execution
options).
command

filename

listfile

úill

This
specifies
the name
of
field must be present;
be
intermediate
the
file for which code quad is to
This intermediate
generated.
file is a phase file with
.Q
a
extension,
created by the first
of the
The
compiler.
without
fije name should bephasespecified
.Q
the
extension;
the second
supplies
the

it

4-7

8086/8088

Lattice

C

Compiler

Compiler/Run-time

Implementation

may be
automatically.
extension
Alphabetic
characters
The
in either
supplied
default
upper or lower case.
is used unless another drive/directory name
directory
and
is
specified,
the object file is created in the
same
as
drive
the quad file unless the -o option
is
used (see below).

options

hyphen
as
a
time
options
Compile
are specified
The
followed by a single letter.
letter must be typed
in lower case; the corresponding
upper case option will
Each
be
must
no
option
specified
have
effect,
and
with a separate hyphen
separately,
(that is,
letter
UNIX
they
certain
cannot be combined as they can for
programs).
Current options include:

-ggroup

a name
Assigns
of the user's choice to be used for the
in the .OBJ module.
code group
group may be 15 or
and
be adjacent
must
fewer characters
in length,
to the
blanks).
-g {no intervening

-oprefix

Specifies
that the output file (the .OBJ file) is to be
.Q
formed by prepending the input filename (the
file
The
is being compiled) with prefix.
which
drive
is
alphabetic
specified
by a single
either
character,
by a colon.
Thus
lower
followed
-ob:
upper or
case,
Any
with b:
drive
causes prepending
or directory
prefixes
attached to the input filename are discarded
No
intervening
before
the prepending is performed.
blanks are permitted
in the string following
the o.

.

-ssegment

Assigns a name of the user's choice to be used for
the
code segment in the .OBJ module.
segment must be 15 or
be
and
must
fewer characters
in length,
adjacent to the
blankg).
-S (no intervening

-v

Causes

the code generator
to omit the code at the entry
(See
which checks for stack overflow
tD each function
Section 4.5.5).

The

and -s options for LC2 are provided
the
to override
code group arA segment names.
Only users who need
to
applications
languages,
(other
to very specialized
need
make
to
use of these options.
will

-g
default
interface

etc.)
EXAMPLE
LC2

u790

-OC:
This
using
to be

4-8

command

file
created

executes

U790.Q
on

as

drive

the second phase of the
input,
causing the file
C:

.

compiler
U790.OBJ

Lattice

8086/8088

C

Compiler

Ccmpiler/Run-thne

Implementation

Linking
Program
d

4.1.3

After all of the component source modules for a program have been
be
must
linked together
executable
compiled,
they
to form an
is necessary
This
for
several
step
reasons.
program
file.
by
of
the second phase
the
First, the object a file produced
for execution.
Second, most
compiler is not in
state suitable
not defined in the current module;
programs make use of functions
they must be "connected" with
before
such programs can execute,
be defined
by
may
functions
These external
those other modules.
as
the user, in which case they must be compiled and be available
.OBJ
they may be defined in the library supplied with
files, cir (The
functions
the compiler.
portable
are described in Section
3;
others
defined
in Section
only under MS-DOS are described
C
Third,
although
normally defines the function
5.5.)
called
be
C
a
execution
main to
point of
the
program, there is usually a
be
must
amount
processing which
considerable
of system-dependent
performed
before main is actually
called;
the module to perform
into the program when
is integrated
is linked.
this processing

it

function
the usual concept of linking involves external
defined
to access data locations
calls, C also permits functions
This kind of reference
is possible because the
in other modules.
mechanism
by
linkage
external
supported
the object
code
an external
associates
symbol with a memory
location;
symbol
this
used
The
is the identifier
to declare the object in a c program.
the same
to declare an object with
programmer must be careful
and
the module
attributes in both the module which defines
which refers to
because the linker cannot verify the type of
made
simply connects memory
reference
references
using
external
symbols»-- The Lise of include files f,o,k common
external
Ó7"error.,
declarations
will usually prevent this'"kiñd
Although

it,

it

it

sense requires that all of
linking process in a general
specified,
of a program be
either
directly
as
input to the linker.
Three types of input
indirectly,
required.

The

components

the
or
are

].

CD.OBJ,
or CL.OBJ)
file CS.OBJas (or CP.OBJ,
specified
the first module included by
the
This
defines the MS-DOS entry point
for
linker.
file
all C programs compiled using the Lattice C compiler.

2.

by
as
Functions
generated
specified
the user must be
These
additional
modules to be
included.
modules
as
as
any
include
the main module,
additional
well
defined in other source modules.
functions

3.

A Zibraty
or LCL.LIB)
file LCS.LIB (or LCP.LIB, LCD.LIB,
as
during
must be specified
the library to be searched

A start-up
be
must

linking.

In the case of the Microsoft
inputs are specified
by:

linker

supplied

with

MS-DOS,

these

4-9

Lattice

8086/8088

Compiler

C

l.

Making

2.

Including
the
object
user's
CP,
CD,
(or
or

LINK

Typing
Libraries

3.
Note

command

CS
command.

that

for

must

be

(or

Compiler/Run-time

CP,

CD,

or

(without

names

CL)

the
the

Implementation

first

.OBJ

extension)

files on the LINK command,
CL)
specification.

LCD
(or LCP,
or LCL)
prompt from the linker.

LCS

step (2)", one of the
the main module.

files

in

module

after
response

included

on

the

on

of the
the CS
the

to
the

LINK

the
linker cannot find one of the .OBJ files mentioned on .EXE
If thecommand,
a
without creating
will stop processing
it
can
Another
condition
arise if the linker cannot
error
file.
.OBJ
find
referred
to in the
all of the external items
files
be
specified.
In this case, the message
Unresolved Externals
will
by
names
generated
the linker, followed by a list of the external
SÉj.
,t.o.
LINK

which
were not defined.
unresolved externals
should
missing functions
will never

attempt

execute a. program with
is certain
that the

be made
unless
b.e. called.

Section
4.2.2
for a discussion
Section
4.4
for a discussion
of the
used
See
in the four memory
models.
description
of
the object
code
implementation.
the
linker being
a .MAP
public
symbol map,
file may
examination
of the components in the
See

If

it

See
names.
of external
and
startup
library files
Section 4.5 for a technical
used
features
in
this
used
allows generation
of a
be
created,
allowing
the
resulting
load module.

EXAMPLE
LINK

CS

XYX

QRS

Run
File [cs.ExEj: XYE

List File [NUL.MAP]:
Ubraries (.LIB]: LCS
as
This command
executes the linker, prodacing XYZ.EXE
and
an executable
program, and causes the files XYZ.OBJ
QRS.OBJ
AnswerS
to the
to be included in the program.
from the linker used for this compilation
prompts
are
also shown.

Álternatively,
command
a

LINK

4.1.4

single

line:

Linket

instructions

can

appear

on

CS+XYZ+QRS,XYZ,NUL.,LCS

Program Execution

When

C
a
program
begin execution.
receives
before

it

4-ID

these

is executed,
important
control.
Two

the function
main is
called
to
services are performed for
main

Lattice

I.

8086/8088

C

Compiler/Run-time

Compiler

Implementation

command
and
which executed the program is analyzed,
as
is supplied
information
from the command
line
The
and
analysis
performed
the
parameters
to main.
be
discussed
in
of the parameters supplied will
nature
This
feature
is designed to make
detail below.
command
easier to process
line inputs to the program.

The

it

2.

buffered
(standard
text files stdin
input), stdout
and
stderr
(standard
(standard
output),
error)
are
opened
and
by
thus available
for use
the program.
units
assigned
Normally,
three
user's
the
to
are
all
console,
but stdin and stdout may be assigned elsewhere
by
command
options
described
below.
This feature
line
in the use of programs
allows
which work
flexibility
and
with
I/O using
the standard
getchar
text
putchar macros.
The

file

way
simplest
to execute a C program 18 to type the name
of
by
a return
the .EXE
(without the .EXE extension),
followed
Since the command
().
line provides a convenient way to
supply input to a program, a program execution
request will often
The
contain
information.
other
general format of the command
line to execute a C program is:

The

file

["stack]

[outfile)

[args)

as
Everything
indicate.
is optional,
the brackets
after
The
and
various additional
items ("stack,
outfile),
command
present,
must appear before all other
line arguments
following
the program name.
Note that these three items do
not
contribute
to the argument count.
pgmname

if

pgmname

This
name

field
of

linked.
extension.
=8tack

The
number

names

the

It

the
.EXE

must

is the
to be executed;
created when the program was
.EXE
specified
without
the

it

pEogram

file
be

first

optional
field is used to specify a decimal
of bytes to be reserved for the stack when
the
The
default
value used
program executes.
this
field
2048
The
is
is
bytes.
size
is
not present
stack
number
by
as a decimal
specified
immediately preceded
an
sign.
equals
All objects declared auto are
allocated
from the stack, but the memory
used for these
allocations
is freed when the function
in which they
The
dynamic nature
are declared returns to its caller.
makes
of
allocation
generally
to
this
difficult
how
much
needed
predict
a
stack space is actually
for
The
on
option
stack size
the
program.
particular
command
of
line allows the user to adjust the amount
memory
reserved
for
the stack
without
having
to
The
memory
recompile
reserved for
the
the program.
stack
available
affects
the amount
for
of memory
by
dynamic allocation
the various
library functions

if

it

4-ll

mttice

8086/8088

C

described
information

outfile

it

if
list

The
third optional field names a file orbe device to
which
the standard output (stdout)
assigned.
is to
This
option
is
useful
only
the program being
executed actually
uses the standard output (that is,
generates
or printf or makes
text output using putcbar
The
explicit putc or fprintfbe calls using stdout).
file>
by
name
immediately preceded
a
must
or device
a
name
character;
the full
including
See
extension,
Section 5.2
any, must be specified.
The
for a
of valid device names.
is opened
file
as
a new
file, which anddiscards itsan previous contents
they already existed
creates
empty file.
the
filename
specified
is invalid or not enough
directory
the ptogram
to create the new file,
space is available
is aborted with the error message
Can't creat2
stdout

if

list

if
if

it

file,

If

file.
two
If
is

if

characters
instead of one,
the file
are used
and
any
on to
flor appending,
output is added
the
of
option
is useful
for
the
This
The
accumulating
logging information.
file is created
does not exist.
opened
end

>

file.

if it

arg8

and
name
additional
fields beyond the program
and
three
optional
passed to
are extracted
fields
function
main as two arguments:

Any

main(argc,
argv)
int argc;
char *argv{];

r
/"

number

array

of arguments */
of ptrs to arg strings

the
the

"/

a null byte.
Each arg string is terminated
argv[0]
is the name
which
systems which support C,
under MS-DOS
Unfortunately,
the program was invoked.
available,
although all
the program name is not readily
A
of the other information
from the command
line is.
dummy
supplied
argv[0j
is therefore
(all programs are
named
c according
to argv[0])
but subsequent
elemeots
of argv are defined properly.
Arguments appear in argv
by

4-12

On
by

most

8086/8088

Lattice

in

the

command

specifiers
strings.

Compiler

C

same

Compiler/Run-time

Implementation

order in which they were found
stack
Note that the optional
included
in the argv
are not

line.

on
and

list

the

file

of

Although
intended as
conveniences
all of the above features are
many
of the
for writing
programs under MS-DOS,
library
I./O
functions
are forced to be a part of the program because of
Df
input
the buffered
this processing
(specifically, the opening
and
the
fiLes).
For programs which were going to use
output
I/O functions
does not present a problem,
buffered
anyway,
this
add
number
a substantial
of bytes
of
even
though these functions
code
the size of the linked program.
Users who
must be
to
who
and
about program size
these
concerned
are not using
can
a
functions
avoid including
the extra modules by supplying
the library function
which calls main.
special version of main,
See
Section 5.4 for"details.

utility

EXAMPLES
CPROG

=8000

PQP

>errors.log
This
to

data

command

value
Function

argv

with stdout connected
executes ERRLOG.EXE
for
appending (adding to the end
of
be supplied
function
with an argc
will
c and
data in the argv array.
of 2, with strings

ERRORS.LOG
The
main

file).

4.1.5

file

will

Extract

Utility

Because the compiler
generates a single,
indivisible object
module for ali of the functions
defined in a source
file, the
(FXU)
Function
is provided so
that
of
Extract
groups
Utility
be kept together
and
may
functions
in a single source
small
The
them
object
modules produced for
individually.
by extracting
the source text for a single,
specified
operates
a
function,
creating
thus
module which can
then be
source
compiled to produce an object module defining
specific
only that
function.

file
utility

Those

who
may
puzzled by the need for this
are somewhat
Suppose
find the following
example helpful.
that one user has a
STRING.C,
module called
which defines several
string
handling
and
functions,
that a program calls one of those functions
(say,
STRING.C
is compiled as a single source module, the
strcnt).
resUítiDg
object module defines strcnt along with several
other
When
functions.
the machine code
the program is linked,
then,
(as
for
module produced
part of the object
strcnt is included

utility

If

4—13

mttice

8086/8088

C

Compiler

Compiler/Run-time

Implementation

STRING.C
was
compiled),
but the code for all of the other
is included as well,
functions
not
even though the program does
make
use of them. Only by compiling 8trcnt as the only function
defined
in its source module will the compiler produce an object
module
be
used
FXU can
which defines only that function.
-to
produce such a source file.
when

The

format

of the

ccmmand

to invoke

the Function

Extract

is
FXU

[output-fi1e)

filename

Utility

function

various command
in the order
they
are shown
line specifiers
in the command;
optional
specifiers
appear
are shown
The
enclosed
in brackets.
first two options are part of the
command
options for all C programs
general
(see Section
line
40 I 4 )
P
e

The

must

output-file

The
first option specifies a when
file which will be
copied
the specified
to the output file
The
function
is
found.
entire
is copied
file
is written.
before any text from the function
If
only
the function
itself is to be written to the
the INPUT.C

This
text
the

called strcnt from the
the function
text
to be
causes the extracted
console.

and

input

XOFUNC.C

command
the function
called input from the
extracts
IOFUNC.C,
prepends the output with the text from
IOS.H
and
writes the resulting
text to INPUT.C.
can
in IOFUNC.C
refer to the external
each function
and
and
ne,eds
locations
flag2,
for example,
the
information
from the standard I/O header
then IOS.H

If

file
file

flagl

should

include

tinclude
extern
A

similar

extensive



int flagl,

flag2;

technique can
external
references.

4.1-.6 object

file,

the text

be

used

for

functions

which

need

more

Module Disassembler

C modules at the machine
code
programmers who wish to debug
(OMD)
provides a listing of
level,
the object Module Disassembler
the machine language instructions
generated for a particular C
the module is compiled with the -d option
source module.
so
that
information
is included in
the object
line number/offset
can
with
produce a listing
file, the disassembler
interspersed
lines.
This listing can then be used in
source code
For

If

utility

4-15

Lattice

8086/8088

association

interactive
The

format
disassembler
OMD

C

Compiler

Compiler/Run-time

with
the link map
for
debugging using Microsoft's
of
is

the

[>1istfile]

command

[options)

invoke

first

program

to

perform

object

the

module

objfile [textfile]

specifiers
various
are
in the command.
Optional
must appear
enclosed in brackets.
command

The

line

to

the
DEBUG.

Implementation

in the order
specifiers
are

shown

they
shown

>listfile

The
by

options

each
options can be specified;
Four override
consists
of a hyphen followed by a single letter which indicates
be
and
a string of
the
overridden,
value
to
decimal.
specifying
value.
the override
There must be no
digits
embedded
each
be
must
blanks in any single option,
but
a separate
as
specified
field. The valid options are:

-Pnnn

Overrides
size provided
the default
section
of
the object module being
number
a
specifies
decimal
of bytes
allocated
for the program section.
is 1024 bytes.

-Dnnn

Overrides
size
provided
for
the data
the default
section
nnn
of
the object module being
processed.
a
specifies
decimal number
of bytes of storage to 75é
The
allocated
default
for the data section.
is
value
1024
bytes.

—Xnnn

maximum
number
items
Overrides
of external
the default
by OMD;
be processed
can
which
applies
this number
and
separately
external
to both external
definitions
number
nnn
a decimal
specifies
of external
references.
The
items
which
default
i':
value
can be processed.
200.

-Lnnn

and
Overrides
size for the line number
the default
These tables are used only
offset information tables.
the object file was produced with the -d 'option;
information
from the file is placed
line number/offset
The
size (which defines the
tables.
default
in thesenumber
maximum
pairs which can be
of line number/offset
processed)
is 100.

OMD

to
is omitted,
console.

option is used
to direct the listing produced
a specified
file or device.
this option
the listing output is written
to the user's

If

for
the program
nnn
processed.
of storage to be
The
default
value

if

objfile

4-16

Specifies
the name of the object file,
compiler,
which is to be processed by
name
including
the .OBJ extension must

produced by
The
OMD.
be
specified.

tbe

full

Lattice

8086/8088

textfile

C

Specifies

Compiler

Compiler/Run-time

source code file which is to
disassembled instructions.
the object
must have been
The
using the -d option for the LCl command.
including
the .C extension
must be specified.
the

name

of

a

C

listed along with the
this option is present,

be

compiled

full

name

Implementation

If

file

The
processes only a single object module.
entire module Theis
before the listing is generated.
read and loaded into memory
override
various
options are useful for processing
large
very
needed
by
object
of memory
modules,
or for reducing the amount
OMD on
for memory.
systems which are cramped

OMD

only the source text
from the
the textfile option is used,
specified
is listed;
refers to any tinclude
files,
Some
they will not be listed.
limitations of the textfile option
code
be
for
portion
noted.
the
generated
the
should
ttiírd
First,
that code
of for statements is placed at the bottom of the loop;
end
the
the
of
the
next statement after
appear in front of
will
compiler
tends to defer
storing
loop.
Second,
the
registers
shown
moment,
so
that the code
for
until the last pQssible
loading
often consists merely of
assignment
statements
values
be
into registers;
the registers
stored later.
will
Finally, the
code generated for entry to a function will often be displayed
in
function.
front
of the source
lines
defining
Thus,
that
be
inspection
of the surrounding
code may
necessary to determine
the actual code generated for a source
construct.

If

if it

file

file

EXAMPLES
OPID

-P2048

-D8000

QRS.OBJ

and
This co=aDd disassembles the object module QRS.OBJ
writes
console;
the listing to the user's
causes
2048
decimal bytes of storage to be allocated
the
for 8000
and
program section defined in the object module,
decimal bytes for the data section.

it

OMD

>TEMP.LST

-X400

XYZ.OBJ

XYZ.C

and
This command
disassembles the object module XYZ.OBJ
TEMP.LST;
writes
the listing to the
causes the
placed
in the
code lines
from XYZ.C
to be
source
and
provided
that
listing,
line number
offset
information
is present in the object file.
also
number
a maximum
provides
for
of 400
external
items
(same
limit for both external definitions and external
references).

file

it

It

ERROR

MESSAGES

a
variety of error conditions are detected by the object Module
and
Disassembler;
all cause early termination of the output
result
in the writing of an appropriate
to stderr.
error message
one
These messages
for the most part.
of
are self-explanatory
options is not sufficiently large,
the run-time-specifiable
the

file
If

4—17

D

Lattice

8086/8088

C

Compiler

Compiler/Run-time

Implementation

the specific option which
etror
message will indicate
large enough;
for example,
the module defines too
of program section,
the message

if

Program section

was
not
words
many

overflow

will

be produced.
Note that OMD was designed specifically
for
with modules generated by the C compiler;
attempts to use
with other object modules will probably cause an error message
to
be generated.

it

use

4.2

Machine Dependencies

does
C language
specify all aspects
not completely
definition
a number
of important
features
of the language;
are described as
in some of the finer details
machine-dependent.
This flexibility
permits
the language to be implemented on a variety
of machine
without
architectures
forcing
code generation
sequences that are
awkward
and
one
on
on
machine
another.
This
section
elegant
as
describes
features of the
the machine-dependent
language
2
manual
See
on
Section
implemented
the 8086/8088.
of the
for a
description
of the machine-independent
features of
the Lattice
implementation
of the language.
The

4.2.1

Data Elements

C
according
standard
data
types are implemented
to the
The
following
descripticms.
data
elements
which
free
only
and
alignment to a word offset are pointers,
unions;
structures,
be
by
as
a
noted in Section 4.1.2,
disabled
this alignment can
of the length of
compile time option.
regardless
In all cases,
the low order (least
the data element,
significant) byte is
followed by successively
higher order bytes.
stored
This
used
scheme
on
is consistent
with the general byte ordering
the
with the memory
formats expected by the 8087
numeric
8086, and
The
following
data processor.
table. summarizes the character,istics of the data types:
The

first,

Type

char

int

8)ijort
unsigned
long

float

double
char

int

4~18

Length

in

Bits

to 255 (ASCII character
set)
-32768 to 32767
-32768 to 32767
0 to 65535
-2E9 to 2E9
+/- I0E37 to +/- I0E38
+/- I0E-307 to +/- WW08

8
16
16
16
32
32

0

64

defines
characters
according

Range

B-bit
unsigned
integer.
with
are generated
bit
format.
to the standard ASCII

an

defines a l6-bit signed
int are synonyms.

integer;

short

7

and

Text
reset,
short

Lattice

8086/8088

unsigned
unsigned

or

int

C

Compiler/Run-time

Compiler

Ímplementation

defines a í6-bit unsigned integer.
Note that in
unsigned is not a modifier
this implementation,
but a separate data type.

long or
long int

defines

a

float

defines
with an

B-bit

32-bit

signed

integer.

32-bit signed floating point
number,
and
a
biased binary exponent,
24bit fractional part which is stored in normalized
form without the high-order
bit being explicitly
The
This
represented.
127.
exponent bias is
6
representation
is equivalent
to approximately
7 decimal
or
digits of precision.

double
or
long float

defines
with an

a

a

64-bit

signed

floating

point
number,
and
a 53exponent,
stored in normalized
bit being explicitly
The
This
1023.
exponent bias is
15
is equivalent
to approximately
digits of precision.

ll-bit biased binary
bit fractional part which is
form without
the high-order
represented.
representation
16 decimal
Dr

two
pointers
bytes or four
to the various data types are either
bytes in length,
depending on the memory
addressing model
used.
See
Section 4.4 for more information.

4.2.2

External

Names

External
identifiers inone the MS-DOS implementation MS-DOS
differ from
ordinary
important
in
the
linker
respect:
identifiers
they were the same.
treats
upper and lower case letters as
means
main and
This
that,
although the compiler will consider
MAIN
two
functions,
linker
the
to be
not.
will
different
be up
and
names
may
External
in
length,
the
to 8 characters
underscore
is a valid character.
Since
the compiler
always
assumes
names
as
characteristics
that
external
have the same
ordinary
identifiers, programmers must be careful not to define
names
which
external
the compiler believes
are different but
A safe
which the linker will interpret as the same name.
rule is
items,
to use lower case letters only for all externally
visible
and
including
functions
data items which are to be defined
for
reference
from functions
in other source files.

if

A

user

conflict
*******
CX***h

define external
with the following

may

objects
classes

Certain
library functionsC)
modules written
in
underscore.
Run-time
language)

with any name that
of identifiers:
and
data elements
with
are defined

does

(defined
an

functions
(written
in
support
which implement C language features

not
in

initial
assembly
such as
4-19

Lattice

8086/8088

C

Compiler

Compiler/Run-time

integer
long
multiply and divide,
and
arithmetic,
the like are defined
first two characters.

likelihood

Include
Include

or

is
collision with library definitions
and
avoid
aware of these conventions
user-defined
identifiers to external,

of

but users should
these
types of
and
data.
4.2.3

floating
CX

with

as

point
the

Low-level operating
system interface
functions
(written
in assembly language) are defined with XC as the first
two characters.

XC"***

The

Ímplementation

be

File Processing
files may be specified

tinclude

"filename.ext"

tinclude



remote,
applying
functions

as:

The
name
the same effect.
two forms have exactly
between the
be
must
delimiters
is
taken
face value;
the extension
at
The
one
specified
is defined for the file.
usual convention
as was
is to use .H for all header files,
done with the header
the compiler package.
Alphabetic
characters
filesa included with
be
filename may
in
specified
in either
upper or lower
case.
The
be
must
present in the default
drive/directory unless a
drive
(not
specifier Theor pathname is included in the filename
recommended).
option
is
(see Section
4.1.1)
the
a
recoñmenáed method for
specifying
different drive byand,/or
The
filename
is retained
directory
path.
the
internally
compiler for error reporting
(see Section 4.3.3).
The

if

file

-i

4.2.4

Arithmetic

Operation8

and

Conversions

Arithmetic
operations
for
the integral
types
(floating type
operations
in the next
section)
are discussed
are generally
performed by' in-line code.
Integer overflows
are ignored in all
16-bit
although
signed
comparisons
cases,
correctly include
in determining
overflow
the relative size of operands.
Division
bjj
MS-DOS;
on
zero generates an interrupt which is processed by
the operating
the message
system used to develop the compiler,
overflow
is generated and execution of
the offending
Integer
Division
of negative integers
program aborted.
causes truncation
and
integers,
does for positive
toward
the
zero,
just as
has
remainder
Right shifts are
the same sign as the dividend.
arithmetic,
that
is,
the sign bit is copied into
vacated
bit
positions,
unless the operand being shifted
is unsigned;
in that
a
is
performed.
case,
logical (zero-fill) right shift

it

Function
calls to library routines areandgenerated only for long
integer
comparison.
Product
multiplication,
division,
is ignored.
Division
by zero yields a result
overflow
of zero.
The
same
as
is
sign
remainder
sign
of the
the
the
of
the
4-20

8086/8088

Lattice

C

Cowpiler

Comparison

dividend.
overflow.

is

Conversions
are generated
conversions"
described
in
trouble
free.
generally
noted:

I.

0

for

D

will

4.2.5

signed

Iwplewentatiot3

but does not take

according to the
"usual
and
Ritchie,
Kerntghan
The
following
four points

account

i;
O
(i"8; i
not

of

arithmetic
and
are
be
should

char objects are unsigned in thi8 implementation.
is n.o.t. performed during expansion
extension
to
instead,
the high byte 18 simply set
to zero.
sequences such as
char

Sign

int;

Code

i--)
(in this case, the loop never terminates).
sign
of
int or 8hort to long causes
The
inverse operation
is a truncation;
the
large
und"

D;

work

2.

Conversion
exteosion.
is
result
to be represented.

3.

Conversions
from
straightforward.
fractional part to

4.

Compiler/Run-time

integral
The
be

to floating types are fairly
conversions
inverse
cause any
dropped.

Conversion from float to double is well-defined,
but the
may
an underflow
inverse
operation
or overflow
cause much
condition
since double has a
larger exponent range.
is also lost, though the fraction
precision
Considerable
is rounded to its nearest float equivalent.
Floating

point

Operatiom

point
In accordance with the language definition,
floating
alldouble
precision
using
arithmetic
operations
are performed
and
operands,
type float are converted
all function arguments of
The
used
formats
to type double before the function
is called.
and
long real formats expected by
are identical to the short real
in
the 8087
numeric data processor
(the formats are described
include simple
Section
4.2.1).
Legal floating point operations
conversion
minus
assignment,
to other aritlmetic types,
unary
(change sign),
addition,
subtraction,
division,
multiplication,
and
comparison for equality
Note that,' in
or relative size.
negative floating
contrast
to the signed integer representations,
point
in two's complement notation;
values
are not represented
and
positive
negative numbers
only in the sign
bit. 'This
differ
and
means
positive
of zero
that
two kinds
are possible:
as
point operations
either
negative.
value
floating
All
treat
produce positive
true zero and generally
zero, whenever possible.
code
which checks float or double objects for zero by
Note that
they were int
type punning (that is, examining the objects as
type) may assume
or some other integral
(falsely) neqative ,z.e.r.o,

if

4-21

8086/8088

Lattice
to

be

not

C

Compiler

Compiler/Run-time

Ímplementation

zero.

and
Floating
point arithmetic
comparison operations
are performed
These
do not
by generating
functions
to library functions.
calls
make
use of the 8087, although the floating-point formats
are
with
compatible
these
functions
the 8087.
Note that
were
designed
speed,
using
for
straightforward,
not
accuracy,
algorithms.
unsophisticated

point
Floating
CXFERR
called
coovention:

exceptions
is
that

are processed by
called
according

a

to

library
the

function
following

CXFERR(errno);
int errno;
where

be

can

errno

I2
3

=
=
=

underflow
overflow
by
divide

zero

standard
version
in the
of CXFERR supplied
library file
and
LCL.LIB) simply ignores
LCS.LIB (and LCP.LIB,
LCD.LIB,
all
You
may
write a different version
(in either C
error conditions.
and
terminate
or assembly language) to print out an error message
CXFERR
processing,
returns to the
or take any other action.
is processed as
each exception
library function which called
follows:
The

If

it,

Underflow
Overflow
zerodivide
the

Consult

8087

Sets the result
sets the result
Sets the result

equal to zero.
to plus or minus
equal to zero.

description

more

for

infinity.

information

about

the

floating-point formats.
4.2.6
Bit Fields
Bit fields are fetched on a word basis,
that is, the entire word
containing
the desired bit field is loaded (or stored) even
if
the field is 8 bits or less in size.
are assigned
Bit fields
from left to right within a machine word;
the maximum
size
field
15
is
in this
bits.
Bit fields are considered unsigned
implementation;
sign extension
is not performed when the value of
expression.
is expanded in an arithmIetic
a field
If a structure
is declared

{
structunsigned

unsigned
unsigned
}
a;
then
4-22

a

occupies

a

x

y
z

single

:
:
:

5;
4;
3;
16-bit

word,

a.x

resides

in

bits

15

Lattice

8086/8088

C

Compiler

Compiler/Run-time

Implementation

through
a.y in bits ID through 7, and a.z in bits 6 through
4.
the way bytes are ordered on
Because of
8086,
the
this
in a.y being split between the low and high bytes.
results

li,

4.2.7

Register

Variables

does
This
version
of
the compiler
implement
register
not
number
variables
because of the comparatively
limited
of
on
registers
8086/8088 microprocessor.
available
However,
made.
using
register
declarations
properly'
are accepted
been
is
fW
these objects as
Storage
reserved
they had
declared auto.

if
if

4.3

Compiler

Processing

The

C
two
Lattice
compiler
is
as
under MS-DOS
implemented
each
separately
executable
performing
of the
programs,
part
compilation
task.
This section discusses the structure
of
the
compiler in general terms, and describes the processing performed
by
both phases.
Special sections are devoted to a discussion
of
the topics of error processing and code generation.

4.3.1

Phase

I

first phase of the compiler performs
all pre-processor
functions
concurrently
with lexical and syntactical
analysis
of
input
the
which contain
generates the symbol tables,
file.
and
information
about the various identifiers in the program,
an
intermediate
produces
called
records
file of logical
by
quadruples,
which represent the elementary actions specified
The
quad
the program.
intermediate
(also called the
file
file)
and
is reviewed as
is written,
sub-expressions
locally common When
results.
the entire
are detected and replaced by equivalent
has
been processed (assuming there are no
source
program
fatal
symbol table information
is written
to the quad
errors),forselected
by
The
use
the second phase.
phase is thus very
file,
first
active as far as disk I/O is concerned.
Generally,
the disk
stops for more than a few seconds,
is reasonable to
activity
has
See
assume
that
the compiler
Appendix B for
the
failed.
cqmpiler error reporting
prpcedure
this happens.
The

It

it

it

if

if

When

a
the first
phase begins execution,
sign-on
writes
message
unless (I) the specified
to the standard output,
sjource
file could benot be found, or (2) a quad file with a .Q extension
The
could
created (owing to lack of directory
not
space).
message
sign-on
the version of the compiler which
is
identifies
The
MS-DOS
being
executed.
2.0 implementation
returns an
exit
code
and
code
no errors
of zero
a
of I
were detected,
otherwise.
This allows the use of
expressions
in batch files,
such as:

it

if

if

u
if errorlevel l

LCl
See

Section

4.3.3

for

more

goto errs
information

about

error

processing.
4-23

Lattice

8086/8088
the

Note that
detected.
4.3.2

Phase

C

Compiler

quad

file

Compiler/Run-time
is deleted

if

any

Implementation

fatal

errors

are

2

by
second phase of the compiler scans the quad file produced
and
produces an object file in the Intel 8086
the first phase,
format. This object code supports all of the necessary relocation
needed
and
C
linkage
conventions
external
for
(see
programs
A logical
Section 4.5.2 for details).
segment of code specifying
8086
make
up
machine language
instructions
which
the
the
portion
of the program is generated first, followed by
executable
a segment of data-defining
code for all static items.
Unlike the
the code generator
is not always actively
performing
first phase, Each
disk
I/O.
function
is constructed
in memory
before
its
be
so
pauses
object code is generated,
sizable
there may
fairly
which no appatent activity is taking place.
during
In general,
these delays should not last more than several seconds.
Anything
be
assumed
a
a
30-second delay can safely
than
longer
to ·be
B
for information
crash;
compiler
about reporting
see Appendix
problems.
The

a
sign-on
second phase begins execution,
writes
quad
the standard output,
unless (I) the specified
to
be
(2)
.OBJ
an
a
found,
with
object file
or
file could not
be
extension
could
not
created (owing to
lack of directory
When
phase
is complete,
code generation
space).
the second
writes a message
of the form
When

it

the

message

Module size

p=pppp

D=dddd

pppp
the user's
console).
output (usually
to the standard
indicates
the size in bytes of the program or executable portion
and
dddd indicates
the size in bytes of
of the module generated,
These
the data portion;
both values are given in hexadecimal.
included
include the requirements
sizes
for all of the functions
define
in the original source file.
the
Note that the sizes
(as
amount
required
is loaded
for the module once
of memory
the .OBJ file requires mote space
part of a program) into memory;
relocation
information.
contains additional
because

it

it

noted in the introduction
the code generator
to Section 4.1,
.OBJ
a
module
for
given
module,
produces
source
a single
of how many functions
regardless
module.
were defined in that
These
one
functions
is defined)
cannot be separated
(ifanymoreone than
of the functions
is needed, all of them
at link time;
Functions must be separated
into
individual
will be included.
and
compiled to produce separate object modules
source
files
As
is necessary
to avoid
this collective inclusion.
(FXU.EXE)
a Function
is
mentioned,
Extract
previously
Utility
be
may
multiple
functions
stored in a single .C
sso that
provided
see
Section
file and extracted individually for compilation;
4.1.5.
As

if

it

4~ 2 4

if

8086/8088

Lattice
4.3.3

Error

C

Compiler/Run-time

Compiler

Implementation

Processing

internal
compiler
All error conditions by(with the exception ofAs soon
as
the first phase.
the first
errors)
are detected
the compiler stops generating
quads
fatal error is encountered,
and
deletes the quad file just before it terminates
execution.
This
code
to generate
prevents the second phase from attempting
from an erroneous quad file. As mentioned in Section 4.3.1, under
DOS
2.0 the compiler returns a zero if no errors are detected,
and
When
a l otherwise.
the compiler detects an error in an input
message

file, it

generates
filename

an

of the form:

error

.l,i.n,e,

Error

nn: descriptive

.t.e.x.t.

input file (which may
where filename is the name of the current
Sinclude files are used); line
not be the original source
is the line number, in decimal, of the current
line in that file;
number
LYj. is an error
text
identifying the error; and descriptive
A
a
condition.
is
of the error
(Appendix
brief description
and
provides expanded explanations
warning messages
for all error
produced by the compiler.)
to the
are written
All error messages
standard output,
which is normally the user's console but can be
(see
A
message
directed
desired
Section 4.1.1).
to a file
similar
instead
of
the one above but with the text Warning
to
in this case, generation
Error is generated for non-fatal
errors;
quad
an
of
the
In some cases,
error
file continues normally.
message
will be followed by the additional message:

file if

if

Execution

terminated

indicates
which
that the compiler was too confused by the error
The
compiler uses a very
to be able to continue processing.
simple-minded
error recovery technique which may cause a single
in a "cascade"
to induce a succession of subsequent errors
error
should attempt to correct
the
effect. In general, the andprogrammer
obvious
about
not be overly concerned
errors
error
first
messages
valid source lines (although
for apparently
all lines
for which errors are reported should be checked).
CXERR
messages
begin with the text
which
internal
Error
are
compiler
a problem
in the compiler itself.
errors which indicate
The
See
Appendix B for the compiler error reporting
procedure.
few
compiler
a
that
other error messages
generates
are not
The
numbered;
theY are usually self-explanatory.
most common of
is
that
these
the
the Not enough memory
message, which means
compiler ran out of working memory.

4.3.4

Code

Generation

The

code generation
phase reads the quad file and builds an image
of the instructions
in working
for each function
memory, before
instructions
This implies that
to the object file.
writing the much
be present
must
as
working memory
is required by
at least as
the largest
function
in the source file;
considerably
actually,
more
memory
size)
required
is
(as much as several times that
4—25

Lattice

8086/8088

Compiler

C

Compiler/Run-time

Implementation

overhead used by tbe compiler.
Since
because of the additional
model which has a 64K
byte data
the compiler
uses the S memory
is a definite limit to the size
space
of a
limitation, can there
be compiled
amount
functicn
which
of
even when the maximum
own
memory
all of the compiler's
is available. some Nonetheless,
modules
of which contain very large functions
source
--be
can
compiled without
In any case, C is a language
difficulty.
which encourages modularity;
most programs consist of!
numetous
doubtful
is therefore
that the
functions,
most of them small.
size limitation will prove to be a problem.
function

It

in
the function
for the extra overhead in buffering
reason
are not explicitly represented
is that branch instructions
by
image.
special
Instead,
they are represented
in the function
when
denoting the type and target of each branch.
the
structures
has
been
completely defined,
the branch instructions
function
are
analyzed and several important optimizations
are performed:
One
memory

branch instruction that passes control
another
branch
instruction is re-routed
directly to the target location.

l.

Any

2.

A

3,

Sections
detected

4.

to

to
branch

conditional
branch instruction that branches over a
by
a
unconditional
single
single
branch is replaced
conditional
branch instruction of the opposite sense.
of
and

code into
discarded.

which control

does not flow

are

branch
instruction is coded in the smallest
possible
machine' language sequence required to reach the
location.
target
Each

these optimizations
Most of
are applied
improvement is obtained.
further
The

directly

iteratively

until

no

a
special
also makes
generator
effort to generate
code for the switch statement.
Three different code
and
depending on the number
range of
sequences may be produced,
the case vqlues.
code

efficient
I.

the number
of cases is three or fewer,
control
by a series
routed
of
the case entries
test
to
branch instructions.

2,

and
the case values are all positive
the difference
and
minimum
between the maximum
case values is less than
number
a
twice
of cases,
the
the compiler
generates
branch
table
which is directly indexed by
the switch
by
The
value.
value is adjusted,
the
necessary,
minimum case value and compared against the size of the
indexing.
This
construction
requires
table
before
time and a table no longer than that
minimal
execution
cjf
No.
required
for the type
3.
sequence described in

If

If

if

4-26

is
and

Lattice

8086/8088
3.

C

compiler

Compiler/Run-time

Otherwise,
the compiler
generates
value, branch address) pairs, which is
for the sYitcíj value.

a

Implementation
table

linearly

{cas,e.
of
searched

sequences
the above
are generated in-line without Eunction
enough
of instruction
because the number
bytes 18 small
them
as
benefit
would be gained by
implementing
library functions.

All

of

calls
that

little

Áside from these special control
flow analyses, the compiler does
any
perform
global
data
flow
analysis
not
loop
or any
optimizations.
in registers
Thus, values
are notThe preserved
be
may
regions
into
which
directed.
control
compiler
across
however,
retain information
does,
about register
conteñt8 after
conditional
a
which
region
branches
of
to leave
cause control
code.
Throughout each section of code into which control
cannot
may
via
conditional
branch
(although
branche8),
values
exit
which are loaded into registers
are retained as long as possible
and
The
so
as
operations.
avoid
redundant
load
to
store
by
allocation
is guided
information,
of registers
next-use
obtained by analysis of the local block of code,
which indicates
which operands will be used again in subsequent operationm
This
information
assists
in analyzing
binary
also
the compiler,
operations,
in its decision whether to load both opetands
into
registers
reference
to
or to load one operand and use a memory
an
the other.
Generally,
operation will be
the result
of such
computed
a
in
register,
but sequences like

it

i

j;

+=

and
compute
of j into a register
will load the value memory
into
location
the
for i (but only
directly
used
later in the same local block of code).

the

if i

result
is not

and
AX,
BX,
CX,
DX
hardware registers
are used as general
while SI and DI (along with BX) are used
purpose accumulators,
BP 18 u8ed
for
indirect
operands.
to address
the
access to
see
Section 4.5.3 for more information.
current stack frame;
In
and
ES
d
L
segment
memory
addressing
is
the
models,
the
regigter
used
see
for indirect
pointer references,
4.4.
Section.

The

order
the largest
to generate the most efficient code for
of source language constructiom,
the compiler
u8uaIly
a
assumption
variables.
favorable
pointer
about
assumes
that the actual objects accessed using
specifically,
pointer
variables
are not the same as other objects which can be
This allows the compiler to avoid discarding
accessed directly.
them
register
reloaded,
perhaps
(thus forcing
contents
to be
is assigned
unnecessarily,
at a later time) whenever a remüt
using a pointer.
Consider the following
example:
In

number
makes

it

int i,
C 0

"pi

i

j,

e
=

j+2;

"

j;

k,

"pi;

4-27

tmttice

8086/8088
k

=

C

Compiler

Compiler/Run-time

Implementation

1"4;

is quite possible
In the general case,
that pi might actually
point
which would change the value assigned to k in the
to i,
of C programs,
however, i
next statement.
In the vast majority
is not possible
for pi
to
will be Thea local variable to which
point.
compiler normally makes
assumption,
is,
that
this
and
can
that *pi cannot be equivalent
therefore
retain the
to i,
value computed in the first statement for i in a register, which
operation
in
to perform the multiply
saves having to reload
the third statement.

it

it

it

On

the other

not

valid.

C

pi
*pi

hand,
there are rare cases where this assumption
programmers almost never code sequences such as:
=
=

is

U;

12;

subtle cases of pointer
overlap can occur,
particularly
and
both the pointer
For
its target are externa1iy defined.
option is provided
(Section
these
the -a compile-time
cases,
aliasing
4.1.1);,
to assume
worst-case
this forces the compiler
generating
(which
jargon for pointer
overlap) when
is compiler
The compiler is so designed because instances of pointer
code.
overlap are more the exception
than the rule.
Thus, rather than
assumptions that produce correct
default
code in
to worst-case
and
in most
the
unnecessary inefficiencies
cases,
all cases
makes
a favorable
assumption
compiler
normally
that
produces
code
which works correctly
in nearly ali cases.
efficient
but

more

when

when
even
the -a option is used,
final note on this subject:
assumes
that only objects of the pointed-to
the compiler
type can
be
an
changed in pointer
assignments.
pointer
is
Thus,
int
used
in an indirect assignment,
containing
only registers
int
values will be discarded.
A

if

4.4

Memory

Addressing

Models

and
8086
8088
segmented architecture
of the
processors
special
problems for the implementation
of high
level
presents
languages.
In order to provide programmers with the ability
to
needed
select
the
combination
of efficiency and addressability
a
four
the compiler
for
supports
particulat application,
memotY
assumptions,
called
different Eachsets of memory addressing
and
models.
is
identified by a single capital
letter,
and
data
view of the addressing of functions
reflects a a different
be
by
C
within
These views can
expressed
the
program.
on
for program text
the size of the respective
space
limitation
OÉ
and
functions)
data
objects
the declared
(the
or
(all
allocated
data structures), as follows:
The

4-28

Lattice

8086/8088
Model

The

D

and

Compiler/Run-time

Program Address

Space

Implementation

Data Address

64K

S
P

up

D
L

up

to

Im

to

IFI

to
to

up
up

IM
Im

and
pointers,
four-byte
the P and L models
The
S and
P
models produce
returns.
code limited
to addressing a 64K data
area,
models allow access to all of the I megabyte of
use

calls
efficient
D and
L
memory.

Space

64K
64K

64K

L models
FAR

generate
compact,
while the
available
4.4.1

Compiler

C

Choosing the

and

Memory

Model

The
and
is most efficient (both in terms of code size
compiler
execution
speed)
for
the S model.
of
the examples
in
All
—
previous
with
for compiling
the S
sections have shown commands
and
model
recommended
memory
this
is particularly
model,
for
beginning C programmers.
and
compiled
in a single program must be
of
the functions
memorjj
linked with one and only one of the available
models.
In
functions
compiled for different models may not be
other
words,
becomes
combined.
important,
'therefore,
to choose the right
The
memory
model for the particular application.
tradeoff
is
addressability.
between efficiency and memory
There are two
choices that must be made.

All

It

l. will

in the program
the combined size of the functions
one
of the models
greater than 64K bytes?
not,
If
that
uses NEAR
calls (the s orandD models) should be
as
require
these are faster
less
selected,
code.
model
a
Otherwise,
that supports .F.A.R calls (the p or L
be
models) should
selected.
"""
be

"

2.

"

require more than
the application
bytes of data
one
of the models that uses 2-byte
storage?
not,
be
S
P
data
pointers
(the
models) should
selected,
or
much
more
operations
because pointer
are performed
in these models.
the program simply
efficiently
needs
locations
beyond the
access to specific memory
program's 64K address space,
the library functions
peek
and
be
poke can
used, allowing
the program to retain
the
pointers.
Otherwise,
data storage
efficient 2-byte
64K
a model
in excess of
bytes is a must,
that uses the
must
be
pointers
4-byte
data
(the d or ,[; models)
somewhat
less
selected,
even though this wÍll produce
efficient code.
64K

Does

If

If

if

4.4.2

Compiling

Generation
compile-time

of

for

the

Memory

Models

code for the various models is controlled
on
option
specified
the first phase ([.Cl)

by

of

a

the
4-29

Lattice

8086/8088
The

compiler.

C

a
memory

generated

for

S

(no
immediately
option must be followed
spaces)
the desired
lower or upper case) specifying
be
as
a
specified
single
model may also
code
no -m option
is present,
is
to 3.
the
model.

model:

LCl filename
Lcl filename

(no

-mp

model:

LCl filename
LCl filename

-mD
-m2

L model:

LCl filename
LCl filename

-ml)
-m3

Linking

flags)

-mS

LCl filename
LCl filename

D

4.4.3

If

—

model:

P

Implementation

-m

letter (either
The
model.
numeric digit from 0
S

by

CompÉLer/Run-time

Compiler

-ml

programs

using the various memory
models,
care must be taken to link
appropriate
(LCS.LIB,
LCP.LIB,
LCD.LIB,
with
the
or
library
The
compiler generates code segments with
LCL.LIB).
different
LINK
map
examination
of
the
names
to
for each model, which allows
been
erroneously
determine
code for different models has
names
on
one
should appear
of the following
segment
mixed.
Only
the link map.
When

if

S
P
D
L

model:
model:
model:
model:

Note that for the P and
PROG)
(or
will
piled module containing

_CODE

4.4.4
In
of
the
in
is
by

or

Code

Generation

PROG
CODE
Code
PROG

(code group

PGROUP)

(code group

CGROUP)

models,
included
functions).

L
be

for

Pointer

several segments with the
(one
for each separately,

name
com-

Operatiom

the S and P models, pointers
to the various data types consist
of the low order (least significant) byte of
the ÍÍ6—bit"offset
Since the ccmbined size of the data elements
data element.
the address of an item
these models cannot exceed 64K bytes,
Indirect
data references
are made
fully specified in 16intobits.
one
SI, DI,
of the indexing registers
loading the pointer
BX.

Function
pointers
differ in each of the memory models. In the —S
and
d models,
consist of the 16-bit offset
pointers
to functions
'Éhe
of
the function.
In the .S.
byte of the code defining
is stored in two bytes, while in the D. model,
model, this pointer
'Ewo
two
is stored as the
of four bytes (the last
are
required
conform
but
merely
since
they
used,
to
are
zero
are not
.D
.P
in
model).
the
four-byte
size
of
other
pointers
the
In
the
to
a two-byte
pointer
(required
because of the two-byte size
model,

first

it

4-30

first

8086/8088

Lattice

C

Compiler

Compiler/Run-time

Implementation

is used to store the offset of a four-byte
pointers)
of data
function
This
function
address contained in the data section.
has
pointers
in the .L. model,
the same format as function
pointer
the next
where the first two bytes contain a l6-bit offset and
two
contain the l6-bit segment base for the function.
pointers
code generated by the D and L models uses four-byte
These
in memory.
pointers
address any location
can therefore
in the low two bytes, followed by
are stored as an offset portion
a
in the high two bytes (the format expected by the
base portion
LDS and
instructions
LES).
objects
machine language
are adby
Loading the base portion
into
the
dressed from these pointers
ES,
an
index
into
the offset portion
segment register
extra
ES
and
for
using the segment override
to force
prefix memory
register,
location.
indexed
operation
the
to refer to the correct
ES
as
Since
there is only one
register, such common operations
copying from one pointer
to another require ES to be reloaded for
each
Pointer references
step in the copying process.
are theremodels.
fore less efficient than in the 2-byte memory
The
and

used
in the
pointers
four-byte
rules:
according to the following
The

D

and

L

models are manipulated

Pointer arithmetic
is performed by adding or subtracting
using a call
32-bit
offset
to a
to the pointer,
allocated
Thus, dynamically
arrays
library routine.
be
by
may
a pointer
subscripting
(addressed
variable)
work properly
larger than 64K, and address manipulations
since the compiler
for
Note that,
all offset values.
requires statically declared arrays (extern,
static, or
only a 16-bit
auto) to be less than 64K bytes in size,
used
accessing
of
is
in
elements
these
arrays,
offset
resulting
in more efficient code.

l.

a

2.

When

two

routine

4-byte
is called

pointers
are
which returns

a

subtracted,
long result.

a

library

3.

pointers
Conversions
between long integers and
4-byte
performed,
again by calling library
are automatically
routines.

4.

Comparison of pointers
for equality
or relative rank is
by
a library routine
which converts
performed
calling
(canonical)
form before
the pointers
to normalized
which have different base
comparing.
Thus, two pointers
and
point to the
but which actually
offset portions,be
same
recognized as equal.
location
will

5.

Any

function

which returns

library routine
normalized
(i.e., offset
calls

a

a pointer
as its return value
which converts that pointer
to
in the range 0 to 15) form.

4-31

Lattice
4.4.5

8086/8088

C

-s Option

The

Four-byte

for

Implementation

Compiler/Run-time

Compiler

É'ointers

use
describe
of
generally
four-byte
overhead of Library routine calls can be
amount
a significant
is
of pointer manipulation
inefficient
A special
on
(specified
being
compile-time
option
performed.
who
work
LCl)
is provided for knowledgeable users
are willing to
certain
Adding the -S flag to LCl causes
within
restrictions.
changes in the above rules:
the following
above

While
rules
the
pointers,
the additional

if

l.

Pointer
a
may

arithmetic

offset
l6-bit
be
greater

is performed by adding or subtracting
no single
object
Thus,
tD the pointer.
than 64K bytes in size.

of the
arithmetic
only the offset portion
affects
When
pointers
(not the base).
are compared for
match of both base and offset portions
equality, an exact
When
only the
compared for relative rank,
is required.
so
is
the comparison
are compared,
offset portions
they are pointers
meaningful
only
to the same array.

2.

Pointer
pointer

3.

when

4.

and
is
Pointers
long integers
are not converted when one
a simple
instead,
amigned to the other;
copy operation
is performed.

5.

The

if

two

portions
a short.

is

pointers

patticipate

return value
not normalized.

are subtracted,
in the operation,

from

a

function

only
and

the offset
is
the result

which returns

a

pointer

be
can
safely compiled
with
the -s option,
Most functions
resulting
in improved code generation
In fact, all of
quality.
C
supplied in the libraries are
written
in
the library functions
allocation
with the -s option,
except,for
the memory
compiled
functionm
Note that the'-3 flag has no effect on the s and' E
models.
"

converting
problem when
the biggest potential
noted
above,
pointers
of the p. and L models is that
to use the four-byte
may
while
pointers
and integers
are no longer the same sizé.
in any way on
appear that a program's source code does Dot depend
that
for subtle problems
this fact, programmers must be alertimportant
cautions:
might relate to this.
Here are three
A8
code

it

l.

4-32

supplying pointer
arguments to C functions,'
practice
to supply a null pointer
(i.e., one
as
does not point to anything)
the #define constant
When
which
compiling
is defined as 0 by stdio.h.
the D or L models, NULL must be changed to DL so
for
is the
the null"poinfer value supplied to functions
as
Failure
size
the pointer
to do this
argument.
address
the called
function
to incorrectly
cause
resulting
in serious problems.
parameters,
when

common

it thatis
NULL,
code

that
same

will
its

8086/8088

Lattice

C

Compiler/Run-time

Compiler

Implementation

is supposed to return a value
allocator
sbrk memory
when
memory
no more
is available
(for compatibility
of
Under
the ,D and .L. models,
with other implementations).
pointer depends
into a character
the result of casting
4.4.4).
on
whether the -S option was used (see Sections
was
compiled without the -s
Since
the
library function
pointer
option,
the
gets converted to the four-byte
The
compiled with the
is that a function
result
format.
value!
test for the
All of
-s option cannot properly
by
be
can
using
the library
avoided
these problems
of
which accepts a long integer number
function
lsbrk,
no morcz
(see
bytes and returns zero
space is available
Section 3.1).
The

2.

-l

-l

-l

-l

if

,L,
The
implemented under the ,D, and
pointers
four-byte
on
the
models allow
access to all of the memory
direct
can
also
but
machine.
This can be extremely useful,
and
8088
be
Memory
on
the 8086
extremely
dangerous.
and
an
values via
storing
is not protected,
processors
can
pointer
crash the system -- or worse.
uninitialized
MS-DOS
of very important
system elements
stores a number
so
that use of an uninitialized pointer
in lower memory,
consequences (such as
to store data can have disastrous
a
for
hard
Table (FAT)
destroying
the File Allocation
,disk!).
Programmers should exercise extreme caution when
Beginnin9
models.
using
these memory
programmers ,a.t.e
where
advised
to use the S o,r. P models,
uninitialized
pointers
less
are much
likely .tg. access critical
locations.

3.

it

4.4.6
Since
maximum

size
t

Creating

Array

an

Greater

than

64K

Bytes

models is limited
data in all of the memory
to
of
bytes, the only way to create an object of greater
functions.
allocation
is through the memory

static
64K

a

values must be
that an array of 10,000 double precision
80,000 bytes of storage will be required for such an
allocated;
array.
First, a pointer must be declared which will contain the
array's
address after allocation:
Suppose

double

"d;

is all that
Note tbat a simple double pointer
the fact
that
will actually point to an
memory
allocation
function

it

is needed, despite
the
Next,
array.

char "getml();
must

be

declared.

function
allocation
Also note that the memory
must be declared to
otherwise,
the compiler will assume
returns
return a pointer;

it

4-33

Lattice

8086/8088

int and
correctly. The
an

d

=

C

Compiler

Compiler/Run-time

shown
operation
the cast
by
array is then allocated

(double

Implementation

below will
not
the expression:

work

*) getml(80000L);

The
size could
also
the L (el) specifier on the constant.
as
specified
(I0000L * sizeof(double)).
(Note:
the size
argument for getml is computed using a multiplication expression,
be
sure that one of the operands is a long constant or is cast to
otherwise,
a
the compiler will
long before the multiplication;
and
an
obtain
the multiplication in short arithmetic
perform
as
the example above is written
incorrect
result.
* sizeof(double)),
((long)(10000
the size argument is incorrectly
computed
as
14464!
Note
be

if

If

returned
pointer,
of course, must be checked for null (zero)
NULL
memory
is
returned
there is
before
not enough
use;
The
d can
now
variable
available
for the requested allocation.
be subscripted
as
were an array,
i.e., d[12] will address
the
etc.
In this example,
the thirteenth (13th) element of d,
number
of elements in the array is less thañ 64K, so ordinary
int
used
had
been
be
a char array
as
subscripts;
can
variables
needed
be
an array
of
allocated,
long integers would
to subscript
object with a size
greater
size. Also note that since anoption
this 64K
be
used.
is being addressed, the -S
cannot
than
The

if

if it

it

4.5

Run—time

Program Structure

under the
of C programs
section
describes
the structure
This
C compiler.
Some
of the Lattice
8086/8088 MS-DOS implementation
8086
and
of the
of the
knowledge
of
the architecture
processor
8086
in order
object
code and linkage concepts is required
to
much
presented.
Readers who
understand
of the information
are
in the precise technical
not interested
details of the hardware
may
implementation
safely skim through or skip over this section;
an
is primarily intended for programmers who
must provÍde
between C and assembly language.
interface

it

postponing discussion
of the specific object code details
(see Section 4.5.1 below), the general structure
create
program is illustrated by the diagrams on the next page.

it

4-34

used

of

to
a

C

8086/8088

Lattice
S

and

P

C

Compiler/Run-time

Compiler

Implementation

Models

High Address

stack
(auto data)

dynamic

<-

SP

<-

DS,

<-

CS

<-

SP

<-

SS

<~

DS

<-

CS

memory

static

data
ES,

SS

f6aoctóom
Low

D and

L

Addre88

models

High Addrem

-

dynamic
memory

8tack
(auto data)

static

data
"——_""

functions
Low

Addre8s

-------

for three basic
kinds
of
which make up the executable
which persist
independently
of
any
which refer to them, and the automatic data
of the functions
is
invoked.
which exist
items
Most
only while a function
one)
implementations
(including
through
support,
library
this
an additional
functions,
dynamic memory
allocation facility which
The
pointers
declared.
to objects
not explicitly
returns
as
one
diagrams
above show the way these allocations
are made;
on
the 8086
might
the auto data items are allocated
expect,
hardware stack.
The

C

programming

language provides

allocation: the instructions
functions,
the static data items

memory

4-35

Lattice

8086/8088

C

Compiler

Compiler/Run-time

Implementation

Two
depending on the size
of
layouts are used,
different memory
the functions
pointers.
In either
are grouped together in
case,
of the address space defined by the program,
the
lowest portion
and
immediately above
the static data items are grouped together
DS,
the segment
registers
the functions.
In the S and P models,
and
SS all.
ES,
contain the same value,
which is the base segment
The
for all of the static data items in the program.
address
SP is
stack pointer
initialized to point to the highest available
is X'FFF0'
value
offset
this
relative to this segment;
and
is adjusted acc: ordingly
sufficient 64Kmemory is available,
remain above the data segment base.
bytes of memory
less than
number
A
which grows
of bytes is reserved for the stack,
certain
The
downward.
remainder of memory
between the end of the static
and
is
items
data
the lowest address allotted to the stack
using library functions.
available
fot dynamic memory
allocation
mechanism
The
in Section 4.5.'5
described
stack overflow detection
used
be
the
from exceeding
can
to prevent stack allocations
and
pool or the
with the dynamic memory
colliding
allotteddataspace
The
feature described in
items.
stack size override
static
the
of bytes to be reserved for
4.1.4 allows the number
Section
when
is executed.
a program
stack to be specified

if
if

L models,
D and
the
the stack resides immediately above
—
by
and
áata
the
free memory
pool (allocated
the
arz·a,
static
described in Section 3.1) is above the stack, which can
functions
DS points
be as
Segment
register
to the base
large as G4K bytes.
SS points
of the static data area,
to the base of the stack, and
SP is
The
ES
stack pointer
is undefined.
initialized to contain
allocated
for the stack (defined in _stack;
of bg"tes
the number
As noted above,
the stack overflow detection
see
Section 4.5.S).
mechanism prevents collision with the static data elements.

In

4.5.1

the

object

Code

conventiom

phase is in the standard
object
file created by the secondcompatible
with
the Intel
object code format,
which is
The
the
object
defines
module format.
object
file
and
instructions
data necessary to .implement the module specified
and
and
relocation
linkage
also contains
by the C source
be
information
necessary to guarantee that the components will
as
addressed
properly when the module is executed or referenced
the
a linked
of
In order to force the parts of
part
program.
object
module into,the proper locations
file
after linking, the concatenation
for
segments which are marked
defines
two logical
same
name.
with other segments of the
The

ms-dos
8086

file,

the
includes
the segment which
segment is
program
by any
functions
instructions
which perform the actions specified
As noted
the
in Section
4.4.3,
defined
in
the source file.
used
segment
name
for the program segment depends on the memory
model.
The

DATA
items which
is the segment which includes all static data
those
This includes not only
in the source file.
are defined
items
data
explicitly' declared static but also items declared

4-36

Lattice

8086/8088

C

Compiler

Implementation

Compiler/Run-time

class
without an explicit storage
outside the body of a function
and
double precision
constants.
string
speCifier,
constants,
on
the stack at
run time
(Auto data items are simply allocated
and
are not explicitly defined in the object file.)
DATA
segment
is defined to be combinable with other segments
the program segment is
of the same name.
In the S and D models,
made
bytecombinable.
Program segments combine with
also
data segments combine
that is, as closely as possible;
alignment,
when
functions
Thus, no space is wasted
with word-alignment.
are
and
alignment
of elements
the word
combined during
linking,
segment
is preserved after combination.
a particular DATA
within
for
alignment
of data items is important
This
efficient data
fetches on the 8086, where word fetches from an odd byte address
a
an additional
four clock periods.
Note that although
require
the
in Section
4.1.1)
allows
(described
option
compile-time
requirement for data items within a particular module
alignment
the word alignment of DATA segments during linking
to be relaxed,
is not affected.
The

at link
net effect of these segment
definitions is andto force,
be collected
data
together
time,
all static
allbe functions tocombined.
Thjs achieves the most important
items to
similarly
segment
The
diagrammed above.
of
the program structure
part
C
needed
directives
to combine assembly language modules with
in Section 4.5.4.
modules are shown
The

Linkage

4.5.2

Conventions

qroup concept is used to guarantee that
linked program does not exceed 64K
and
D models,
is similarly used to force the
section to
into 64K. The groups which may be
The

8086

of the

final

fit

PGROUP
CGROUP
DGROUP

it

" BASE
X BASE
X DATA

segment
segment
segment

+ PROG
+·CODE
+ STACK

the data portion
in the ,S.
bytes;
combined program
defined are:

segment (S model)
8egment (D model)
segment (all modeIM

and
DATA
PROGRAM
segments are obtained from the C modules in
The
as previously
discussed.
other two segments are
the program,
CD.OBJ,
CP.OBJ,
defined
in the startup
module (CS.OBJ,
or
be
during
module encountered
which must
the first
CL.OBJ),
The
two
BASE
forces
segment serves
purposes:
(I)
linking.
PGROUP
is
the
because
lower in memory
(or CGROUP)
first
and
contains a byte
(2)
the startup module,
segment within
The
model
allows
feature
used.
which identifies the memory
latter determine
the
to
programs to be examined with a program debugger The
STACK
used
when
segment
memory
module
the program was linked.
has
defines the base of the stack
a dual
role as well:
(I)
and
dynamic memory
portion
of the data section of the program,
and
type
(2)
satisfies the linker's need for a segment a ofwarning
STACK
the linker generates
(if one is not encountered,
message).
The

it
it

it

it

it

4-37

8086/8088

Lattice

C

Compiler/Run-time

Compiler

Implementation

CD.OBJ,
CP.OBJ,
also
module (CS.OBJ,
startup
or CL.OBJ)
and
The
PROGRAM
DATA
segment
own
segments.
defines
program
its
The
defines the initial execution address of the linked program.
and
the amount
of memory
segment registers
are initialized,
The
above
stack
remaining
the STACK segment is determined.
as
noted
value,
in the
is adjusted
pointer
to its initial
in Section 4.5.
In the DATA segment of the star"tup
discussion
for use
the address of the stack base and top are saved
module,
by the memory
functions.
allocation
At the top of the stack, the
address of the program segment prefix is saved so that an orderly
The
when
be made
can
the program terminates.
return
to MS-DOS
line which executed the program are
from the command
characters
A
from the program segment prefix to the stack.
transferred
pointer
to this copy of the command
line is then passed to the
main,
which begins
execution
of the program
function
(see
Section 5Á).
The

names
extetnal
in Section 4.2.2,
differ from ordinary
in C in
that upper and
lower
case letters are
names
unspecified
equivalent.
are defined as an
All externalno
that is, there is
set of attributes associated with the
type,
one
name;
is simply an offset within
or the other of the two
an error
items
is therefote
defined
to define two
groups.
It
name
the
same
in the same
external
with
the
progtam.
It and is also
programmer's
occurrence
responsibility to prevent thisexternal
make
names
in a
refer
to
to
programs
sure that
way
a function
should not refer to xyz as long
consistent
(i.e.,
when
defined as int in some
other
module).
is actually
External
definition and reference from assembly language modules
in Section 4.5.4.
are discussed
As

noted

identifiers

it

it

how
on
for information
the appropriate
linker documentation
As
a
a
linked
a
public symbol map for
program.
to obtain
name
class
convenience,
the DGROUP
segments are defined with
and
CGROUP
PROG,
PGROUP
DATA,
the
the
segments with class name
segments with the class name CODE.
See

Function

4.5.3

Call

Conventions

it

C function
a call to another
function,
a
first
pushes the values of any arguments onto the stack and then makes
a NEAR
function.
a
call (which changes IP but not
call to that
CS)
is used in the S and .D. models; a FAR call (which changes both
CS)
IP and
is used in the p and L models. The argument values are
order because the stack
pushed in reverse (right-to-left)
grows
downward
function
on
the 8086;
to address
this allows the called (low-address-to-highthe arguments in the natural
left-to-right
The
order.
addre3s)
first actions taken by the called function
are:
makes

When

4-38

I.

The

2.

The

BP

value

register
BP used

of

stack
subtracted

is pushed onto the stack;
by
the caller.

pointer
from

SP

it)

is reduced
the number

by

this

(i.e.,bytesa
of

saves the
v.alue

of

is
stack

ittice

8086/8088

C

Couipiler/Run-time

Compiler

Ímplementation

This value
is
space required by the called function.
is
rounded to the nearest word sq that the stack pointer
The
stack space includes all
auto
always word-aligned.
and
may
declared in the function,
elements
also
data
additional
the temporary
include
storage
space for
expression
during
locations
which
are often required
no auto
evaluation.
items or temporaries
are needed,
this step is skipped; SP is unchanged.

If

3.

was
with
stack
overflow
compiled
the function
for a legal
detection,
then checks the stack pointer
as described
in Section 4.5.5.
value,
If stack overflow
is routed to tbe entry point XCOVF
is detected,
control
by
means
of a jump
in the startup module)
(defined

If

it

instruction.

4.

stack
addressing
arguments,
The

BP
SP
into
pointer
is moved
the stack:
of
the elements on
and
temporaries.
auto storage,

to

indicated
of
offsets
the varÜjUB componenü are
used
of the registers
diagram.
ollowing
Note that
ailing program, only BP is saved.
he

High

-

argumenU

<-

Caller's

<-

BP,

allow
function
by
by

the
the

BP

00e

return
(2
or

callerW

4

addreB8
byte8)
8aved

auto data

BP

items

temporarie8
Low

SP

SP normally
BP and
execution of a C function,
contain the
The
temporaries
closest
value.
to BP,
are allocated
by
in the order
of
ollowed
the auto elements declared,
their
addressing scheme
that
eclaration.
This
has the disadvantage
he
an
supplied
the
function
to
arguments
are at
offset
declared.
etermined
in part by the amount
of auto storage
124
he
bytes of auto
function
declares more than approximately
the arguments require an additional
torage,
offset byte in the
which refer to them.
nstructions

uring
ame

If

a
compensating
advantage
to this mechanism
appears when
and
unction
supplies
with
function
argument
calls another
may
alues.
in special
Because a C function
cases have a
number
example), the
ariable
of arguments (printf is the classic
in pushing
ailed function
the stack space used
cannot deallocate
he

it

4-39

Lattice

8086/8088

C

Compiler/Run-time

Compiler

Implementation

By
the calling function
values;
must do
the argument
so.
C
can
Lattice
functions
retaining
the normal SP value in BP,
restore the stack pointer
after a function call with the two-byte

instruction:

MOV

If

to

BP
SP,

is not
which

SP,BP

set up in this way, a value must be explicitly
a threerequires
or four-byte
instruction.

added

this technique is that
is easy to
advantage
second
to
with
(to be called from C)
implement assembly language functions
oumber
Since the caller's BP contains
of arguments.
a
variabte
pushed
(as
in SP before argument values
the
the value
were
defines the upper limit for the address of any
diagram shows),
saved
words,
only the space between the
In other
arguments.
can
address arjá the address in the caller's BP register
return
contain arguments.

it

A

it

a
function
returns
function
return value,
size of the value returned

When

if

bits
bits
bits
multiple registerthat
16
32
64

In the
Note
of the value.
of
the segment portion
and
in
the base portion

to its caller,
first loads
registers.
into predefined
any,
determines the register(s)
used:

it

the
The

AX register
(AX,BX)
register

pair
(AX,BX,CX,DX) register

returns,
in the
a pQinter

d

quadruplet

AX contains
the
and
L models,

return

value

high

this

order
means

is contained

bits

that
in BX

AX.

adds
the function
the
to sp
the return value is loaded,
Then
BP
on entry.
is popped,
that was subtracted
value
and
a
is
base pointer,
restoring
the caller's
near return
must
The
now
regains control, and
function
executed.
calling
SP
any
argument values were pushed.
restore

After
sanie

if

4.5.4

Assembly Language Interface

modules
for
may
assembly
language
write
Programmers
provided that these modules adhere to
inclusion
in C programs,
and
function
the object code, linkage,
call conventions described
assembly
sections.
In order to facilitate
in the preceding
macro
four
models,
programming for the various memory
language
package.
have been provided as part of the compiler
libraries
be
These
tested for
libraries define values for symbols which can
conditional
assembly purposes, including:
LPROG
DATA

8086
8086

8086
8086
4-40

I for
l for
for
for
for
for

l
l
l
l

p
or L model, 0 otherwise
6 or
model, 0 othew*S8e
S mo&íi,
0 otherwise
F
model, 0 otherwise
6 model, 0 otherwise
k model, 0 otherwise

í

8086/8088

Lattice

defined
Also
beginning and

are

end

C

order

In

be

to

use

used

and

defines
define8
defines
defines

PSEG

these symbols
at the beginning

Implementation

used
to
macros,
data segments:

four special
of the program

ENDPS
DSEG
ENDDS

must
For

Compiler/Run-time

Compiler

delimit

the

start of program segment
of program segment
data segment
startof ofdata
end
end

segment

INCLUDE
an
statement
macros,
module.
of the assembly language

and

example:
INCLUDE

DM8086.MAC

available
the symbol and macro definitions for the D memory
named
DOS.KAC,
an
By
using
the generic include
model.
be
of
the
assembled under any
assembly
language module can
is copied
header
to
as
long as the appropriate
models,
DOS.MAC
before the module is assembled.
makes

file

file

An

to

functions
assembly language module which defines one or more
called from C must define the start of the program segment:

be

PSEG

followed

by

PUBLIC

declarations
PUBLIC

followed

by'

the functions

AFUNC

PROC

of the functions:
AFUNC,

...

themselves:
NEAR/FAR

WO0
ENDP
NEAR
in the
Note that the PROC statement must define the function
The
and
FAR
S and
D models,
function
in the P and L models.
must
detailed
in Section 4.5.3.
conform to the conventions
If a value
be
by
must
be
placed
in the
is to
retutned
the function,
appropriate
register(s).

it

declaration
an EXTRN
from assembly language,
and
the caller must supply
that function,
4.5.3).
any
expected arguments in the proper order (see Section
is
of the EXTRN statements for functions
Note that the position
and
L models,
the
they mast appear before
critical:
lor the P
program segment definitions:

To
most

function
callbe a included

AFUNC

for

EXTRN
PSBG
PROC

For the S and D models,
the program segment:

XYZ: PAR,
FAR

they must appear

after

the

definition

of

4-41

Lattice

8086/8088

C

PSEG
EXTRN
PROC

AFUNC

Implementation

Compiler/Run-time

Compiler

XYZ: NEAR,
NEAR

...

assembly language module may also define data locations
declarations)
from C programs:
accessed (using "extern"
An

Dxl
DX2
DX3

DSEG
PUBLIC
DW
DW
DB
ENDDS

to

be

DXI,DX2,DX3
4000H
8000H

'Text

string',0

the name
the address of an item is to be defined,
that
is used as the operand
with the group name
prefixed
DD
statements.
operator or of the DW or
of the OFFSET
If DX4mustis
used
to define the address of DXl in the example above,
be coded:
Note

must

be

if

if it

it

DX4

DW

DGROUP:

DXI

a segment-relative
Otherwise,
will not
offset is generated, which
be
within
the
is defined
address of the item as
the actual
the prefix is not required for
(NQte:
context of a C program.
ASSUME
LEA
which
refers
to the current
the
instruction,

it

directive.)
to
to refer
Similarly,
EXTRN
appropriate
include

data elements
statements:

EXTRN

XDI: WORD,XD2:BYTE

W
V
0
MOV

AX,XDI

defined

in

a

C

module,

Note that any EXTRN statements for data elements must be defined
previously.
within a DATA segment declaration
like the one shown items.
The
BYTE
used for external
char
If an
attribute rñu8t a be
used
be
a STRUC
word,
to define
element is larger than
can and
used
to fetch
its
or its off8et can be loaded into an index
The
a
same
caution about addresses requiring
component parts.
example:
an
external
reference.
For
group prefix applies to

it,

DW

DGROUP:

XDI

a segmentOtherwise,
used to define the address of XDl.
which will not be
the actual
offset is generated,
of
the item as
is defined within the context of a C
address
for
the LEA
the prefix is not required
Note that
program.
instruction, which refers to the current ASSUME directive.

must

be

relative

4_42

it

8086/8088

Lattice

C

Implementation

Compiler/Run-time

Compiler

(and
and
names
for
lowet case letters for external
symbols within assembly language modules) are equivalent,
C
be
XYZ
as
either
can
called
from
assembly language function
or xyz.
Upper

functions
Assembly
language
any
compiler
does not make
a function
contents following
As

for
be
be

all

an
XYZ

as
the
to preserve BP only,
register
regarding
assumptions
call (except for return values).
need

DS always points
to the base of static storage
noted above,
must
models, so assembly language functions
any of the memory
DS.
In the S and .P, models, ES must also
careful
not to change
preserved
(but not in the D and L Ñodelsj.

Note the differences
models from their
following
example:

between the
in the

usage

in the
pointers
.L.
as
models,

use
of
!2 and

MOV
MOV

BX,[BP].ARG1
AX,[BX]

;get
;use

a

D/L model:

LES
MOV

BX,[BP].ARGI
AX,ES:
[BX]

;get
;use

offset

following

and

S

in

pointer

model:

S/P

The

so

it
and

.P.

the
arg
base

it

example (supplied with the compiler package as the
and
also
many
of the above requirements,
and
DOS.MAC
conditional
assembly fer
the

illustrates
file IO.ASM) the
use
of
demonstrates
memory
models.
different
TITLE
SUBTTL
NAME
INCLUDE

IF
X
X

EQU
ELSE
EQU
ENDIF

PORT
I/O
Copyright

FUNCTIONS
1982
by

PORTIO
DOS.MAC

Lattice,

Inc.

LPROG
6

;OFFSET

OF

ARGUMENTS

4

;OFFSET

OF

ARGUMENTS

PSEG
- kik
ir
O
V
; name
W
W
; synopsis
;
;
e
V
; de8cription
;
O
r
·G**
PUBLIC

IF

inp
c

=

int
int

-- input byte
inp(port);

c;
port;

from port

returned byte
port address

inputs
This function
addre88 and returns

a

it

byte from the specified
as
value.
the function

por

INP
LPROG

4-43

Lattice

8086/8088

INP

PROC
ELSE
PROC
ENDIF
PUSH
MOV
MOV

INP

Compiler/Run-time

Compiler

Implementation

FAR
NEAR

XOR
POP
RET
ENDP
PAGE

BP

BP
BP,SP

;SAVE

DX,[BP+X]

PORT ADDRESS
;GET
;'3ET
INPUT
BYTE
HIGH
BYTE
;CLEAR

AL,DX
AH,AH

IN

INP

C

BP

P
·**
0

V
; name
r0
; synopsis
;

-- output
outp(port,c);
int port;
int c;

;
0
B
;
;
H
V

function
tbe specified

PUBLIC
PROC
ELSE
PROC
ENDIF
PUSH
MOV
MOV
MDV
OUT
POP
RET
ENDP
ENDPS
END

OUTP

OUTP

stack

4.5.5

sends
port.

t-he

specified

character

to

'JUTF
LE'ROG
FAE'

IF

OUTP

port address
byte to send

TFÜs

description

I·**

byte to port

outp

NEAR
BP
BP,SP

;SAVE

DX,[BP+X)
AX,[BP+X+2}

;GET
;GET

BP
PORT ADDRESS
OUTPUT
BYTE

DX,AL
BP

Overflow

Detection

compiler,
by default, generates code at the beginning of each
The
cost in code size for
function
to check for stack overflow.
each
bytes for
function
is 9 bytes for tbe S and D models, and
The
benefit
is elimination
of a very nasty
the P and L models.
When
stack
class of etrors
which can be very difficult
to find.
overflow is detected,
the error message:
The

li

*"*
written

is
ately.
4-44

STACK

OVERFLOW

to the console,

***
and

the program

terminates

immedi-

8086/8088

Lattice

C

Compiler

Implementation

Compiler/Run-time

Stack overflow occurs when the program fails to supply sufficient
number
The
of bytes of storage
for the run-time stack.
storage
location
for which the stack is set up is defined in the external
and
be changed when
the
can
the program is executed by
stack,
Jnnn
The
size of the stack can thus
Option on the command
line.
be
set in any of three ways:

If
l. object

no

definition for
modules during

a
provides
definition
stack
Thus, the default

2.

stack

the

user's

linking,

C
2048

library

is found
in
the Lattice
of _stack containing
size is 2048 bytes.

one
If
definition

of

that

includes
object
modules
the user's
used.
stack,
that value will be
for
is that a statement such as
is required

int

stack

=

a

All

4096;

appear outside the body of a function.
becomes
stack size.
the default
3.

(2K).

That value

then

overridden
at
one
of the above methods can be
Either
by executing
the program
linking)
execution
time (after
command
such as
with a
PROGNAME
The

stack

=8000

sign
decimal
value after the equals
size during execution of the program.

the

becomes

how
Unfortunately,
there is no hard and fast rule for determining
storage
At least as much
stack space a program will need.
amount
the
of
as
of auto storage declared in any
the largest
a
functions
included
in the program will be needed
(i.e.,
much
has
that
an auto array
of 4000 bytes,
function
at least
on
stack space is needed,
because auto data items are allocated
functions,
other
Since C functions
the stack).
typically
call
added
by
function
to that
must be
the called
the storage needed
and
The
needed
by
in supplying the
so on.
intention
the caller,
setting
mechanisms described above is to make the stack
various
adjustable.
size easily

much

if

be eliminated
can
code for stack overflow detection
LC2
on
-v option
source
your
file with the
stack
with
functions
4.1.2).
Library
are supplied
detection
included.
The

by

piling

(SecÉion
overflow

com-

4-45

Lattice

8086/8088

5:
System Library

C

System Library

Compiler

Implementation

SECTION

Implementation

the portable
library functions described in Section 3 of
define a general purpose interface
to the typical
many
provided for C programs,
there are inevitably
which are system-dependent.
variations
In this
some
section,
of the MS-DOS library implementatior
of the details
in order to clarify the peculiarities
of this
are presented
particular environment.

Although

this manual
environment
details and

MS-DOS
Fortunately,
of powerful features which
supports a number
a full
allow
implementation
of the standard file I/O functions,
a
minor
although
the representation
of text
files presents
problem; Section 5.1 discusses file I/O.
Several standard device
and
C
names
I/C
by MS-DOS,
supported
the Lattice
are also
in special
explained
interface
these
processes
ways, as
ir
The
C
Section
5.2.
of Lattice
structure
programs (see Sectior
memory
functions,
althougF
4.5) allows the full set of
allocation
aj
care must be taken to provide sufficient space for the stack,
The
Section
basic program entry and exit functiom
5.3 warns.
and
some
unique
in Section 5.4,
special functions
are described
As
5.5.
to the MS-DOS implementation
are presented in Section
be
additional
provided as the compiler
functions
wilt probably
evolves,
the programmer should check the addendum
for the current
version of the compiler.

5.1

File

Filenames

I/O
are specified

according

to the following

format:

d:\pathname\filename.ext
d,: .

where
directory
is
the
currently
current

is an optional
specifier,
file extension.

drive
filename

If

pathname is an optional
specifier,
and
is the name of the file,
,±u!
the
the drive specifier is omitted,

the
logged-in
disk is used;
the pathname is omitted,
The
specified
without
directory
is used.
filename is
8
than
the extensior
less
characters;
trailing blanks
one
is not defined for ttiÉ
(including
the ".") must be omitted
may be
supplied
in either
Alphabetic
characters
upper or
file.
lower case;
Only
actual filenames use upper case letters only.
those
characters
which are legal for filenames under MS-DOS
are
documentation
acceptable;
consult
for
the MS-DOS
details.
names
seE
Certain
are recognized as devices rather than files;
Section 5.2.

if

if

if

level I I/O functions
perform disk I/O by making direct calls
so
is performed by the operatinc
that all buffering
to MS-DOS,
system.
Programs using the level 2 I/O functions
cannot use the
rbrk function,
using getmem.
a buffer
because fopen allocates

The

In the MS-DOS
fclose)
getc,

implementation,
the level

and

l

both the level 2 (fopen,
putc,
read, write, close)
(open,
creat,
5-I

Lattice

8086/8088

C

Compiler

System

Library

Implementation

I/O

functions
including
to 20 open files,
devices,
are limited
including
(stdin,
the
three
stdout,
stderr)
which are
opened
automatically
for the main program.
Note that the number
by the
of files available
under MS-DOS version 2 is also affected
CONFIG.SYS
file,MS-DOSsince an MS-DOS file handle is used for every
open
documentation).
(see
and

file

The

portable
option when
a
library provides a system-dependent
is opened
the programmer may select one of two
or created;
file
modes
of I/O operation
while a
is open. On some systems the
modes
but in the MS-DOS implementation
they
are in fact the same,
differ in some important details.

file

condition.
Translated
In this mode,
or text mode is the default
normally used by C programs (a single newline
the line terminator
is
\n or 0x0A)
line
character,
translated
to the MS-DOS
terminator,
which consists
of the two characters,
carriage
return
and
(0X0D
This
linefeed
fcñlowed by
0X0A).
translation is
when
performed
the file is written using calls to the write
is performed when the
the inverse translation
library function;
programs which use
file is read using the read library function.
(putchar,
the higher level I/O functions
getchar,
printf, etc.)
but programs which call read and write
not affected,
ate usually
On
of these translations.
read calls,
the
directly must beware
be
by
may
returned
less than the actual number
of
count
bytes
CR
was
which
the file position
advanced (because of
deletions).
Note that all carriage
returns are discarded when reading from a
mode;
file in theCR/LFtranslated
similarly, all linefeeds
are
when
expanded to
writing to the file.
Untranslated
selected
or binary mode is an option which can be
By adding
0x8000
the file is opened
to the mode
or created.
mode
the open call or to the access privilege
for
word for
the
indicates
operations
creat
that read/write
call, the programmer
on
the file are to be performed without
In this
translation.
mode,
bytes
between the caller's area and
the
are transferred
This option must be used for
file without modification.
files
containing
binary data; otherwise data bytes which happen to take
on CR and LF values
will be translated incorrectly.
when

two
other
In addition
to the file I/O modes discussed
above,
The
should be clarified under the heading of file I/O.
functions
function
creat
gets a system-dependent
the access
argument,
these
under the Ms-nos
are ignored
privilege mode bits;
which,
implementation,
except for bit 15 (the 0x8000
set,
bit)
mode.
the file to be accessed in untranslated
or binary
causes
The
has
mode,
an offset
lseek function
implemented,
not always
Because
an
which specified
to the end of file.
relative
offset
mode
MS-DOS
retains
the exact file size in its directory,
this
be and is implemented
can
in this version.

if

5.2

Device

Several
interface
S-2

I/O

special
under

file

MS-DOS,

names
and

are checked for by
processed using

I/O
the Lattice
single
character

Lattice

8086/8088

Compiler

C

System

Library

Implementation

These
device names may be specified
in either
reads and writes.
but will be recognized by the level l open
upper or lower case,
and
suppliéá.
the trailing colon is
only
creat functions
the colon is omitted,
the name is passed to the operating
system
and
by
be
may
processed specially
however,
the level
l
functions
deal with a device reference sans colon as
will
The
device names recognized are
were a reference to a disk file.
as
follows:

if

If

it;

Console

CON:

printer
Aux

PRN:
AUX:
NUL:

port

Null

,,,

if

LST:
COM:
NULL:

,,

LPT:
RDR:

,,

if

LPTI
PUN:

I/O is performed to these devices, one character
at a time, using
BDOS
One
function
the appropriate
exception
occurs
calls.
for
mode
,r.e.a.d. operation
a translated
the console device:
requests
more
is
than l byte,
the BOOS buffered console input function
used
Any
of 128 bytes
to read the data (a maximum
per read).
by
special
editing
features
supported
the operating
system
be
enabled.
(backspace processing,
etc.) will therefore

if

The

following
table
functions
used for
modes.
untranslated
Device
Name

lists

read

the devices and the corre6ponding
write operations
in translated

and

Translated Mode
FN
Write FN

Read

l3

CON
AUX

corn

3

PRN

—
—

LPTI

2
4
4
5
5

BDOS
and

Mode
Untranslated
Read
FN
Write FN
7
3
3
—
—

6
4
4
5
5

NUL

number
function
indicates
the
that
the correspondiDg
- for
The
operation
is not supported for that device.
read function
end
of file (count = D)
read is not
supported.
returns
the write function
returns a normal
writing is not supported,
indicating
but does not actually
send the data.
count
success,
An
by
NULL
a
additional
special device name,
specified
string
which consists
of just a '\0'), is recognized and processed
("",
had
CON:
as
been specified.
A

If

if

if

mode,
(0x0A)
a newline
is converted to a carriage
In translated
A
return/linefeed
on
input
is
carriage
return
sequence.
and
converted to a newline,
terminates
the read operation
even
mode,
the
byte
is
count
not satisfied.
In untranslated
do
and
characters
read operations
are sent without modification,
has
been
terminate until the requested number
of characters
not
received.
in
a
Note that
read operation
to the console
mode
does
untranslated
received.
not echo the characters

if

Programmers

may

also

perform

direct

single

character

I/O
5-3

Lattice

8086/8088

operations
functions

using
support

details.
If one of
and

Compiler

C

the

direct

System Library

and
bdos function,
I/O to the console.

Implementation

several
additional
See
Section 5.5 for

these devices is opened
for access using
fopen,
input
which means
output
that
are performed in unbuffered mode,
The
single
characters
only
are received and sent immediately.
exception
to this rule occurs for stdin, which main opens
in
mode
be
so that
buffered
can
the buffered console input function
mode
desired,
used.
stdin can be changed to the unbuffered
see
using setnbf;
Section 3.2.2 for more information.

If

5.3

Memory

The

full set of memory
3.1 is provided under

l.

+

Allocation
allocation
MS-DOS.

The

functions
following

described
cautions

in Section
apply:

and
rstmern
functions
The reset
rbrk cannot be used
on
any of the level 2 I/O functions
are also being used
disk
only
Note that
currently open
files.
files
block using getmem;
the reset
allocate a mayfilebe access
used
open
functions
the only
files are
A
be
may
closed,
actually connected to devices.
file
then
re-opened
after
the reset
function
is called;
be
however,
updated
must
any file pointers
this is
because there is no guarantee that the same value
done,
be
when
opened
returned
the file is
again.
will

if

if

if

2.

used
by
dynamic memory
The
the memory
allocation
used
functions
is
the same memory
for
the run-time
be
enough
stack.
careful
Programmers must
to provide
for
the stack to prevent its collision with
the
space
by getting
an override
dynamic memory
pool, either
value
command
by
from the
defini'ng
line (see Section 4.1.4) or
an external
int location called See_stack and initializing
a
with
desired value.
Section
a
4.5.5
for
complete discussion
of the stack size.

it

3.

Programmers

allocation

the
startup
available:

who
wish to implement
their own memory
can
functions
refer to the data locations
in
module which define the total stack
space

extern

umigned

_base;

contaim
the offset (from
of the lowest portion
the
stack,
which is the same as the highest offset
the
static data items in the program (see diagram
Section 4.5).
DS)

extern

unsigned

of
of
at

_top;

contains,
in the S and P models,
the offset of the top
of the stack,
either
X'FFF0' or whatever was determined
to be the highest usable offset; in the 9 and L models,
5-4

Lattice

8086/8088

C

Compiler

System

Implementation

Library

for the stack
contains the number
of bytes allocated
As noted above,
as
the external
location
stack).
size
contains
stack
stack
the default
or specified
aesired;
memory
may
user-written
allocators
wish to make
use
of that value, as a convenience.

it

(same

5.4

Program Entry/Exit

The

CD.OBJ,
(or CP.OBJ,
startup module CS.OBJ
or CL.OBJ)
calls
and
a copy
main to begin execution of a C program,
passes to
which
executed
the
Actually,
the command
program.
line
of the
does not save the program name portion
because MS-DOS
command,
consists
of the
the command
line passed to main
"c " (lower case 'c' followed by a blank) immediately
characters
by
name.
followed
all of the characters typed after the programanalyzes
The
standard version of main supplied in the libraries
in Section
the command
line for all of the elements described
and
then passes the command-line arguments to main.
4.1.4,
and
the stack override
features are not needed,
file specifier
be used
can
instead.
Please
the version supplied as TINYMAIN.C
important cautions
note the following
this is done.

it

Of

If

if

I.

2.

sends its output to the prelibrary function printf
which is normally opened
by
stdout,
defined file pointer
function
main.
the code that performs
this
is
If
Femovecí,
produce no visible output
printf calls willignore
I/O
functions
read
(the
attempts to
or
library
a similar
write unopened
caveat applies to the
files).
use
of 8canf, which reads from stdin.
If the goal is to avoid including the level 2 I/Q
functions
in the linked program,
the library function
since it closes all buffered
exit should not be called,
and
execution
terminating
before
output
file
be
2
The

automatically
causes level
Call _exit instead.

functions

to

included.

program exit functions
exit and exit are aescFibed irt
The
Section
thq
3.2.4.
error code argumenf is passed back to
operating
where
system,
can be tested in a batch file using d
command
such as:

The

it

if
5.5
The

to

and

Special

error

level

I

goto error

Functiom

functions
discussed in this section provide low-level
access
They
machine-dependent
various system resources.
tend to be
not portable.
are therefore

5+5

Lattice

8086/8088

C

Compiler

System

Library

Implementation

NAME

bdos

-- call

BDOS

function

SYNOPSIS

ret
int
int
int

=

bdos(fn,dx);
returns code
BDOS
number
function
dx;
value to be placed in

ret;
fn;

DX

DESCRIPTION

Performs
the DX
returned

placing fn in the AH register,
INT
21H.
The
an
operating
in the AX register
is passed back as

BDOS
call andby
register,
by BDOS
a

in
value

dx

ret.

CAUTIONS

the D and L models,
is better
intdosx
In
to use the
aescri6ed
function
calls need
next, since some BDOS function
a pointer
which may not contain the
defined relative to DS,
correct
segment base in these models.

it

5-6

8086/8088

Lattice

C

Compiler

System

Íjibrary

Implementation

NAME

intdos,

intdosx

--

generate

DOS

function

call

SYNOPSIS

ret
ret

=
=

intdos(inregs,
intdosx(inregs,

int ret;
REGS

union
union
struct

REGS
SREG

'"inregs;
*outregs;
"segregs;

outregs);
outregs,

segregs);

operating
system return code
input registers
output registers
(intdosx only)
segment registers

DESCRIPTION
DOS function
a
Generates
request to the operating
system.
The
should be
checked to
operating
system specifications
and
determine the DOS functions
callingusedsequences supported;
as
inputs.
in the registers
the values
In
are
by
function
request is specified
particular, the exact
MS-DOS,
one
(under
the
of the registers
placing a value in
number
in AH;
is specified
in CL).
function
under CP/M-86,
inregs must contain the values which will be loaded into the
made;
function
working registers
before the
outregs
call is
will receive the values in the registers
after control
function
with
intdosx,
the values
request.
returns from the
be placed
in the segment
registers
before
the
which will
be
SREGS
may
specified;
although the
interrupt
structure
only DS and ES will
defines
of the segment registers,
all
The
be
SREGS
REGS and
actually
loaded.
structures
are
defined in the DOS.H header file.
CAUTIONS

Defining
the
acco%lished
(see below for

values for intdo8x
segment register
segread to obtain
current
calling
details on this function).

by

is

best
values

and
Note that inregs, outregs,
segregs are shown as pointers
above;
the usual technique is to declare them directly, and
then use the address-of
to them.
operator to pass a pointer

S-7

Lattice

8086/8088

C

Compiler

Library

System

Ímplementation

NAME

int86,

int86x

--

generate

8086

software

interrupt

SYNOPSIS

int86(intno, inregs,
int86x(intno, inregs,
int intno;
REGS

union
union

"inregs;
REGS *outregs;
struct SREGS "segregs;

outregs);
outregs,

segregs);

interrupt

number

input registers
output registers
segment registers

(int86x

only)

DESCRIPTION

Performs an 8086 software interrupt of the specified
number.
operating
the
system should be checked to determine
supported;
generally,
interrupts and calling sequences
must
inputs.
inregs
in the registers
values
are used as
contain
the register
values which will be loaded into
the
is performed; outregs
before the interrupt
working registers
receive the register
from
values after control
returns
with int86x,
the values which will be placed
the interrupt.
before
in
the
the
segment registers
interrupt can be
defines all of the
specified;
although
the SREGS structure
be
only DSand ES will actually
loaded.
segment registers,
The
and
REGS
SREGS
in the DOS.H
structures
are defined
header file.
The

yill

CAUTIONS
on
interrupts
the 8086 are used to implement
and
system processing,
invalid input data can
(and
disastrous)
occasionally
results.
cause unpredictable
values for int86x
is best
Defining
the segment register
by
accomplished
segread to obtain
values
current
calling
(see below for details on this function).
The

software

multi-level

and
as pointers
outregs,
Note that inregs,
segregs are shown
above;
the usual technique is to declare them directly, and
then use the address-of
to them.
operator to pass a pointer

5-8

8086/8088

Lattice

C

Compiler

system Library

Ímplementation

NAME

segread

--

return

current

segment register

values

SYNOPSIS

segread(segregs);

struct

SREGS

"segregs;

structure

for

return

of values

DESCRIPTION
8086
into
the
values
the current
segment register
whose
pointer
is supplied.
structure
Its a main purpose
make
subsequent
is
to obtain current values in order to
definition for the SREGS
call to int86x or inintdosx.DOS.H Theheader
is found
the
structure
file.

Places
SREGS

5-9

Lattice

8086/8088

C

Compiler

System

Library

Implementation

NAME

movedata

--

move

data bytes

from/to

segment/offset

address

SYNOPSIS

movedata(sseg,
irjt sseg;

soff;
int dseg;
int
int doff;
unsigned nbyte3;

soff,

dseg, doff, nbytes);
of source address
segment portion
portion
of source address
offset
of destination
address
segment portion
portion
of destination
address
offset
number
of bytes to move

DESCRIPTION
number
the specified
of data bytes from the source
to
The
as
address.
addresses must be specified
the destination
in accordance with the standard 8086 nota(segment: offset)
This function
is primarily intended for use in protion.
L
using the S and P models;
in the D and
grams compiled
models,
the standard library function movmem can be
used.
The
be used to obtain
can
segread function
segment register
values.

Moves

CAUTIONS
Memory

is

parametem

5~

I0

on
not protected
to this function

invalid
the 8086, so supplying
results.
have disastrous

can

Lattice

8086/8088

Compiler

C

System

Library

Implementation

NAME

peek, poke

--

examine/modify

arbitrary

memory

locations

SYNOPSIS

peek(segment,
poke(segment,

int segment;
int offset;
char *buffer;

unsigned

offset, buffer,
offset, buffer,

nbytes;

nbytes);
nbytes);

segment portion

of memory
address
of memory
address
buffer
of bytes to transfer

portion
offset memory
local

number

DESCRIPTION

functions
copy data values between an arbitrary memory
and
a local
memory
location
buffer:
peek moves data to
the
memory
address,
while
poke
local
buffer
from a specified
moves
data
from the local buffer to the arbitrary memory
These
intended for use in
functions
address.
are primarily
.L.
in the ,D, and
programs compiled using the .S. and E models;
models, the standard library function movmem can be used.
These

CAUTIONS
on
is not protected
the 8086, so supplying
have
can
disastrous
parameters to the poke function
Memory

invalid
results.

5~

lI

8086/8088

Lattice

C

System

Compiler

Library

Implementation

NAME

inp,

outp

-- direct

I/O functions

port

SYNOPSIS
= inp(p);
outp(p,v);
v

int
int

v;
p;

I/O value
I/O port

number

DESCRIPTION

reads I/O port p and returns whatever
inp function
The
writes value v to port p.
is there.
outp function

The

data

CAUTIONS

operations
Direct
port
damage
physical
including
be
exercised.
should

5~12

can cause all sorts
systemm
to some

of problems,
Extreme care

8086/8088

Lattice

C

Compiler

Error

Messages

APPENDIX
A:
Error Messages

by
appendix
describes
produced
the
the various messages
and
which
second phases of the compiler.
Error messages
with the text CXERR are compiler errors which are described
in Appendix B.

This

first
begin
A.l

Unnumbered

Messages

describe error conditions
These messages
than errors
in the source
rather
language specifications.

file

Can't

object

create
The
.OBJ
on

Can't

file

second phase of the compiler was unable
file. This error usually results from
the output disk.

phase of the compiler
This error usually results
file.
the output disk.

first

The

The

File

unable to create the
from a full directory

was

.Q
on

file

file
drive/directory.
open
source file
The
first phase of the compiler
Lcl command,
file specifiedon on the specified
exist
the
not
drive/directory.

it

.C
unable to open the
did
usually because
logged-in)
(or currently
was

it

missing

name

file

not specified

the LCl or

LC2

file error
first phase of the compiler encountered
writing to the .Q file. on This error usually

an

A

the
create
directory

full

.Q
second phase of the compiler was unable to open the
on
specified
the LC2 command,
usually because
did
on
exist
logged-in)
the specified
(or currently

not

Can't

quad

open

to
a

file

quad

create

Can't

in the environment,
due
improper
to

name

was

on

command.

Intermediate
The

out-of-space
Invalid
An

command

condition

line

invalid on

specified

the output

disk.

when
error
from an
results

option

command

either

a
line option (beginning with
-)
command.
the LCl or the LC2

was
See

A-I

8086/8088

Lattice

C

Compiler

Error

Messages

and
Sections
4.1.1
line
4.1.2 for valid command
options.
is ignored,
is not otherwise
option
but the compilation
affected.
In other words, this error is not fatal.

The

No

or data defined

functions

which did not define any functions
or data
processed by the computer.
This error
always
be generated
can
execution of the compiler.
by
comment,
which then causes the
forgetting to terminate a
as a comment.
compiler
to treat the entire

A

source
elements
terminates

was

file

It

file

Not enough

memory

This message
is generated when either
phase of the compiler
The
working memory.
onLy cure for
uses up all the available
memory
on the
to increase the available
this error is either maximum
is already available)
reduce the
system,
or (if the
size and complexity
of tbe source file.
large
Particularly
much
functions
of how
generate this error regardless
will
memory
is available;
break the task into smaller
functions
this occurs.

if

file

object
The

error

second phase of the compiler encountered an error
This error usually results
to the .OBJ file.
on
out-of-space
condition
the output disk.

writing
an
A.2

Numbered

Error

when

from

Memages

describe syntax or specification
in
These error messages
errors
they ate generated by the first phase of the
the source file;
few
a
remark on
compiler.
are warning messages that simply
constructions
acceptable
but do
the
marginally
not prevent
See
more
creation
Section
4.3.3
of
the quad
for
file.
information
about error processing.

I

This
is generated by a variety
of conditions
in
error
commands,
including
specifying
with pre-processor
connection
command,
an
unrecognized
failure to include white space
elements, or uge of an illegal pre-proce3sor
between command
symbol.

2

The

3

The

end
of an input file was encountered when the compiler
expected more data.
This may occur on an tinclude
file or
correction
of a
the original source file.
In many cases,
previous error will eliminate
this one.

found.
4

A-2

file

name

specified

on

an

Unclude

command

was

not

unrecognized
input
element was encountered in the
file
lexical
could
that
not be classified as any' of the valid
an
(such as
constructs
identifier or one of the valid
An

Lattice

8086/8088

C

Compiler

Error

Messages

if

expression operators).
This may occur
control
characters
or other
illegal (i.e., high bit set) characters
are
a pre—
detected in the source file.
This may also occur
command
with the t not in the
is specified
píocessor
first
position
of an input line.

if

tdefine

5

A

6

Expansion
of a #define macro caused
This may occur
buffer to overflow.
macro
appears on a single input line.

pre-processor
of arguments.

macro

was

used

if

7

The

maximum

the compiler
4.

extent of iinclude
supports tinclude

file

nesting

with

the wrong

the

compiler's
line
than one lengthy

more

nesting
to a

number

exceeded;
depth of

was
maximum

specified.
conversion was
or pointer
invalid arithmetic when
an
This
usually
results
attempt is made
to convert
something into an array, a structure,
or a function.

8

An

9

The

in the context
identifier was undefined
that is, it had not been previously
message
is only generated once;
subsequent
with the identifier assume
that it is of type int
cause other errors).
named

it appeared,
This

in which
declared.
encounters
(which may

[
was
following
detected in the expression
the
error
expression).
may
character
(presumably a subscript
This
in brackets is NULL (not present).
the expression
occur

10

An

II

The
length of a
constant exceeded
(256
by
the compiler
bytes).
This
"
(quotes)
omitted in specifying
the

12

expression
preceding
the . (period) or -> structure
by
reference operator was not recognizable
the compiler as a
This may occur
structure
to a structure.
or pointer
even
by
see
which are accepted
for constructions
other compilers;
Section 2.1.

13

An

if

string

will

are

maximum

if
string.

allowed
the closing

The

identifier indicating
the
not found following

.

the desired aggregate
(period)
or -> operator.

indicated
identifier was not a member of the
or union to which the . (period)
or -> referred.
for
constructions
which
occur
are accepted
see
compilers;
Section 2.1.

14

The

15

The

not
16

the
occur

identifier
implicitly

preceding
or

explicitly

the ( function
declared as

a

member

structure
This may
by
other

call

operator
function.

function
following
argument expression specified
function
This may occur
call operator was invalid.
argument expression was omitted.
A

was

was

(

the

if

an

A-3

Lattice

17

8086/8088

Compiler

C

Error

was
During expression evaluation,
the end of an expression
encountered
but more than one operand was
awaiting
may
an expression
evaluation.
This
contained
an
occur
incorrectly specified operation.

still

if

18

19

evaluation,
the
an operator
was
an operand was

During expression
but
encountered
may
This
occur
operation.
L
The

number

expression
occur

if

20

Messages

if

of

opening
not equal.
macro was poorly

of

an

expression

was

pending
evaluation.
stillomitted
for
binary
a

closing
in an
parentheses
message
This error
may
also
specified
used.
or improperly

and

was

a

end

was
expression
which did not evaluate to a constant
encountered
in a context which tequired a constant
result.
may
one
This
of the operators
for
not valid
occur
was
constant expressions
present (see Kernighan and Ritchie,
Appendix A, p. 211).
An

if

21

union,
or function
identifier declared as a structure,
without
being
encountered
in an expression
properly
(by
a
reference
structure
or function
qualified
call
An

was

operator).
22

This non-fatal
warning occurs when an identifier declared as
a structure
argument without
or union appeared as a function
the preceding & operator.
Expression evaluation
continues
ássumed
&
with
the
(i.e., a pointer to the aggregate is
generated).

23

The

occur
when
?4

conditional
the
expected.

if

?

operator was used
is present
operator

context

if

an
required an operand to be
context of the expression
&
may
was
This
lvalue.
following
the expression
occur
an
lvalue,
side
of an
assignment
the left
not
or
was
expression
not an lvalue.
The

if

26

27

The

of
context
arithmetic
(not

a

if

required an operand
the expression
function,
pointer,
or aggregate).

required
of
the expression
context
This
arithmetic
or a pointer.
logical OR and logical AND operators.

The

either
28

A-4

This may
not found

a
required an operand to be
of the expression
following
* did
This may occur
the expression
not evaluate to a pointer.
The

pointer.
25

erroneously.
but the : was

During
expression
encountered
but

evaluation,
not enough

the end
operands

an
may

to

be

operand to be
for
the
occur

of an expression
were available

was

for

Lattice

8086/8088

evaluation.
improperly

Compiler

C

This
specified.

may

Messages

Error
occur

if

a

was
specified
which was
operation
operands
(such as one of the arithmetic
than addition).

binary

operation

invalid

for
operations

is

pointer
other

29

An

30

when
warning
in an
This
non-fatal
assignment
occurs
a value
a
for
pointer
defining
variable,
statement
the
on
side
expression
of the = operator
did
the right
not
same
of the exact
evaluate
to a pointer
type as the pointer
did not point to the same
variable
being assigned,
i.e.,
See
Section 2.1 for an explanation
of the
type of object.
philosophy
behind this warning.
Note that the same message
becomes
genera€e^Ljj
my leMing 'diite
the
bIaí1k3
tabs)
then
and
and
per form
cuñv€Tsion.
'Ihe conversion
stops
at the f irst
character, and no check is rnMe for overflow.
Fbr

atof,

may

be

(i -e.
appropriate

space

ímrecognized

pint

the ASCII
and
a decimal
string may contain
signed
Followed
by
integer
a
an e or an E arid
leading
minus
For
exµmimt.
sign indicates
all functions, a
negative
noit±er.
\díite space is not allowed between the
¿ninus
the
and
the
number
betwem
number
and
the
sign

j

or

?KEjonent*

16

8086/8088

Wttice

C Ccmpiler

SuWlanmt

for

Version

2.10

bQWE

strtol

—

t

eonver

ASCII

to

long

integer

SJQK)FSIS

r

=

strtol(s,p,base);

long

resul t
strim to be scmned
returns pointer to

r;

áar *3;
char
**p;
int base;

conversion

terminating

character

base

[EsaunIcN
an ascii strim
ibis fmction converts
into a lom integer.
Leatlinj
usim the sFecified number base for the conversion.
aM
the
rdiite space
(i.e. blanks and tabs) is skipped,
conversion
proceeds
unreccgnized
character
is hi t.
m
mtil
The
in p.
pcñnter
character
to the unreccgnized
is returned
If no conversionbe 0. can be performed, p will contain s, and the
result will
base can be in the ranje from 0 to 36.
If
then
the
ASCII
digit
str ing may contain
frcxn
throcgh
the letter A
0 throüjh 9 and
as
many letters as necessary,
with no distinction made between
then
tiií-'
and lower
base is !3,
For exanple,
tpper
case.
allowable
9 and A,i3, and C '-k
are 0 through
digit characters
leading
"Ox" or "OX" may
base
then
a
a, b, and c.
is 16,
in the string.
appear
The

conversion

is

non-zero
characters

it

,
frorn

if

If

the leading
then
characters
of the stxifYj are
1eMin;j
determine
the conversion
base.
a
O
(base
Ox or
8)
while a leeding
indicates octal conversion
,
conversion
(base
16)
A leadin'j
DX iMicates hexMec iinal
.
(base
ID)
digit from 1 to 9 indicates decimal conversion
.

If base
exanined

is

0,
to

17

Lattice

8086/8088

Súfpimmt for

C Ckmpiler

Version

2.10

NAME

ecvt --

convert

floatiW

point

to

ASCII

SYNOFSIS
p =
char
double

ecvt(value ,ridig ,dec,sign) ;
pinter

*p;
value

;

to

to ascii
convert

strim

of digits in string
returns position of decimal

int ridig;
int *dec¿
int "sign;

This

value
nunber

if

non-zero

fmction

point

negative

the specified value
into a nullthe specified number
off
string cQntainim
then contain the
to by dec will
integer pointed
its. 7helocation
relative
of the decimal point, with a negative
meaning
value
is to the left of the
that the decimal
dig
returned
'The actual
decimal
its.
point character is not
txied
the
generated
incl
in
string.

terminated
dig

converts

ASCII

18

Lattice

8086/8088

C

Qmpiler

Supplanmt

for

Version

2.10

NAME
matherr

math

haMle

--

fmction error

SYNOPSIS
code

=

mtherr(x)

int code;
struet exception

;
non-zero
for new return value
math exception
block

*x;

ImmIprIcN
flhis fmction is called whenever one OE the other
receives
Upon entry,
functions detects an error.
exception
block
the
that describes
in detail.
error
as follow:
in math.h,
structure is defined

it

struct

mat-h
the

'M3

exception

{

int type;

error

char
*nane;
double
argl;
arg2;
double
double
ret;
9:
The

error

type

DCMAIN
SING
(NERFLKM

FLOSS

nanes
=>
=>
=>
=>
=>
=>

type

of fmction

having
argunent
second
argunent
proposed
return value
nane

f irst.

defined

in

math.h

error

are:

domain

error
singularity
overflow
under f low
total loss of significance
partial loss of significance

matherr
is called , the fmction that detected
have
placed
its proposed
return value
exception
you want to substitute
structure.
code.
value, then matherr mwt return a non-zero
Hjctj

will

If

If you do mt supply a version of matherr,
version will put the appropriate error nurber
return a cede of 0.

19

the

a

the

into

error
into the
different
stand
errno

ard
and

Lattice

6.0

8086/8088

C Ckmpiler

FQRFYEXEC c~IbuLTIcN

for version

SuEpl%mt

2.10

EUETIcFí6

behaves
2 contains
a systm call tmt
like a
1hat
LNIX fork and exec functions.
is,
of
module.
IOM
which
executes
creates
a specified
a "child" process
canpiletion
the
!Ihe
child's
"parent" process can @n retrieve
cede via another
new systan
call that is similar to the INIX mit
unct
ion.
f
Version

it

+

combination

Version
MS4jOS
2 does not
course
really sL«ort multi,
do
prcgrarmirg, arid so the parmt and child processes
not
swpeMed
the ccmpiter
Uie j;ár«jt umains
actuaiiY timeshare
.
terminates.
Ebwever
is
multi-progr=im
child
,
mtil the
added
MS4X)S in the future,
tD
we expect
that the interface
provided
in our library will te maffected «cept tMt the parmt
will nc> lomer be totally out of bminess while ttm child
Qf

if

executes

.

new ftnctions described
followiW
in
reviewiW
manual
pagm
jpu might mrüer u}y we did not providesimply m exact
The mswer
is
equivalent of LNIX's fórk fmction.
tmt 1Ñe
could
way to
repl icate the parmt
not figure out a general
aídress
8086.
process'
spa: e on the
typical
s
mt is,"'"j"' ""'" nuúbers,
prcqran
oFeratim txüer MS-4XJS contains absolute
impossible
which
nakes
to move tie progran
for mecution in
another
area of mmory.

«

~

After

~

it

Meukky

Manqjanmt

CNuige

hM to chame
the FÚRK/EXEC capebility,
In order
to implanmt
approach
S and p
to mmory
our
allocation for
mdels.
Version
2.0
with the
of Lattice C rwained fully cxmpatíhle
wallmw:
versions
by
the
stack
as
high as
del
placing
earlier
possible
in the data segmmt and by µlacing the inanory pxíl {i .e.
the Static data
between
and
the "heap")
area
stack. However ,
placed
tm
with Version
for the D and L mdels intrcxíwed
2.0,
the static data
above
and male all
stack
rmainirg
imediately
stack
heap.
above
the
the
manory
available for

=

¶

~

r

just above the static data
2.1, the stack is located
models.
\kder
MS-DOG
2,
mmory
thm,
start-up
the
(see " c./Lqq)
to
returns all umainirg manory space
systan
so that there
is roan to create a child process.
Ken
anotnt
you call djrk,
will attenpt to obtain tte
of space back frcm MS-DOS, and when you call rbrk, the space thw
other
obta int-d
In
will once .again be givm back to MS-DC6.
'rjrcis,
the manory
allocation functions will appear to operate as
Version
2.0 cñ the compiler, but in fact tjñey will
'íey did íxíder
.e much
closely coupled to the operating systm.
In
for

Version

~

all
µo;jran
operatirrg

r~ired

it

mjte

Che

fly

terminate
Farent

in

may

the

but

f

ointmmt is that a child process cm cMose
remain
resident in memory.
that happens,
irid
the
that its heap cannot grow because

If

20

to
the

child

Lattice

8086/8088

C

Qmpiler

MPlmmt

for

version

2.10

process
is in the my. lb help avoid this problan, @!ve added a
'Ihis
integer
global variable called meed .
is simply a long
that sµecifies the minTnun nunber of bytes neMed in the heap.
each
time
and
meed
At
yum call
rbrk,
is
star t-up time
consul ted
sufficient sµce cannot be allocated, trié start-uµ
.
If
aborts
µrcgran
Ñjt2 that ydli
or rbrk returns a -l failure ccxie.
WbC£Xj each time
can charge
jpu call rbrk.

Finally,
directly

if

referenced
the
wbase
and
you
pinters
mext
the tnmory
al1&ation functions,
witMut goiW throWh
be
aware
that these are both 4-byte pointers cxxIer all memory
mcxiels.
This
impl les that
the S ard
under
thés<-·
P models
.The sbrk
as [6-relative
pointers sMuld not be treated
offsets.
aMs
the
fmction
of
in order to return
top to
first mrd
Also
a
N-relative offset tD you.
that the heap
, sbrk ensures
aidressing
DEL
range
of
rmains within tM

_

21

Lattice

8086/8088

for

suFp}anent

C Gcmpiler

Version

2.}0

NNQE

forkjwit --

create

child

and

process

wit

for

it

SYNOFSIS
= forkv(nme,argv) ;
= Eorkl (nane,arg0,argl,
;
= forkvp(nane,argv)
= forkjp(naoe,arg0,argl,

error
error
erro r
error

code

=

mit();

int error;
int ccxie;
char
char
char

"nane;

...

,argn.NKL)

. . ·

¶argn0NULL)

;
;

success,
ñoHzéro
for
process
return code
nme of loai module
argunent
pinter array
0 for
child

error

file

*argv[];
*arg0,"argl, .. argment pñnters

DE3CRIPTKN
the
fmctions create a child process that executes
sµxñ£i«í load mdule and then passes a return code back to
The sFecified argtnents
the prent process.
to
are passed
argc/argv
the
p'int via the normal
child's main entry'
the
inechanim.
By convention,
first argunmt (i.e. arg0 or
argv[0)) is the nane of the child µrocess loal mdule, which
however,
Note,
that this first
is usually the sume as nane.
ar'junent
is not actually passed to the child process because
in
the
MS—DQS
process
creation pr imitives.
of limitations
the
Also
note
total
that these same limitations restrict
be
127
than
"
argunent
no
more
strings to
length of all
characters.
These

the
var ious
fmction naaes have been cMsen to match
'The "V" suffix on
forkv
of the LNIX exec fimction.
forkvp indicates that the argments are suppl led as a
the
in
the
form.
7hz
vecto
argv
r
pointer
in
vec tor
last
arü forklp iMicates
The "I" suffix on Eorkl
must be null.
as a list of f'ointers,
with
that the argtmmts are supplied
'The "p"
the
suffix on Eorkvp and
last pointer being null.
forklp indicates that the PATH enviroment variable sFmüd
mcxiule
in
the
be
wed
is not found
current
if the load
through
the
the
directDries,
jirectory.
id~ stepping
in
each
functions look for "name.CCM" and then "nane.EXE"
directory.
The
forms
and

It the child process cmnot be created, the fork fmction
result. Under MS-tOS, the global integer
returns a non-zero
the operating
contain
sYstxm
error cede.
oserr will
If it
while
processing
the
Is 0, the error occurred
fork call
par meters .
cAUrI~
22

Lattice

Supplwmt for

C Cjcmpiler

8086/8088

is dropµxi,
argunmts.
in its camand
its startup

sUcceediW

child

pragran,
back iñtÁj

an

arg

list.

2.10

are converted
into a text string
!n7e
argunmt (i.e. arg0 or
arü
between
a blank
is placed
1he resultim
strim is passed to the
the child is
C
a
line buffer .
©ase
will comert the camnaM
line

urder
MS-DOS the argunents
than
127 bytes.
no longer

argv{0])

Version

first

If

23

Lattice
7.0

C Compiler

8086/8088

ASCII/BINARY

for

Supplanmt

MOFE SPBCIFWRS

Version

2.10

CN FOPEN

finode global flag bas confused
the
the
users,
some
Éé of
mother"way
added
to specify translated
or
mtranslated
You can
when openim
a level 2
via fopen or freopen.
the letter
'a' in the
now
specify translated mcxle by placing
seco"nd
Similarly, the letter 'b'
position of the mode string.
the second
letter is neither of
sµci fies mtranslated mcrle.
Einode is wed
these,
as before.

Since
we've
mode

file

If

LNIX-compatible.
Note
that this new approach is ncjt currwtly
packages
several
Fbwever ,
mrk this way,
other C ccmpiler
proposals
sene
of
for this apprOach are floating around
standards
ccjmnittees.
In
sumary,
strings:

foFen

— open
— open
— open

r

ra
rb

open
3perl
open

w
wa
wb

—
—

a
aa
ab

— open
— open
— open

--

for
for
for

and

freopen

reading
reading
re¿Kjim

now

reccgnize

(translation
(translated)
(mtrmslated)

the

following

according

for writinj (translation accordirg
Edi writing (translated)
for wr it¿W (mtranslated)
for
for
for

appendiW
appendiW
appending

(trmslation accordiW
(translated)
(mtranslated)

airü
the

mcxie

Encde)

to

"
to

hncde)

"
to

finode)

"

sign
codes
place
to
a plus
after any , of these
cm also
If jk)u open for
indicate opening for both reading md writing .
reMing with a plim thm the file must alre&!y exist; but if ydu
anew.
open
for writing with a plm, the file will be created
Qpming'
with a plw will allow ydu to reed frcn
for appending
anjMhere
in the file, but all write operations will occur at the
end of the
file.
You

I/O

ERRCR

C=

mention
the
we fngot to
,
üíen
what went wrom
one
of
to
calls fails.
In gmeral , we've tried to adhere
jptr I/Otechnique
LNIX's
you
a
&en
failure
for reporting errors.
get
indication Eren m I/O f mction, consult the global integer
in the
cedes defined
which
one of the
will contain

Nm

we

methDd

error
As a further refinmmt,
you cm look at
error.h.
the
to
see
MS~ error code,
global integer _omrr
if any.
Reference
codes
and
FC4JC6
are de&ribed in the MS4XX3

errno,
healer

~

the Version
2 manual
wrote
which
by
you can determine

file

These
Mmuals.

24

Lattice
8 .0

8086/8088

C Compiler

ACCESS TO

MS-ljOS

Version

%pp1anent

for

Version

2.10

STRINGS
2

the
supports
LNIX
notion of " env irorrnent
ard
are
of the fbrm "nane=value"
are
usually
by the SET camand
'Ihe strings are stored
one
after
.
another
in the erivironment
and the last one is followed
at'ray,
by
a
Ü[joñ
the
null strinj.
public pointer env point3 to
entry,
the
P" mdel.z:
Ebr the S and
cur rent
enviroment array.
, the
startup prcxjran copies the enviroment into the stack sc) that you
address
can
Note
i t relative to [g.
sfjáce
that the stack
requir«] for this is added to the jaiue jpu specify'
in stack oí
on the camard
line.

strings",
def ined

7he

t:j

díich

LNIX-compatible

«iabl p

env irorvnent

you

function
easily find

getenv
to

.

25

has
a

been

aided

µrticular

to

the

nane

library
in

the

Kttice

8086/8088

C

Cmpiler

Supplmmt for

Version

2.10

NAME
getenv

—

get

striW

envirorxnent

by nane

SYNOPSIS
p = getemr(nane)

char "p;
char *nane

;

points
;

errv

to

value

nane

prt

of

matching

mv

string

lmmpTIoN
'This

fmction searches the errviroment
env and returns a pinter
to the value
str ing wMse name prtion matches nme.
a NULL pointer is returned.

26

array pointed the to by
prtíon of
first
If m match occurs,

Lattice

C Compiler

8086/8088

9.0

14ISCELLANE(XS

By

popular

functions

LIBRARY

request,
from the

Following

we've
proposed

SuRplanEs)t

ADOITI~
aided
LNIX

AND

Version

2.10

CCRRKTI=

more of the string manipulation
added the
standard.
Also,
we've

functions:
sane as ml ink
sane as clrerr
renane
a
trios
ftmction wi th
getch
wi
th eclK)
—
current stack
-- save
make lorA
return

rmove

—
—
—

clearerr
renane
bdosx
getche
setjnip
longjmp

file

--

pinter
for lorg return

--

The
library now contains callable versions
described
character
type
macros
in section 3
Manual.
Specifically, the following macros are
function form:
isalFtba(c)
isupeer
(c)
islower
(C)

non-zero
non-zero
non-zero
non-zero
non-zero
non-zzro
non-zero
converts
converts

kdigft(c)
iwpace(c)
isa1ntm(c)

iscntrl
toupFer
tolower
order
In
header

for

to

(c)
(C)
(c)
use

f lle in
reason,
jpu can
as fmctions.
The followim
added.

the
your
#uMef

manual

if cc
if c
if c
if
if cc
if
if c
c ix)
c to

is alphabetic
is upper case
is lower case
is a decimal digit
is white space
is alphanuneric
is a control character
üpper
case
it is
lower
case if
is

function forms,
compilation.
the specific

pages

describe

27

of scxne of the
of the Lattice C
also
available in

if

do

it

lower
upper

not #incluie the ctype.h
need ctype.h for
sane
that should be treated

If jNjü
macros
the

fmctions that

have

been

Lattice

8086/8088

SuFplmmt for

Gmpiler

C

Version

2.IC

NAKE

strcat/strncat

—
—
—
—
—
—
—

3tranFj/strnQnp

strcpy/strncpy
strlm
strchr/strrchr
strpbrk
strspVstrcsµ7

str
str
str

concatenation
ison

ing
ing
ing

ccmpar
copy

str % lmjth
find first or last occurrmce
break
tim
cMracter
find loWest initial sFan

measure

of

character

SYNOFSIS
;
to m strcat(to,fre)
to " strncat(to ,frcim,mw)

order = stranp(a,b) ;
order * 8trn=p(agbemax)
to = 8trcpy(to
to " stirncpy(to

rum) ;
,frcmómax)

,f

lergth " str1m(s)
p w
p m

strchr(src)$
strrchr(s.c);

p

strFbrk(8,t);

-

;

;
;

;

length * strgpn(8Ft);
lergth " Gp-.'-g'y (mt):
cMr *tjcj ,*frmj
int
cMr "a,"bb
int order 6

destination m 9otirce strims
mimtn nmber of characters
strings to canpare

cMr "W
cMr "t;
int 1ermh;
cMr "p;

test str Lng
result l€mth
result pinter

if
+ifa>b
string to test
-

0 IE

a < b
a — b

tmcRrpTIcN

strcat and strncat fmctions append the " from" str kg to
Fbr 8txñcat,
"tD" string.
m more than tibe specified
maximim
ntmber
of characters
will be appeMed.
The

tM

¶ie stranp ard strnmp f mctions perform
m msigned
of the specif Fed strings. Fbr strnanp,
character ccmparison
nurber
no mre thm tte speci fled maximun
will
of characters
be

The

cxmpared-

strcFy
to str im .

ard

strncpy hmctions
Fbr

8trrKpyb

no more

28

copy

tMn

the Eran strim
to the
the sFecifLed
maximun

Lattice

C Canpiler

8086/8088

nmber

of

characters

'Ihe
strlen
characters

function
in

terininatirg null

the

for

Supplan«it

will

Version

2.10

be cmpied.

returns
sµecified

a count
str ing,

jf

:
not

the

nunber

inclíxiing

df
the

.

first
function returns a pointer to the
in the sµ"cified
of the sµ"cified character
the
last
strrchr retur,ns a pointer to
Similarly,
str
Both functions return a null
occur rence
of the charactet
.
the
found
the
character
string.
in
is mt
pointer if
'Ihe

strchr

occurrence
ing.

the
to
k
f unction
returns a pinter
Eran string
in string s of any character
rence
the
frcxa
m character
null po inter is t"eáirned
strirvj is fourri.
The

str pbr

occur

if

first
t. testA

fmction returns the lmth of the initial
string s that consists entirely of characters
returns the length of the
t. Similarly, strcspn
stri% of characters
not frocn string t.

The
strsµi
segment
of
from strim

initial

0

29

Lattice

8086/8088

C

Suppltmmt

ampíler

for

Version

2.10

NNQE
rmane

--

rmane

file

a

SINOPSIS

error = rmane
int error;
cMr "old;
char

(old

,new) ;
0 for sUccess
old file naae

*new;

new

fmction rmanes
the new
occur
does
nane
m .
This

If

t

file

file

pssibl e.
alreay wists or

file, if

a
nme

nane

30

A

if

failure will
old file

the

Lattice

8086/8088

C Gcmpiler

SuWlanent

for

Version

2.10

nnqe
txios/bdosx

—

call

BOOS

function

SYNOPSIS

ret
ret

= bdos( fn Ax
= tx1osx(fn,dp,al)

,al)

int ret;
int fn;
int dx;
char

*dp;

int al;

Performs
a BOOS call
arü P manory mcxíels,
the D and L mdels,
requi res
FDinter
a
integer in DX.

;
;

return cede
ftmction

BIXJS
value

ntnber
placed
in
be placed
in DX
fjointer to be placed in 1j6: DX
value
t: j be placed
in AL

AH

to

via interrupt

nunber
0x21.
Fbr ttje
S
ard txiosx
behave
Fbr
identically.
the BDCG function
must use bdosx
jpu
in IX3:DX
tdos
an
BW only wants

txlos

or

31

if

if

Lattice

C Chnpiler

8086/8088

SUFpl«nmt

for

directly

to/from

Version

2.10

NAME

getch/prtch

—

get/µit

character

console

SYNOPSIS

getch();
getcte()
µitch(c) ;

c =
c =

;

get cMracter with m ecM
with ecN
get character
put

character

int c;

These fmctions get arid pit characters
directly to imid Eran
the
usiMg the lower-ntmbered
console
BIXJE3 f unctions.
Ni)
special processing
is done except that pNch µíts a carriage
in front of each newline.
return character

Previow

versions of pitch masked off the high order bit of
imxj
did not autmatically
«nit carriWe
EXisting
that gmerate "\r\n" sequences
returns.
prcgrms
dimild stfll behave the sane became the second '\r' anitted
by
is merely redurdmt.
the

character

)h

32

Lattice

Supplanent

C Cbmpiler

8086/8088

For

'jersion

2. 11·)

N/AM£
setjÍnp/lQrR

jmp

-- git

Í-)l"q

rK)E)-l32jl

goto

SYNOPSIS

ret = setjmp(save)
1Dm jmp( save ,value)
int ret;
int value;
jtnp

but
—

;
;

return
return

code
üaíúe

save;

DESCRIPTION
stack
function saves the curcent
spmi fled by save and returns a
'lhen
a
later cAl to lorujmp will retur 11
statment after the original setjmp call wi th
ccxIe.
retucn
If value is 0, it is forced to !

'Ihe

setjmp

buffer

area

1he jmp_buf
setjmp.h.

descriptor is

defined

in

the

header

tuatk
1!1 the
value
of 0.
the
to
next
the
value
as
by longjmp·

file

called

13 useful
f: n" quickly popping back up through
'Ihis iaechanim
except ional
multiple
layers gf f unct ion calls under
"gurus
lose
a lot
of
cl r : unstances.
StructurM pr(jgrmlnim
sleep
the "patholog
over
ical connections"
that can result
from
indiscriminate waye·
CAJJTI06B

with an inval id save area is an ef fective
(he carmon
jpur sYstan.
error is to use
lo'xjjmp
to
after the f unction calling setjmp has returned
how the stack
you think atjout
mrks, )pú'1l
its caller.
If
see \Áljf this doesn' t.

Calling
my to

longjmp
d isrupt

33

Lattice
10.0

ccN\mIENcE
version

This
to

the

use

--10.1

a

are

descr

Batch

Version

2. ID

.FEA=ES

files for

simle la

Batch

for

Supplanmt

things
that
incl®irig:

contains severa!
Lattice C CXxnpiler,

—- Batch

These

C Camµiler

8086/8088

files
ibed

ZoMing

ccmnand

invoke

for canpiling

both

onto

an

compiler
in

linking

and

make

it

easier

IBM-XT
passes

standard

ways

tte followim sections.

in

Files for

ccmpiler

the

to

should

Qampiler

Lotding

IHYI-XT

onto

the IEM-XT arü equivalent MS-DOS hard-disk machines
sean to
included
a batch
very ppular with Lattice C users,-w'e've
file
that constructs our reccmnended
directory structure ard a secorü
the hard disk.
1o&is
the compiler
batch
onto
that
file
Since
be

contain
the
creates
a directory structure that will
package.
mediales
'R)
execute
that make up the compiler
release
place
the
disk into drive a and type A: MAKELC.
the
procedure
the hard
ccmpletes,
disk will conta in tm

MAKEL£.BAT

vario=

it,

first

Nen
following directory strtrture:

\lc

Contains

\lc\s

Cbntains
mmory

\lc\p
\lc\d
\lc\l
\lc\c
\lc\src

cxmpiler,

heeder

files,

he&lers, objects,
.
heaers, objects,

and

utilities.

and

libraries

and

librar

for

S

for

P

model

Cbntains

les

manory

model.

Cbntains

heMers,
mdeL

objects,

and

librar les for

D

healers,

objects,

and

librar

L

m«nory
Cbntains
m«nory

model

Cbnta ins

building

les

for

.

heMers,
files.

objects,

and

librar

les

for

.C(M

Cbnta ins
source
dmonstration prograns

Elles

for

utility

and

.

copies
UJAIJLC.BAT procedure
information from the release
to the hard disk.
jpu don't want to keep a particular
before
mcdel
onl ine,
mmory
its sttdirectory
simply renové
executing
place
the
the lo?d
procedure.
'Ib execute
IAADLC,
release
disk into drive A arid type:

6

The

disks

If

first

34

Lattice
c:

cd

C Cknpiler

8086/8088

\lca :

oopy

for

~anent

Version

2.10

loadlc.bat

IoMIc
the

At

appropriate

in drive

times

),kju

will

be

prompted

chacrje

to

the

disk

A.

mcdules,
set the
you should
default
loaiing the compiler
This can
path
interpreter to include
f3r the camarü
either be done via the PATH comnaM or via the NJTCEXEC.BAT
manual
as demr ibed
in the MS-IXJS reference
.

After

\lc.

search

10.2

LC

¶ie

release

disk contains
fiímc tions

FCRK/EXEC
new
repeatedly
for
format:
IJC

muí

ti pI e

the
LC.CCM that uses
tWD canpiler
passes
has
The
ccxnmand
the

a progran
to
call

called

ccmpiler

oµions

the

compilations.

file

options files

options is a
of files, diich can
where

of
list
include

"wild

cards"

arid

is

files

a

list

.

and
LC2
In
are the same as for the LjCi
gmeral , the options
where
ccmands,
except
ICl arid LC2 used the sine option letter to
as follows:
mean different
things. 'These cases were resolved

option

This

option
Sane

on

as

sFeciEies

the

the

-S

-mds.

-mis

L mcxíel

with -s option

mn3s

Sane

-mis.

-qx

%eciEie5

as

with

D mcxíel

LC2.

prefix for

on

lC2.

files,

cpaj

sane

as

LCl

-o.

-s flag for pass 2 aFpears as a suffix on the
-m and -ml manory rnMel sEecifiers, and the quad file drive is
apply
charUjes
Ncjte that these
of -o.
indicated via -q insteixí
only to the new lC
not to LCl and LC2.
In

other mrds,

the

LC allow
jpu to
string that follow
IE

-d

xyz

,
put

it,

a blank
as in

betwem

an

option letter

is compatible
with (NIX, but causes a problan
is just before the file rime part of the camand
mcxle instead
tD iMicate debljggim
of defining a

bis

35

arxí

the

the -d itm
and
ws intended
symbol,
as in

if

IE
'Ihe

for

Version

2.10

-d µrogrm
"progran"
will
be ccmpiled.
endiwj
of

synbol

-d -

get around
options with
Tb

the

Batch

The
simpl

release
ify the

of beiW treated as
use the
this problan,
a siwjle dash:

prcgran

Files for Cknpilinj

10.3

instead

Sdefined

be

nane to
fileconvention

a
UNIX

LC

SuFp1mmt

C Ccmpiler

8086/8088

Lattice

and

Linking

f lies that
linking scmarios.

ba tch

several
compiling
and

disks contain
most

camion

Cjcmpile

LCS
LCP
ICD
LCL

for
CMpile for
Ccmpile
for
Gmpile for

LINES
LINKP
LINKD
LINKL

Link
Link
Link
Link
Link

LINK

for
for
for
for
for

should

S mdel
P ímdel
D model
L model

S mcxiel
P mrxíel
D rmdel
mcdel
.CCM

l

file

9 argunmts
consistirg of options
nanes or file nane
defined for
patterns.
file
lhe
LINKX
a
options met appear first .
µocdíures accept
the
the
.(BJ
nane of
single argmmt that is
file containing jpur
The
(as
'Ihe

LCX procedures

main

prog ran.

11.0

LIST

CF

acceFt
1£.CCM)

up to
and

FIW

shipped
on disks
in the IBM 320K format.
batch
10,
the
disk contains
files
the release
disks onto jpur mrd disk
that facilitate copying
IEM-XT
The actual
release
ydu use
files
equivalmt.

Version
2.10
As
discwsed

is normally
in section

are:

or

m

Batch

first

Files
MAKELC.BAT
LQADLC.BAT
LCX.BAT
LñúCx.BAT

Executable

bard disk directory structure
Ibai Lattice C onto hard disk
Ckmpile
tMer m«nory mcxlel x
Make

Link

urüer

manory

mcdel

x

Files
Qmpiler

LC.CCM
LCI.EXE
LC2.EXE
FXU.EXE
cmd.exe

plib86.

C cu use our standard
installation procedure
and
aidendun,
hard disk will contain
a directory "\lc\c"
your
versions
former
In the
)pü will find
a batch
"linkc.bat".
Ed "c.obj"
and "dos.mac"
that must be lg21Í 'when constructing .CCM
procedure
is:
f lies. !Ihe general

If

the

file

the

l.

Compile
under
C incdulc's
ytjlk
procedure)
LCS batch
;

2.

Assemble

"\lc\c\dos
3.

Link

sMuld

yrmr
.mac"

assembl

Y-larWjage

the

mall
prog

mcidel

rms

(e.g

.

via

wirK3

.

This
oing the LINKC batch [Kocedure.
which
warning
can
messaje,
a "NO stack sEayENr
EXE2BIN to
LINKC also
calls the ms-ujs
.CCM fo mat.
linker .EXE output into the desired

everything

cause
be ignored
.
the
convert

utility

Njte that j,rjl1 cannot produce a .CXM file if any of the included
segment
fixups.
defims a stack segment or contains
md linking with the sFecial
mder
the mall model
version of "c-obj" guarmtees
that these two criteria are met.
does not
irig with the special
Assmbl
version of "dos.mac"
guarantee
can be used to construct a
that your asstnbly-language
look
want to take
.CXMr so you might
a
at "c.am" tD see Ikyw" we
segment
up to avoid
fixups.
set
modules
Compiling

it

"**ENIM*

TECFNICAL BULLETIN
'IB840523.
002
IjATE: May 23, 1984
Version
FR(XjUCT: 8086/8088
C Gcmpiler,
SLBjBCT:
Nturn values for wrocs and

2.10
INT86

did
iáddendun
2.10
not mmtim a change
that we made
arxí IbW86X as a result of requests
INT86,
INT'DC6X,
frcxn many users.
These fmctions now return the processor
status
flags instead of the AX register valw. Many MS-lXj¢3 interrupt
the
to
the
convey
functions use
flags (especially
carry flag)
previously no way
information back to the caller, arid there
the
C
to
pí»;jran
obtain this information after calling one 3É
for
the above functions.
The fl'ags
are defined
in any 8086/8088

°Ihe

in

Version
IÑITRS,

fS

instruction

manual

.

Note that
jpur prcxjran is assuning
to obtain AX
AX,
must be changed
as descr ibed
in the Lattice C Manual.

it

if

that these functions return
fran the "outregs"
stcucture

queries
Eran people
to
had several
We have also
are tryim
absolute
use IW86
or INT86X to perform
disk reads and writes via
This
will not mrk because tNse Uk)
interrupts 0x2S and 0X26.
µished
on the
interrupts return with the status flags
in the MS-DOS aM FC-IXJG Programér's
stack, as is discussed
Reference.

^

still

***END***

TECHNICAL

BULLETFN

TB8406I5.001
DATE:
june 15, 1984
PRODUCT:
8086/8088 C Compiler,
SUBjECT:
Vecsion 2.12 Update

Version
correct

2.Zl

2.12
of the 8086/8088 C compiler
problems:
the following

Null #defines were
l.
statement such as
#define
caused
2.

Version

The

a

'

has

been

released

not handled correctly.

to

That is,

a

XYZ

spurious

error

function

STRNCMP

message.

the correct

did not always return

vaíue.
3.

not

character
include the

The

4. Flit
fields were
changes introduced
5.

The

ÍNT86

ail cases
register.

count returned
terminator

null

and

because

not compiled correctly
in Version 2.10.
INT86X
some

as

the standard
to Ox8000,
were not switched into

Because of a packaging error,
the Version
was
included on the 2.1 release disks.
MAIN.C
and
fiLe is called
is now included.
old MAIN.C
with Version 2.1.
MAIN.C

8.

STDIO.H
p

inemory

of

functions
did not work correctly
destroyed the bp
interrupts

7.

and

result

a

in

DOS

fmode
When
you
defined
(stáin,
stdotit, and átáerO
by
main.

6.

by the STCCPY
function did
under some circumstances.

has been changed to define
models and as DL for the

NULL
as
L
D and

filesmode

raw

2.00
The
Do

copy of
correct
not use the

O for
the
models.

S

size
Sevetml people complained about the load module
feature described
increase caused by the DOS compatibility
we have
Therefore,
in Section 3 of the 2.1 addendum.
changed
the átandard libraries so that the I/O functions
want to becompati5le
work only with DOS 2.
you
IOSIX.OBj,
vñth DOS I, the release disks contain files named
model
(S,D,P,
Include the
where x is the memory
or L).
and
when
you
approDriate copy of IOSl
your program
link,
2.
work with both DOS I andDOS
you want tocodesave a
and
_MAIN.C
remove
that
the
memory,
more
examine
Little
is specific
to DOS I.
9.

If

still

If

will

LO.
you
declared a function to return a char or float
return an int or a
value, the function would actually
This has been corrected.
Note that
double, respectively.
this bug is suspected to exist in several other compilers,
have
and
some
fallen
people
on UNIX
sYstems,
particularly coding practices
The
most
because
common
of it.
into sloppy
pitfaLl ia illustrated below:

If

In

module

ti:

func()
char
{
chac

c;
return(c);
]
In

12:

module

int=

x

x;
func();

contents of x"s high order byte will be garbage,
the modale 42 implicitly declares func to return an
On the 8086,
a char.
returning
is actually
though
means
is that func places c in theAL register
this
nothing with AH, which is a code improvement.

The

it

what
does

and

indicates
that constants
of the 2.1 addendum
This
expressions.
as operands in logical
removed
because
been
broke several
programs.

2.7
II. Section
are not allowed
restriction has

existing

because
even

int

it

12.
There is a typo on page 5 of the
second last line, the word "constant"

13. There is a typo
description
of the
not LC2.
14.
The
command.

-X

and

on
-mds

addendum. In the
should be "comment".

page 35 of the 2.1 addendum. In the
option, the -3 flag applies to LCl,

-n flags

15.
The
header file
2.11 release disks.

2.1

were not recognized

SETJMP.H

was

omitted

by

the

from the

LC.COM

2.10

16.
The
2.10
and
2.11
releases contained libraries that
not compiled with the -s option, which resulted in a
performance degradation.
17.

The

2.1

addendum

recognizes C source
you
type

If

LC

the

If
free

you

to

us

\stuff\abc
will not

command

have already
update to 2.12
with a return

did not make
that are

files

find

it

"in

the source

purchased 2.10 or 2.11,
simply sending the
mailer.

by

***END***

and

were

clear that LC.COM only
the current directory.

file.
you

can

original

receive a
release disks

T

: : ;'
O5

W

0 *e

q

Py ©

> É
W

A

;'

fjb

©W

©

Hir'scHman

808618088

manaKer

~
0

1?Ij1j3á96

Intel
Library"

TJ»nre

ect

obj

£cwk7
'Lpy

PSA object
?lib86:
Table of Contents

Library

Manager

Table of Contents
Library

Concepts

Manager

.

Using Plib86
.
.
.
.
.
.
.
Creating/Merging Libraries
Library Search . . . . .
Updating a library . . .
Module
Extraction
.
.
.
Cross reference listing
Plib86 Commands
Input Format

. .
. .
. .
Names

.

.
INCLUDE,

Building

.

B

Appendix

C

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.
.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.
.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.
.

.

.

.

.
.
SEARCH

. .
EXCLUDE

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.
.

.

.

.

.

.

.

.

.

.

.

.

.
a

.

.

.

.

.

.

.

.

.

.

.

.

Library
Reports .

HEIGHT
.

VERBOSE
BATCH
.
LOWERCASE

Appendix

.

.

.

.

.

.

.
.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Module

.
.

.

Miscellaneous

A

.

.

NOINDEX
BLOCKS

Appendix

.

Library

Extracting
Generating
Controlling

.

a

BUILD
INTEL

WIDTH,
BRIEF

.

.

object Files . .
FILE, LIBRARY,
AS

.

.

Identifiers
File
Plib86
Initiating
Command Format
Disk

.

the Library
Commands

.
.
.

.

.

.

.

.

.

.

.

.

.

.

.

.

·.

.
.
.

Index

.

.

.

.

.

.

.

.

.

2-l
2-l
2-2
2-3
2-3
2-4

3-l
3-l
3-l
3-2
3-3
3-5
3-6
3-6
3-8
3-8
3-9
3-9

3-lO

3-ll
3-12
3-13
3-13
3-14
3-14
3-15
3-17
3-17
3-17
3-17

.

.

l-l

.
.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.
.

.

.

.

.

.

A-l

.

.

.

.

B-l

.

.

.

C-l

Warning

Messages

Messages
- Error
Problemg
- Reporting
.

.

PSA object
Plib86:
Introduction

Library

Manager

i

Plib86 (tm) is a Phoenix Software
Associates Ltd. software system that can
manipulate libraries of object files.
It
supplements the PSA linkage editor
and
is intended for use on
Plink86 (tm),
the Intel Corporation (l) 8086 (or 8088)
processor (tm) under the MS-DOS (2) or
CP/M-86
(3) operating
systems.
plib86 handles object files and
libraries conforming to the INTEL
relocatable
format described in
file
"8086
document
Reloeátable object
their
Module
This format
Formats" #121748-001.
by
used
Microsoft
in
compilers
written
is

Corporation,
creator of the MSDOS
operating system, by most other companies
wUtinú compilers for MSDOS, and by a few
compilers written for Digital Research's
a
CP/M-86
operating system. However,
by
used
is
index
different library
Microsoft to achieve faster library
?lib86 can read and generate
searches.
both tkt' Intel and Microsoft library
index torrnats.

of this manuál
of the "object
library" concept and the capabilities gf
with library
User's unfamiliar
Plib86.
do well to
would
managers
here.
start
Also, the Plink86 user's guide contains a
chapter discussing object files and
linkage editors that may be helpful.
The

provides

Section
first
an explanation

next section of this manual
describes how to use plib86 to handle
several common object library situations.
At the same time it provides an informal
explanation of what the commands do.
Those
readers experienced with linkage
The

PSA object
plib86:
Introduction

Library

Mañager

ii

ediÉors and library managers
rnay wish to
skip directly to this portion of the
provides enough information
manual:
to handle most jobs.

it

The final portion
of the manual is
exhaustive list of the commands and
This should
features offered by PIib86.
when
becomes
be examined
to
necessary
it
given in the
go beyond
the examples
Side issues such as
previous section.
codes
referred to
generally
are
error
appendices.
an

Trademark

Acknowledgements:

(I)

INTEL is a trademark of
Corporation

(2)

MS-DOS

is

Intel

trademark of Microsoft,

a

Inc.
(3)

CP/M-86

is

Research.

a

trademark of

Digital

Plib86:
Library

PSA object Library
Manager
Concepts

Managér

l-l

is convenient (if not
Typically
essential)
to divide a large programming
job into smaller pieces called "modules"
that can be edited and compiled
compilers
separately.
Actually,
available on micro-computers tend to have
severe limitations on how many lines of
code can be compiled at one time, forcing
the programmer
to use modularization
On
anyway.
the positive side, modular
programming
offers a method of organizing
a
program
into manageable
pieces that are
easier to understand and work with.

it

After the program modules
are
must
created and compiled the programmer
"link" them together with a "linkage
to produce the executable program
editor"
(see Plink86 user's manual).
Once one has created
program one may find that
modules
are useful in a

program.

With

a

little

can be made more
function and can be used
programs. The programmer
build up a
of
that can be hooked in by
needed.
whenever

modules

"library"

editor

a modular
some of the

different
effort these

general in
in many
can gradually
useful routines
the linkage

In fact, virtually all compilers are
sold with a "library", since functions
like arithmetic by on real numbers andarehaveoften
supported
the hardware
to
not implemented
The
be
as procedure calls.
compiler library also contains modules
that support the high level features of
the language such as formatted output in
FORTRAN.
This library is often called
the "run time support" since its modules
are required while the program executes.

Plib86:
Library

PSA

object Library
Concepts

Manager

Manager

l-2

Other software products in addition
to compiler runtime support routine8 ate
An
sold in the form of libraries.
example
might be a set of data base
management
routines that is combined
with
by the linkage
program
the application
editor to produce a complete system.
Because

of the importance of

have
libraries, linkage editors typically
To
special facilities
for handling them.
save memory space, only those modules
in
the library that are actually required by
Sometimes
a
the program
are linked in.
conCatenation of
library is simply
a

object modules, requiring
the linkage
ediÉor to search sequentially
for the
required modules. More sophisticated
systems
provide a "library index".
contains a list of the public symbols It
and the
offered by each library module,
location of the module that defines each
symbol. Therefore the linkage editor can
rapidly locate the modules
that are
and Intel
The Microsoft
required.
library formats are indexed structures.
The

purpose of the library manager
and manipulate object module
is therefore a useful
to Itthe linkage editor.

is to create
libraries.
assistant
plib86

provides commands to create
object modules,
individual
from
libraries
a
and to extract
selected module from a
library. It can also merge libraries,
and can replicate
the library search
process undertaken by the linkage editor
while creating a program. In other
words, one can create a library
consisting
of only those modules
that the
editor
link"age
would include in a
particular program.

Plib86:
Library

psa object Library
Concepts
Manager

Manager

l-3

Plib86 also provides a powerful
function.
cross-reference
It optionally
generates a.report listing each public
symbol, the module which defines it, and
a
list of other modules that refer toa it.
This may be used to cross-reference
single library or several librarje3
together, or, in combination with the
library search feature described above,
to generate a cross-reference
of a
program
that will be created by the
linkage editor.

PSA object
Plib86:
Using plib86

Library

Creating/Merging
BUILD

Libraries
use the
librarycommand.

To create a new
command and the FILE

example, executing
BUILD
FILE

DB.LIB
BTREE,

2-l

lqanage¥

plib86

SORT,

and

For

entering

REPGEN,

FIRSTLIB.LIB;
in response to the

prompt

would create

a

containing the files
library named DB.LIB
These
listed'after bethe FILE command. modules
single object
files could
or
Everything is merged
complete libraries.
into a single library. The default file
type for the files appearing in the FILE
statement

is "OBJ".

PIib8ÉA

PSA

Using Plib86

Object Library

Manager

2-2

Normally you can just execute Plib86
type in commands on as many lines as
Then end the last line with a
desired.
Each
semi-colon to begin processing.
statement begins with a key word like
and is followed
by
BUILD or FILE
arguments, possibly separated by commas.
Input is free format, and blank lines are
ignored.
Also, key words may be
abbreviated by leaving off characters at
For example, you can use BU and
the end.
instead
of BUILD and FILE. An error
FI
message
will be given if the abbreviation
could be confused with ánotíjer command.
and

Another
the commands
example, the
been created
PLIB86

Note

defaults

way to use Plib86 is to
For
as
is executed.
above
could have
by entering
(on one

it

library

BU

DB
FI
REPGEN,

give

line):

SORT,

EJTREE,

FIRSTLIB.LIB

that the output file type
to "LIB" automatically.
Library

Search

Suppose
you want
to create a library
consisting
of several modules plus those
portions of another library that are
referenced by the modules. Use the
LIBRARY

command:

DB
FI BTREE,
LIB FIRSTLIB.LIB
BU

SORT,

REPGEN

The portions
of FIRSTLIB
referenced by the three.other
not put into the DB library.

not

files are

PSA
plib8G:
Using plib86

object

Library

Updating

to

2-3

Manager

library
update
library it is necessary
the old library to the output
be
module

To
copy

a

a

to
file while omitting the
updated, and to include the new module.
COSINE in
For example, to replace module
MATHLIB,
rename
the current
library
MATHLIB.LIB
to MATHLIB.OLD and enter
COSINE,
EXC
COSINE

MATHLIB FI
MATHLIB.OLD

BU

EXCLUDE statement applies
name given and causes
module
in the MATHLIB to be

The

file

previous
COSINE

omitted.

to the
the

Extraction

Module
The

a
EXTRACT statement causes
module
to be created.
used at the same time as
may
The
BUILD.
object module found in
so the
is extracted,
the input
module
to be selected from a
The object
must be specified.
extracted may be given any
The module
name remains the same.
name.

file

object
not be

single

It

first

particular
library

files

file

file

For example, typing
EXT

OLDCOS

FI

INCLUDE

MATHLIB.LIB
COSINE

OLDCOS.OBJ containing
object
The INCLUDE statement is
applies
the counterpart of EXCLUDE:
and causes
to the previous input
only those modules named to be considered
There
wouldn't be any
processing.
point to INCLUDing more than one module
one
case
since only the
in

creates

module

file

COSINE.

file

it

for

this

found is extracted.

first

object

PSA
plib86:
Using plib86

Library

reference

Cross

Manager

2-4

listing

To create a cross-reference
listing
the LIST command with input file
statements similar to those given in
previous examples. For example,
use

LIST

FI

=

DB

BTREE,

S

SORT,

REPGEN,

FIRSTLIB.LIB

a
cross reference report named
in all of
describing the modules
the
the.files listed. The "S"Forselects
a
cross-reference
report.
description
of other reports available
The
see the LIST command description.
"=" specifies that the report is to be
put into a disk file. If omitted the
on the console.
report appears

creates
DB.LST

Plib86:
Plib86

PSA

object

Library

3-l

Manager

Commands

Input

Format

This portion of the manual describes
basic input elements.
Later sections
show how these are combined
to create
full statements.

some

Identifiers
is the name of some
identifier module
as
or symbol. An
sequence
of no more than
is
identifier
and
64
An

object,

such

a

a

characters containing no spaces,
containing none of the following:

"=;<>/,\!'#U'+-:
Lower
case
letters,

translated
automatically
The
character of
first
not be a digit 0 - 9.

@

DEL

when

into

used, are
upper case.

iáentifier

an

may

restrictions on valid by
identifier characters may be avoided
The
using the escape character """.
the
character immediately following
escape
character is treated as a normal
identifier character.
The

above

The

following

identifiers:

are

examples

olE

Programl

SORT3
ABC"@
The

(the

following

identifier8:
34ABC
NII'I A

"@"

is

are not

with
- begins
containB a
-

escaped)

valid
a number
space

valid

Plib86:
Plíb86

object

PSA

PROGtl
The
made

Linirary

Kanágc'r

:J-¿

Commands

-

above

valid

starts a comment wittj "*"
identifíers could all be

witn the

escape

character:

"34ABC
NIM" A
PROG"tl
To
an

include

the

identifier enter

escape
character in
two escape
characters

Identifiers appearing in object
files are truncated to 50 characters for
purposes of comparison with other
in the program.
identifiers
Identifiers
be

may

reports
Disk

truncated again for inclusion
(see the LIST command).

file

in

Names

Plib86 adapts itself to the file
format used by the operating system
is executing under. The first
character not allowed to be in a file
The escape
name terminates
the name.
character rnay be used to put any
character into a file name.
name

it

MS-DOS format
file names
for purposes of discussion.
These
form
file names are ofwiththe optional
[device: ]namel.type),
Here
portions in brackets.
are some

In this
are used

manual,

exampi¢zs:

MATHLIB.L"IB
B: CHESS.OBJ
SCANNER

Plib86:
Plib86

Object Library

PSA

3-3

Manager

Commands

When the "device:
" is not given,
plib86 assumes that the ctjrrently
logged-in disk is to be used.

Initiating Plib86
input

Plib86
may

given

plib86
where

This


means

files.
To

mode,

use

be

may

be

used
as

it

interactively, or

statements

means

that

is executed:


to press the RETURN
Plib86 may used in

Plib86

in the

enter

key.
.BAT

interactive

Plib86
Plib86 will read lines
the console.
"=>"
from the console, prompting-with
The standard line editing
features
8upplied by the operating system are
plib86 checks input lines for
available.
syntax and stores them until a semi-colon
is entered at the end of a line.
Then processing of the input files
begins.
on

';'

A
disk file containing all or,only
part of a command may be inserted into
the input at any point by preceding the
The default
disk file name with an Y".
These disk files
".LNK".
is
type
file
"@" specifications,
can contain
further deep.
The most common
up to three levels
is to prepare a file
use of this feature
containing a complete command; then,
entering

plib86

@file

name



Plib86:
Plib86

PSA

object

Commands

Library

Manager

Sometimes
these
creates the library.
".LNK" files may be prepared once for
given library and used over and over
again,
greatly simplifying
the whole
process.

plib86 reads an entire command,
checking for syntax only, Defore any
processing is done.

3-4

a

file

Plib86:
Plib86
Command

PSA object
Commands

Library

Manager

3-5

Format

All Plib86 input is free format.
Blank lines are ignored, and a command
of lines.
may extend to any number
Comments may be included with input from
any source by using a percent sign "%".
When this is encountered,
all remaining
characters on the same line are ignored.
Input

is

a

list

of statements:

 

...



statement begins with a key
followed by arguments
For example, in
separated

word,

Each
and

many are
by commas.
FILE

A,B,C

0

is the key word, and A, B, and
may"be
Key worás
the
arguments.
are
abbreviated by omitting trailing
characters, as long as the abbreviation
is unique among the entire group of key
words. For instance, the previous
statement could have been entered as
FILE

C

FI A,B,C

If a syntax error is found, the,
current input line is echoed with two
question marks inserted after the point
This is
at which the error was detected.
followed by an error message (see
Hib86 pust then be
Appendix).
re-executed.
If an error occurs during file
processing, plib86 terminates with ar,
error message also listed in the
appendix.

Plib86:
plib86

Litnary

PSA Object
Commands

Manager

3-6

Object Files
LIBRARY,

FILE,

SEARCH

Plib86

be

must
and
what modules
to
FILE command
is
normally causes

told

what

object

input and
libraries to use for
The
select from them.
used, and
typically
all modules with the
given files to be processed:

files

COSINE,

FILE
Ttie

SIN,

commands
are
on
select only those modules
that define
symbol
a public
that is needed by some
other module that has already been
processed.
This is called a
a process carried
search" and
out by
most
linkage
insures that
modules
onl',' those
that are
needed
are included in the
ar
>gram.

library

similar, but are
and

and
used

ARCTAN

is
editors.
library

ally

LIBRARY
SEARCH

SEARCH

libraries

only

"library

It

MATHLIB
FORTRAN

LIBRARY command causes the given
to be searched once. When the
SEARCH command
is used the
are
searched repeatedly as long as undefined
symbols remain. This won't be needed
unless two or more
are being
searched that each refer to symbols
The

libraries

libraries

libraries

defined

in the others.

can't find

a
requested
under
is
running
the
file,
MSDOS
2.0 operating system, it will look
in the environment for a string named
"OBJ". The value of this string is

object

If

Plib86

and

Plib86:
plib86

PSA object
Commands

Library

Manager

3-7

path
to be one or more directory
separated by semi-cqlons (just
These
2.0 PATH Command).
like the MSDOS appended
path names are
to the front of
the object file name (any disk drive ID
time in an
is removed first) one at a The
path name
effort to find theadded
file.
between
is
the path
separator
For example, 'if
name and file name.
assumed
names,

'\'

SET OBJ

=

\OBJECT;

\LIBRARIES

entered before running plib86, and
was being searched fór,
file TEST.OBJ
and
would
look for \OBJECT\TEST.OBJ
\LIBRARIES\TEST.OBJ.
This means that
commonly
used object
files can be left in
a directory for use by many programs.
were

it

If an input file can't be found by
using the OBJ path names, or if MSDOS 2.0
is not the operating system being used,
the operator will be asked to enter a
string (e.g. "A:" or
file name prefix
"\OBJECT\"
that will be appended
to the
front of the file name after stripping
any drive
id . Diskettes may be changed
of course,
tÍÜ8
time
at
necessary.
the operator must insure that any
diskettes removed do not contain open
file8 like the BUILD or EXTRACT file. work
AÁbo,
Plib86 runs out of memory a
18 opened
on the default
diMc, which
file
then may not be removed.

if

if

Plib86:
Plib86

Library

psa OLject
Commands

f!arjdger

3-8

AS

library) is
If an object file (not a contains
being processed the module
is
given the same module name as the name of
came from
This is done
the file
because
some compilers don't supply a
This default may be
unique module name.
changed
by using the as statement.
supplies the module name for the lastIt
file náme given. For example,

it

it

MATHI

FILE
would

name

instead

of

AS

COSINE

the module
HATHI.

in

KATHI

COSINE

EXCLUDE

INCLUDE,

library

The modules
selected from a
by using the
may be
The6e
INCLUDE and EXCLUDE 6tatements.
of module names:
are followed by a

further restricted

list

FILE

LIB

MATHLIB
t'lATHLIB,

INCLUDE SIN, COSINE
EXCLUDE BTREE

DB

The INCLUDE statement causes
only
those modules
to be considered for
listed
processing, and this selection precedes a
EXCLUDE is the opposite.
librSlry search.
The modules
are not processed.
listed
INCLUDE ana EXCLUDE apply to the FILE,
LIBRARY
or SEARCH file immediately
preeeding.
In the second example above,
for instance, the EXCLUDE BTREE applies
only to the DB. library, not MATHLIB.

plib86:
Plib86

PSA

Object Library

Manager

3-9

Commands

Building

a

Library

BUILD

command is used to create
selected
of
the modules
out
library
followed by
is
from the input files.
It
The
the name of the file to create.
file
type defaults to .LIB:
The

BUILD

a

BUILD
BUILD

DB.LIB
D: PIATHLIB

After all modules
index is created.

are output

the

library

One must be careful
that the output
does not have
the same name as any
For instance,
the input

file

files.

of
entering

BUILD MATHLIB
FI COSINE, ARCTAN,

won't
before

work

it

because

MATHLIB

MATHLIB

is read.

will

be

erased

BUILD command may not be used
with the EXTRACT command
Mnultaneously
(described next).
If no output is
requested from plib86 (i.e there is no
EXTRACT or LIST command)
BUILD,
then
plib86 will simply read the input modules
and report
any errors
finds.
The

it

plib86:
Plib86

PSA object
Commands

Library

Manager

3-ID

INTEL

By default, the BUILD command
constructs a Microsoft format index for
the library file under construction.
When this statement appears, however, an
INTEL
format index is constructed
No arguments are required.
instead.
When creating
an INTEL format index, tbe
LOWERCASE
statement may have to be used
to inhibit translation of symbol name
characters in the index to upper case.
Sorne compilers
using Intel format
and
between
upper
libraries distinguish
lower case when comparing symbol names.

plib86:
plib86

PSA

Object Library

3-ll

Manager

Commands

Extracting

LÍbrary'Module

a

is used to
module
from a
object
extract
and
a
into
place
separate
library file
disk file. It is followed by the name of
the file to create:
The

EXTRACT

a

command

single

it

EXTRACT COSINE.OBJ
EXTRACT ARCTAN

If

the

assumed.

file

type

is omitted

is

OBJ

The EXTRACT command extracts
module
found in the input

first
Therefore
the

it

is usually

INCLUDE statement
module
should

library

the

files.

necessary to use
to specify which
be extracted.
For

instance,
EXTRACT COSINE

extracts

PLATHLIB,
module.

the very

MATHLIB

module
first
is not the

if the
it

even
To get

FI

EXTRACT COSINE

correct
FI

one

MATHLIB

in

COSINE

enter
INC COSINE

Plib86:
Plib86

PSA Object
Commands

Library

3-12

Manager

Generating Reports
The LIST command is used to generate
reports about the object files being
processed.
It may optionally be followed
by a
name, causing the reports
to be
file
directed to that disk file or device.
preceded

by

file
Then a character
is entered
equal sign.
each
for
report desired, separated by
There
commas.
are two reports available:

The

name

M

must

be

of all
- in list
alphabetical
A

modules

each module
is
symbols
defined

S

-

order.

listed

within

an

processed
Next
to
all of the

it.

list of all public
in alphabetical
external symbols
Each is followed by the
order.
defining the
name of the module
symbol
in parenthesis (this will
be blank for symbols
not defined
by any module
Following
read).
is an alphabetical
this modules
list of
that access the
all
symbol
(i.e. this is a
cross-reference
report).
and

A

Here

are

LIST
LIST
LIST

YI
=
=

some

examples:

DB.LST PI,
XREE.LST

S
S

Object Library

plib86:
plib86

Commands

WIDTH,

HEIGHT

PSA

lianager

Y-13

The report generator can be
re-configured
for different size paper.
and 66 rows per
80 columns
assumes
It
The number
of columns
page as a default.
command,
changed
be
WIDTH
with the
may
and the number
of rows wíth the HEIGHT
command.
Here are sorne examples:
WIDTH 132
HEIGHT 88
BRIEF
The S option of the LIST command can
be quite long.
the BRIEF command is
used,
however,
undefined symbols
are
more
deleted from the report, making
manageable.
These
undefined symbols
that you did not
might be from
search in creating the report, and wight
The
not be necessary in the report.
BRIEF statement has no arguments.

If

all

libraries

it

plib86:
Plib86

PSA

object

Library

Commands

Controlling

the Library

Manager

3-14

Index

NOINDEX

from all
Normally all public symbols
are inserted into the library
a
duplicate symbol is found
index.
If
but a warning
library creation continues
message
is given and the index entry for
that symbol will select the first module
defining the symbol.
modules

Sometimes
to exclude
itfromis useful
the library index.
certain symbols
This may be accomplished by using the
NOINDEX

command.

NOINDEX

excludes
index.

SYMI,

For

SYMI,

example,

SYM2,

SYM3

and

SYPi3

SYM2,

from the

Suppose
you wish to create a library
that contains several versions of the
same module, for instance a device driver
for some kind of hardware. If you try to
into the library
place all of the modules
symbol
warnings,
you will get duplicate
and at link time the linkage editor
wouldn't be able to select the desired
module.

using
entry
This excludes all of these
points.
symbols
To get
from the library index.
the linkage editot to select the correct
module
but unique dummy
inserteachan un-used
symbol
one.
into
At linkage edit
time one of these dummy symbols would be
accessed
in order to create a need for
TfW linkage editor
the desired modulo.
This

NOINDEX

on

can be made to work
most
of the moáule

by

Plib86:
Plib86

PSA

Object Library

would

then select
searched.

could

3-15

Mañager

Commands

it

when

the

library is

Using plink86, for instance,
use a statement like
DEFINE

one

FOO=DRIVERI

the module containing the
dummy entry point.
An
which works in a Microsoft
alternative
on the fact
format
to
that the name of each module is actually
followed by
index as
in the
For example,
an exclamation point.
contains a module nainea
the
DRIVERI
be a dummy index
then there
named
symbols
DRIVERI!.
These
can
entry
be used instead of creating
a durnmy
module
entry point as discussed above.
to select

"driverl"
library is
library
library

rely
well,

if

will

BLOCKS

Microsoft library index consists
Plib86
prime number of hash blocks.
choose
amount
space
index
of
the
will
needed
so that everything
fits and then
adds about a 10%
slop factor. The extra
is added because the hash blocks are set
up as a "scatter
table" (see Knuth's
and
programming)
volumes
of computer
as
search time can increase dramatically
the blocks become nearly filled.
However,
the linkage editor reads most
if
of
the
index into memory when
or all
doing a library search (as plink86 does)
The extra
this may not matter too much.
time spent comparing iáentifiers is more
than made up for by the savings from
reading fewer index blocks from disk.
The

of

a

plib86:
Plib86

PSA object
Commands

The

the
specifies
be used.

when

Library

BLOCKS command
BUILD command
the number of
For example,
BLOCKS

Manager

3-16

functions only
is used, and
index blocks to

7

forces Plib86 to use 7 blocks.
If
won't
into the
some of the symbols
index Plib86 will print warning messages.
If the argument to the blocks command is
not a prime number Plib86 will increase
until
is. The limit on the number
of library index blocks is 997.

fit

it

it

plib86:
plib86

PSA Object
Commands

Miscellaneous

Library

Manager

3-17

Commands

VERBOSE

When processing a large library
file
useful to know what
is sometimes
When the VERBOSE
plib86 is doing.
statement is used Plib86 will maintain a
status line at the bottom of the CRT
what
is going on. This
screen indicating
statement should not be used on a
hard-copy terminal.

it

BATCH

object file
can't find an prompt
If Plib86 will
normally
the
or library
operator to enter the name of a disk
drive or directory
path name where the
be found.
The BATCH command
may
file
will cause Plib86 to stop with a fatal
error without prompting the operator.
It
is useful when running plib86 from within
and no operator
a batch
available
is
fileto a prompt.
to respond

it

LOWERCASE

Any object files and libraries
conforming to the Microsoft standard
normally use only upper case letters in
identifiers. Therefore Plib86 normally
translates all lower case letters to
upper
case. This statement inhibits this
translation
for all identifiers found in
object files, library indices, or Plib86
commands.
It is sometimes necessary to
use this command when an Intel format
library is being built (see the INTEL
command).

plib86:

Appendix

object

PSA
A

-

Warning

Library

Mañager

3-J.

Messages

Occasionally PliD8E. ctetectm a
that looks like It ÍüiYtjt be a
situationwhen
the iñpti'c Cbt outp: " object
problem
by the link: age
processed
files are
m"?32;age
issues
then
editor.
It to execute.a uarning
and continues
TMse lne.4sages
but a nurabc!:
should be self-explanatory,
is also given that may be lookec' '.ip in
this appendix to get a more complete
explanation of what has happened.

I -

may be only one definition for
global (i.e. PUBLIC) symbol in
the object modules being processed.
Plib86 ignores the duplicate
definition and retains the first one
lck use in any library index or
reports being generated.

2

Each record in an object
file
contains a check field at the end
for validation
purposes. This
message
indicates the checksum was
bad,
but processing continues.
These messages
are inhibited
after a
few have been printed.
Was the
object file patched on disk before
Plib86 read it? TYpically people
who patch object
files don't bother
Also, some
changing the checksum.
compilers and other librarians seem
to be sloppy about making sure the
checksums
are correct. If the file
is really smashed a fatal error will
probably occur soon after this
message
appears.

-

There
each

Plib86:
Appendix
3

PSA
A

-

object

Warning

Library

Manager

A-2

í'tessages

Each record in an object
file is
- preceded
word
by
giving the record
a

This error means that Plib86
reached
the end of the record and
found that the number of bytes
processed iSdifferent from the
The object
specified size.
file is
probably smashed,
but Plib86 will
attempt to continue reading it.
size.

4

—

is

There

no

room

in the Microsoft

with the
library index being created
named symbol.
BUILD command
for the
probably used the BLOCKS command
to reduce the size of the index, and
now
is too small to hold
everything.
This warning should
used the
never occur if you haven'tPhoenix
BLOCKS command:
contact
Software
i" does.

You

it

if

plib86:
Appendix

psa
B

-

object
Error

Library

B-l

Mañager

Messages

When a fatal error
is detected by
plib86 a console message is printed which
However,
an
should be self-explanatory.
may be
error number is also printed which
looked up in the table below. A longer
discussion of the error will be found
there.

Command

Syntax Errors

errors are caused by mistakes
in the input given to Plib86.
the
Re-run Plib86 after correcting
The input line causing the
problem
problem will be displayed on the
terminal, with a couple of question marks
inserted after the point where the error
These should aid in
was detected.
locating the problem, but occasionally
Plib86 may not detect the error until
more text is processed.
In other words,
the error location is given as the
front of a line, check the end of the
previous line.
These

made

if

I

"@"
are nested too deeply.
- Only files
three levels of "e" files may
be
Do

active

you

have

a

references?
2

file

Disk error encountered while
- reading
Y" file. Try re-building
the

5

at any given time.
loop in your "@"

file.

The
given for input at thi8
- point item
The maximum
is too large.

size allowed is

64

characters.

plib86:
Appendix

psa
B

-

object
Error

Library

Manager

B-2

Messages

6

Invalid digit in
- thru
9).

10

The input
- Invalid file name.
stream should contain a valid file
name for the particular operating
system
being used.

II

key word
Expecting
statement.
- which
begins
statement should be

(i.e. not

number

0

A

a

a

present here.

12

-

The
may

the

INCLUDE and
be used
same input

not

statements
simultaneously on

EXCLUDE

file.

í4

Expecting identifier.
section,
- module,
segment,
or symbol name
must be entered at this point.

16

An expression
value.
- Expecting
or l6-bit quantity must appear at
this point.
were given to process!
- You files
and
must
FILE

17

A

a

No

specify
18

-

use the
at least

one

statement
input file.

BUILD and EXTRACT commands may
be used simultaneously.
You
must
one
twice
with
Plib86
run
command in each.
The

not

plib86:
Appendix

object
Error

PSA
B

-

Work

Library

Manager

B-3

Messages

File

Errors

it

opens
a
Plib86 runs out of memory
on disk named Plib86.WRK
to
file
of the library.
hold the description
These
error codes indicate a problem with
processing the work file.

when
woEk

30

can't
- Probably file
there is no
The

work

disk directory.

be created.
space
in

the

31

I/O error occurred while writing
- An
the work file.

32

I/O error occurred while reading
- Ari
the work file.

33

I/O error occurred while
- An
positioning
the work file.

34

There
are too many module
- description
objects in this library
and
50,000

(about

so

on

symbols, modules,
defined).
This
is too large for plib86 to

may be

library

handle.

Plib86:
Appendix

object
- Error

PSA
B

Input object

Library

Manager

B-4

Messages

File Errors

following errors have to do with the
object files that are given to plib86 to
Usually they occur when a file
process.
has been corrupted
somehow.
Try
re-compiling
to get a new copy of the
object file. If it is a library supplied
by the compiler manufacturer
that is
causing the problem, try to get a fresh
copy
of it.

The

41

—

premature end of input object file.
end of the indicated
file was
Possibly,
reached unexpectedly.
the file was truncated by copying
with a program
that assumes a
(IAH)
CNTL-Z
is end of file.
The

it

42

-

Fatal read error

file.

in object

input

plib86:
Áppendix

PSA
B

-

object
Error

Output

Library

Manager

B-5

Messages

File Errors

following errors are caused by a
problem in creating the output code file
or memory map file (when written to
disk). Often, they are caused by a full
a disk that is
dísk or disk directory,
write-protected,
or some kind of hardware
problem with the disk.
The

45

create output disk file.
- Can't
Possibly the disk directory is
full, or the disk is write
protected.

46

The given
Output file too large.
- modules
won't
into the library.
You will have fit
to break up the
library into one or wore smaller

ones.

47

write error in output
- Fatal disk
file. Possibly the disk is full or
write protected, or some kind of
hardware error has occurred.

48

read error
in output
- Fatal disk
An irrecoverable
hardware
file.

error

49

has

probably occurred.

close output file. The disk
- Can't
is probably writehas protected, or a
hardware error

50

occurred.

create the LIST output file.
- Can't
possibly the disk directory is
full, or the disk is write
protected.

plib86:
Appendix

PSA
B

-

object
Error

Library

Miscellaneous
51

symbols

There

one

or

more

smaller

modules
were selected
- library search,
INCLUDE,
be
EXCLUDE)
No

file
54

Errors
be

too many
to
- placed are
into the library index. You
will have to break up the library
into

52

B-6

Manager

Messages

(by
or

placed in the output

to

(BUILD

ones.

or

EXTRACT).

There
in the
isn't enough memory You
- computer
must
to run plib86.
have
a really tiny memory - better
buy more!

Plib86:
Appendix

PSA
B

object
- Error

Library

B-7

Manager

Messages

Plib86

Bugs

errors indicate a bug in Plib86 has
occurred through no fault of your own.
They are li8ted here for completeness in
the manual, although it is unlikely that
them.
Try
you can do anything to correct
again.
the
running plib86
error
If
persists,
please gather the relevant
information and contact Phoenix Software
Associates.
These

201
20S

-

No NeedRead
Seek

Buffers

errors while
(attempt to

file
file).

(NRnew).

writing output
end

seek

past

210

Requested
- (Newrec). record size too large

219

object block (GetBlock).
key (Q).
- Invalid object
key (QK).
- Invalid object

221
222

Bad

of

Plib86:
Appendix

PSA
C

-

C-l

object Library Mañager
Reporting problems

ask that you make a reasonable
solve your difficulties
to
effort
yourself before contacting us, and to
phone
only if you are trying to deal with
Otherwise, please report
an emergency.
We
can read
your problem in writing.
much more quickly
than we can listen.
Our address is:
We

Phoenix
Software Associates,
1420 providence Highway
Suite 260
MA
Norwood,
02062

Ltd.

Be sure to include with your
description
of the problem the input you
use and where
trying
to
your object
are
files came from.and If you like, send
on
input, object,
library files
5
(MSDOS
1/4 format,
diskettes
or 2.0
single or double sided), and instructions
on how to run the software to make the
Source
files are
error condition occur.
usually unnecessary. We will be happy to
sign non-disclosure agreements
to protect
your software, if having
will help us
identify a bug more quickly, and to
return the diskettes to you after the
problem has been identified.

l.l

it

LIFKbOiAT
form
u8é thíB
ABBocÍaCem

Ple&8e

Product

Ver6íorj

Wte
H8b

of
the

Boftv&re

Id
act

RKPORT

a6

a

Kedí&

SeríU

No.:

BupplIed

tranBmí[t&l

by
8Íleet.

Format:
No.:

Invoice

Froa:

Purchaee:

mftvnre

reglstmtíon

card

been

CPÚ (8080/B085/Z-dO):
Nmber

C&paclty:
Sy8tem/Ver8¿oQ

Operating

Softvare
reporting

(If

not

of

Drlveo:

liBted

B8Rple
or
come wLth
been &b1e to ubc tbm

Mmory

S1Ee:

l

&bove):

uBed vlth the
above
product, (e.g.
a problem
with m Payroll progrem
Nmme of Software

Docb che 8oftY&re
If bo, Mve you

t:

AuehorizmEFon
Kecurn
recurned?

[ked:

Co.puter
WbÍk

ñO6W

Name:

No.:

Purchaoed

sorrvw

to report error8 or problea8
Thh form i$ deB[Brbed to

Lifeboat
Software

ASSOCIATKS

int

that

the

BASIC

ubcb

ft).

umd

if

you

are

VerUon

té8t prograwH
BucceB8ful}y?

Include
reterence6
encountered.
to the
you Imve
the
problem
to reduce
to a wSmple teBt caBe.
programs
(preferably on dhk).
It you feel thA[ the
being
by the d[8k
m8y be camed
defective, you my prefer to retura the
the faBteDt
re&olutiorl of the
origlKj8l U8jl with U1Íb report to &chieve
problem.
m»y be
(U bo, cUI for & Return Authortzú£on No. a handjAmg cMrge
ch&r8e
or portion thereof io
& product
will be m&de
incurred. No handllmg
of
dete
DEYECTS
JO
d&yB
from
the
PQKDIA
wíthlm
ule).
returned DUB TO DISKKTTE
Pleaee
mwiudl
Enclo8e
proble®

deecríbe

the

problem
Try

ffaoyappropriate.
appropriate

it

0

Inform&tion
tu

publLBhed
PRQBLEK

on

product

Llfelimm

WSCRIPTION:

our

bugji,
fíxé$ and current
ooftware oevUetter.

(Cotltíaue

on

Md£tlonU

if

p&ge6

Phoñe

Mme:

(

)

Addre8B:

(

)

StÁte:

Return

to: Lifeboat MBoci&te8
1651 Third Avenue
Nev York,
N.Y., 10028

002prob.bn.09.8l

up

are

neceuary)

Aru

City:

Rumber8

verwion

ehAnBe8,

Wum

EXtw

"

(

)

"

(

)

Code:

Technicnl
í8 &v&llab]e
B8BIBtánce
üO mm.
Honday
Friday, from
É88terrj
to 7: 00 pm.,
tine.
1-(212)
860-0300
Telex:
64U693
TVX: 710-581-2524

ll:



File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
Linearized                      : No
Has XFA                         : No
XMP Toolkit                     : Adobe XMP Core 4.2.1-c041 52.342996, 2008/05/07-21:37:19
Format                          : application/pdf
Creator                         : 
Description                     : 
Title                           : 
Create Date                     : 2016:06:14 15:42:34-05:00
Creator Tool                    : ChronoScan
Modify Date                     : 2016:06:21 10:24:46-07:00
Metadata Date                   : 2016:06:21 10:24:46-07:00
Keywords                        : 
Producer                        : ChronoScan (http://www.chronoscan.org)
Document ID                     : uuid:da8b8cfa-19f4-674f-973c-1002675a9912
Instance ID                     : uuid:66b93091-ce2a-2241-8eac-d4b6280f180e
Page Layout                     : SinglePage
Page Mode                       : UseOutlines
Page Count                      : 272
PDF Version                     : 1.4
Author                          : 
Subject                         :