Microware Systems Corporation OS-9 C Compiler User Guide

 A an A
у A + . A Ma
РАНО
LEP TE
TERMS AND CONDITIONS OF SALE AND LICENSE OF RADIO SHACK
COMPUTER EQUIPMENT AND SOFTWARE PURCHASED FROM A
RADIO SHACK COMPANY-OWNED COMPUTER CENTER, RETAIL
os ел STORE OR FROM A RADIO SHACK FRANCHISEE OR DEALER AT ITS
7, 7 AUTHORIZED LOCATION
a =;
PE
COR
nt.
rm.
LIMITED WARRANTY
| 1. CUSTOMER OBLIGATIONS
A. CUSTOMER assumes full responsibility that this Radio Shack computer hardware purchased (the
“Equipment”), and any copies of Radio Shack software included with the Equipment or licensed
separately (the Software”) meets the specifications, capacity. capabilities, versatility, and other
requirements of CUSTOMER.
B. CUSTOMER assumes full responsibility for the condition and effectiveness of the operating
environment in which the Equipment and Software are to function, and for its installation.
RADIO SHACK LIMITED WARRANTIES AND CONDITIONS OF SALE
A. For a period of ninety (90) calendar days from the date of the Radio Shack sales document
received upon purchase of the Equipment, RADIO SHACK warrants to the original CUSTOMER that
the Equipment and the medium upon which the Software is stored is free from manufacturing
defects. THIS WARRANTY IS ONLY APPLICABLE TO PURCHASES OF RADIO SHACK EQUIPMENT
BY THE ORIGINAL CUSTOMER FROM RADIO SHACK COMPANY-OWNED COMPUTER CENTERS,
RETAIL STORES AND FROM RADIO SHACK FRANCHISEES AND DEALERS AT ITS AUTHORIZED
LOCATION. The warranty is void if the Equipment's case or cabinet has been opened, or if the
Equipment or Software has been subjected to improper or abnormal use. If a manufacturing defect
is discovered during the stated warranty period, the defective Equipment must be returned to a
Radio Shack Computer Center, a Radio Shack retail store, participating Radio Shack franchisee or
Radio Shack dealer for repair, along with a copy of the sales document or lease agreement. The
original CUSTOMER'S sole and exclusive remedy in the event of a defect is limited to the
correction of the defect by repair, replacement, or refund of the purchase price, at RADIO
SHACK'S election and soie expense. RADIO SHACK has no obligation to replace or repair
expendable items.
B. RADIO SHACK makes no warranty as to the design, capability, capacity, or suitability for use of
the Software, except as provided in this paragraph. Software is licensed on an “AS IS" basis,
without warranty. The original CUSTOMER'S exclusive remedy, in the event of a Software
manufacturing defect, is its repair or replacement within thirty (30) calendar days of the date of the
Radio Shack sales document received upon license of the Software. The defective Software shall
be returned to a Radio Shack Computer Center, a Radio Shack retail store, participating Radio
Shack franchisee or Radio Shack dealer along with the sales document.
C. Except as provided herein no employee, agent, franchisee, dealer or other person is authorized to
give any warranties of any nature on behalf of RADIO SHACK.
О. Except as provided herein, RADIO SHACK MAKES NO WARRANTIES, INCLUDING WARRANTIES
OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
E. Some states do not allow limitations on how long an implied warranty lasts, so the above
limitation(s) may not apply to CUSTOMER.
LIMITATION OF LIABILITY
A EXCEPT AS PROVIDED HEREIN, RADIO SHACK SHALL HAVE NO LIABILITY OR RESPONSIBILITY
TO CUSTOMER OR ANY OTHER PERSON OR ENTITY WITH RESPECT TO ANY LIABILITY, LOSS
OR DAMAGE CAUSED OR ALLEGED TO BE CAUSED DIRECTLY OR INDIRECTLY BY
“EQUIPMENT” OR “SOFTWARE” SOLD, LEASED, LICENSED OR FURNISHED BY RADIO SHACK,
INCLUDING, BUT NOT LIMITED TO, ANY INTERRUPTION OF SERVICE, LOSS OF BUSINESS OR
ANTICIPATORY PROFITS OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OR
OPERATION OF THE “EQUIPMENT” OR “SOFTWARE”. IN NO EVENT SHALL RADIO SHACK BE
LIABLE FOR LOSS OF PROFITS, OR ANY INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF ANY BREACH OF THIS WARRANTY OR IN ANY MANNER ARISING OUT OF OR
CONNECTED WITH THE SALE, LEASE, LICENSE, USE OR ANTICIPATED USE OF THE EQUIPMENT”
OR “SOFTWARE”.
continued
Nan À 23 oN ©
“ada 1 5 "argo. unten, oH =
5 1j
E В |
Я
NOTWITHSTANDING THE ABOVE LIMITATIONS AND WARRANTIES. RADIO SHACK'S LIABILITY
HEREUNDER FOR DAMAGES INCURRED BY CUSTOMER OR OTHERS SHALL NOT EXCEED THE
AMOUNT PAID BY CUSTOMER FOR THE PARTICULAR EQUIPMENT” OR “SOFTWARE”
INVOLVED.
В. RADIO SHACK shall not be liable for any damages caused by delay in delivering or furnishing
Equipment and or Software.
C. No action arising out of any claimed breach of this Warranty or transactions under this Warranty
may be brought more than two (2) years after the cause of action has accrued or more than four
(4) years after the date of the Radio Shack sales document for the Equipment or Software.
whichever first occurs.
D. Some states do not atlow the limitation or exclusion of incidental or consequential damages. so the
above limitation(s) or exclusion(s) may not apply to CUSTOMER
IV. RADID SHACK SOFTWARE LICENSE
RADIO SHACK grants to CUSTOMER a non-exclusive. paid-up license to use the RADIO SHACK Software
on one computer, subject to the following provisions:
A. Except as otherwise provided in this Software License. applicable copyright laws shall apply to the
Software.
В. Title to the medium on which the Software is recorded (cassette and or diskette) or stored (ROM)
is transferred to CUSTOMER. but not title to the Software.
GC. CUSTOMER may use Software on one host computer and access that Software through one or
more terminals if the Software permits this function.
D. CUSTOMER shall not use, make, manufacture. or reproduce copies of Software except for use on
one computer and as is specifically provided in this Software License. Customer is expressly
prohibited from disassembling the Software.
Е. CUSTOMER is permitted to make additional copies of the Software only for backup or archival
purposes or if additional copies are required in the operation of one computer with the Software,
but only to the extent the Software allows a backup copy to be made. However. for TRSDOS
Software. CUSTOMER 1s permitted to make a limited number of additional copies for
CUSTOMER'S own use.
F. CUSTOMER may resell or distribute unmodified copies of the Software provided CUSTOMER has
purchased one copy of the Software for each one sold or distributed. The provisions of this
Software License shall also be applicable to third parties receiving copies of the Software from
CUSTOMER.
G. All copyright notices shall be retained on all copies of the Software.
V. APPLICABILITY OF WARRANTY
A. The terms and conditions of this Warranty are applicabie as between RADIO SHACK and
CUSTOMER to either a sale of the Equipment and or Software License to CUSTOMER or to a
transaction whereby RADIO SHACK sells or conveys such Equipment to a third party for lease to
CUSTOMER.
B. The limitations of liability and Warranty provisions herein shall inure to the benefit of RADIO
SHACK. the author. owner and or licensor of the Software and any manufacturer of the Equipment
sold by RADIO SHACK.
VI. STATE LAW RIGHTS
The warranties granted herein give the original CUSTOMER specific iegal rights. and the original
CUSTOMER may have other rights which vary from state to state.
- TH Ea.
age," я я
ee Ч A ..
ve су99
Rs: 47
14408
C COMPILER
USER'S GUIDE
Copyright 1983 Microware Systems Corporation, All Rights Reserved.
Reproduction of this document, in part or whole, by any means,
electrical or otherwise, is prohibited, except by written permission
from Microware Systems Corporation.
The information contained herein is believed to be accurate as of
the date of publication, however, Microware will not be liable for
any damages, including indirect or consequential, from use of the
05-9 operating system or reliance on the accuracy of this
documentation. The information contained herein is subject to
change without notice,
Revision D
Publication date: August, 1983
Acknowledgements
The 05-9 С Compiler was written by James McCosh
with 05-9 implementation assistance from Larry
Crane and Kim Kempf. The Relocatable Assembler,
Linker, and Profiler were written by Larry Crane
and Kim Kempf. This manual was edited by Wes
Camden and Ken Kaplan,
MICROWARE C COMPILER USER'S GUIDE
Table of Contents
CHAPTER 1 - THE C COMPILER SYSTEM
Introduction 1-1
The Language Implementation 1-2
Differences From The K & R Specification 1-2
Enhancements And Extensions 1-3
The "Direct" Storage Class 1-3
Imbedded Assembly Language 1-4
Control Character Escape Sequences 1-4
Implementation-Dependent Characteristics 1-5
Data Representation and Storage 1-5
Register Variables 1-5
Access to Command Line Parameters 1-6
System Calls and The Standard Library 1-7
Run-Time Arithmetic Error Handling 1-8
Achieving Maximum Program Performance 1-9
Programming Considerations 1-9
The Optimizer Pass 1-9
The Profiler 1-9
C Compiler Component Files and File Usage 1-10
Running the Compiler 1-11
Compiler Option Flags 1-13
CHAPTER 2 ~ CHARACTERISTICS OF COMPILED PROGRAMS
The Object Code Module 2-1
Memory Management 2-4
C Program Memory Map 2-4
Compile Time Memory Allocation 2-6
CHAPTER 3 - SYSTEM CALLS
System Calls 3-1
CHAPTER 4 - STANDARD LIBRARY
Standard Library 4-1
APPENDIX A - COMPILER ERROR MESSAGES А-1
APPENDIX B - COMPILER PHASE COMMAND LINES B-1
APPENDIX C - INTERFACING TO BASICO9 C-1
APPENDIX D - THE RELOCATING MACRO ASSEMBLER D-1
Page i-1
MICROWARE C COMPILER USER'S GUIDE
THE C COMPILER SYSTEM
INTRODUCTION
The "С" programming language is rapidly growing in popularity
and seems destined to become one of the most popular programming
languages used for microcomputers. The rapid rise in the use of C
is not surprising. C is an incredibly versatile and efficient
language that can handle tasks that previously would have required
complex assembly language programming.
C was originally developed at Bell Telephone Laboratories as an
implementation language for the UNIX operating system by Brian
Kernighan and Dennis Ritchie. They also wrote a book titled "The C
Programming Language" which is universally accepted as the standard
for the language. It is an interesting reflection on the language
that although no formal industry-wide "standard" was ever developed
for С, programs written in C tend to be far more portable between
radically different computer system as compared to so-called
"standardized™ languages such as BASIC, COBOL, and PASCAL. The
reason C is so portable is that the language is so inherently
expandable that if some special function is required, the user can
create a portable extension to the language, as opposed to the
common practice of adding additional statements to the language.
For example, the number of special-purpose BASIC dialects defies all
reason. A lesser factor is the underlying UNIX operating system,
which is also sufficiently versatile to discourage
nonstandardization of the language. Indeed, standard C compilers
and Unix are intimately related.
Fortunately, the 6809 microprocessor, the 0S-9 operating
system, and the C language form an outstanding combination. The
6809 was specifically designed to efficiently run high-level
languages, and its stack-oriented instruction set and versatile
repertoire of addressing modes handle the C language very well. As
mentioned previously, UNIX and C are closely related, and because
05-9 is derived from UNIX, it also supports C to the degree that
almost any application written in C can be transported from a UNIX
system to an 0S-9 system, recompiled, and correctly executed.
Page 1-1
MICROWARE C COMPILER USER'S GUIDE
THE C COMPILER SYSTEM
THE LANGUAGE IMPLEMENTATION
08-9 С is implemented almost exactly as described in 'The С
Programming Language! by Kernighan and Ritchie (hereafter referred
to as К & КВ). A copy of this book, which serves as the language
reference manual, is included with each software package.
Although this version of C follows the specification faith-
fully, there are some differences. The differences mostly reflect
parts of C that are obsolete or the constraints imposed by memory
size limitations.
DIFFERENCES FROM THE K & R SPECIFICATION
- Bit fields are not supported.
- Constant expressions for initializers may include arithmetic
operators only if all the operands are of type INT or CHAR.
- The older forms of assignment operators, '=+' or '=#%' yhich
are recognized by some C compilers, are not supported. You
must use the newer forms '+=','#-=' etc.
- "fifdef (or tifndef) ...[#else...] #endif" is supported but
"#if <constant expression>" is not.
- It is not possible to extend macro definitions or strings
over more than one line of source code.
- The escape sequence for new-line '\n' refers to the ASCII
carriage return character (used by 0S-9 for end-of-line), not
linefeed.(hex 0A). Programs which use '\n' for end-of-line
(which includes all programs in K & R), will still work
properly.
Page 1-2
MICROWARE C COMPILER USER'S GUIDE
THE C COMPILER SYSTEM
ENHANCEMENTS AND EXTENSIONS
The "Direct" Storage Class
The 6809 microprocessor instructions for accessing memory via
an index register or the stack pointer can be relatively short and
fast when they are used in C programs to access "auto" (function
local) variables or function arguments. The instructions for
accessing global variables are normally not so nice and must be four
bytes long and correspondingly slow. However, the 6809 has a nice
feature which helps considerably. Memory, anywhere in a single page
(256 byte block), may be accessed with fast, two byte instructions.
This is called the "direct page", and at any tíme its location is
specified by the contents of the "direct page register" within the
processor, The linkage editor sorts out where this should be, and
it need not concern the programmer, who only needs to specify for
the compiler which variables should be in the direct page to give
the maximum benefit in code size and execution speed.
To this end, a new storage class specifier is recognized by the
compiler, In the manner of K & R page 192, the sc-specifier list
is extended as follows:
Sc-specifier: auto
static
extern
register
typedef
direct (extension)
extern direct (extension)
static direct (extension)
The new key word may be used in place of one of the other sc-
specifiers, and its effect is that the variable will be placed in
the direct page. "DIRECT" creates a global direct page variable.
"EXTERN DIRECT" references an EXTERNAL-type direct page variable;
and "STATIC DIRECT" creates a local direct page variable. These new
classes may not be used to declare function arguments. "Direct"
variables can be initialized but will, as with other variables not
explicitly initialized, have the value zero at the start of program
execution. 255 bytes are available in the direct page (the linker
requires one byte). If all the direct variables occupy less than the
full 255 bytes, the remaining global variables will occupy the
balance and memory above if necessary. If too many bytes of storage
are requested in the direct page, the linkage editor will report an
error, and the programmer will have to reduce the use of DIRECT-type
variables to fit the 256 bytes addressable by the 6809.
It should be kept in mind that "direct" is unique to this
compiler, and it may not be possible to transport programs written
using "direct" to other environments without modification.
Page 1-3
MICROWARE C COMPILER USER'S GUIDE
THE C COMPILER SYSTEM
Imbedded Assembly Language
As versatile as C is, occasionally there are some things that
can only be done (or done at maximum speed) in assembly language.
The 0S-9 C compiler permits user-supplied assembly-language
statements to be directly embedded in C source programs.
A line beginning with "#asm" switches the compiler into a mode
which passes all subsequent lines directly to the assembly-language
output, until a line beginning with "fendasn" is encountered.
"fendasm" switches the mode back to normal. Care should be
exercised when using this directive so that the correct code section
is adhered to. Normal code from the compiler is in the PSECT (code)
section. If your assembly code uses the VSECT (variable) section,
be sure to put a ENDSECT directive at the end to leave the state
correct for following compiler generated code.
Control Character Escape Sequences
The escape sequences for non-printing characters in character
constants and strings (see K & R page 181) are extended as follows:
linefeed (LF): “1 (lower case 'ell')
This is to distinguish LF (hex OA) from wm which оп 0S-9 is the same
as \r (hex 0D).
bit patterns: \NNN (octal constant)
\dNNN (decimal constant)
\xNN (hexadecimal constant)
For example, the following all have a value of 255 (decimal):
\377 \xff \d255
Page 1-4
MICROWARE C COMPILER USER'S GUIDE
THE C COMPILER SYSTEM
IMPLEMENTATION DEPENDENT CHARACTERISTICS
K & R frequently refer to characteristics of the C language
whose exact operations depend on the architecture and instruction
set of the computer actually used. This section contains specific
information regarding this version of C for the 6809 processor.
Data Representation and Storage Requirements
Each variable type requires a specific amount of memory for
storage. The sizes of the basic types in bytes are as follows:
Data Type Size Internal Representation
CHAR 1 two's complement binary
INT 2 two's complement binary
UNSIGNED 2 unsigned binary
LONG 4 two's complement binary
FLOAT 4 binary floating point (see below)
DOUBLE 8 binary floating point (see below)
This compiler follows the PDP-11 implementation and format in
that CHARs are converted to INTs by sign extension, "SHORT" or
"SHORT INT" means INT, "LONG INT" means LONG, and "LONG FLOAT" means
DOUBLE. The format for DOUBLE values is as follows:
(low byte) (high byte)
+-+------------------------------------- +=-=-=--——— +
{ 1 seven byte ! 1 byte !
{ 1! mantissa | exponent |
mre 0 +---------- + ’
“ sign bit
The form of the mantissa is sign and magnitude with an implied
"1" bit at the sign bit position. The exponent is biased by 128.
The format of a FLOAT is identical, except that the mantissa is only
three bytes long. Conversion from DOUBLE to FLOAT is carried out by
truncating the least significant (right-most) four bytes of the
mantissa. The reverse conversion is done by padding the least
significant four mantissa bytes with zeros,
Register Variables
One register variable may be declared in each function. The
only types permitted for register variables are int, unsigned and
pointer. Invalid register variable declarations are ignored; i.e,
the storage class is made auto. For further detaiis see K & R page
81.
Page 1-5
MICROWARE C COMPILER USER'S GUIDE
THE C COMPILER SYSTEM
A considerable saving in code size and speed can be made by
judicious use of a register variable. The most efficient use is
made of it for a pointer or a counter for a loop. However, if a
register variable is used in a complex arithmetic expression, there
is no saving. The "U" register is assigned to register variables.
IMPORTANT NOTE: Upper and lower case letters cannot be mixed as in
Basic09. For example, Prog.c and prog.c are distinct names. Since
the Color Computer is usually used in upper case only, it is
necessary to enter the following commands to use upper AND lower
case: TMODE -UPC and CLEAR<O>.
Access To Command Line Parameters
The standard С arguments Marge" and "argv" are available to
"main" as described in K € R page 110. The start-up routine for C
programs ensures that the parameter string passed to it by the
parent process is converted into null-terminated strings as expected
by the program. In addition, it will run together as a single
argument any strings enclosed between single or double quotes (n'n
or mm), If either is part of the string required, then the other
should be used as a delimiter.
Page 1-6
MICROWARE C COMPILER USER'S GUIDE
THE C COMPILER SYSTEM
SYSTEM CALLS AND THE STANDARD LIBRARY
Operating System Calls
The system interface supports almost all the system calls of
both 0S-9 and UNIX. In order to facilitate the portability of
programs from UNIX, some of the calls use UNIX names rather than
0S-9 names for the same function. There are a few UNIX calls that
do not have exactly equivalent 0S~9 calls. In these cases, the
library function simulates the function of the corresponding UNIX
call, In cases where there are 05-9 calls that do not have UNIX
equivalents, the 05-9 names are used. Details of the calls and a
name cross-reference are provided in the "C System Calls" section of
this manual.
The Standard Library
The C compiler includes a very complete library of standard
functions. It is essential for any program which uses functions
from the standard library to have the statement:
"finclude <stdio.h>"
See the "C Standard Library" section of this manual for details on
the standard library functions provided.
IMPORTANT NOTE: If output via printf(), fprintf() or sprintf() of
long integers is required, the program MUST call "pflinit()" at some
point; this is necessary so that programs not involving LONGs do not
have the extra LONGs output code appended. Similarly, if FLOATs or
DOUBLEs are to be printed, "pffinit()" MUST be called. These func-
tions do nothing; existence of calls to them in a program informs
the linker that the relevant routines are also needed.
Page 1-7
MICROWARE C COMPILER USER'S GUIDE
THE C COMPILER SYSTEM
RUN-TIME ARITHMETIC ERROR HANDLING
K & В leave the treatment of various arithmetic errors open,
merely saying that it is machine dependent. This implementation
deals with a limited number of error conditions in a special way; it
should be assumed that the results of other possible errors are
undefined.
Three new system error numbers are defined in <errno.h>:
define EFPOVR 40 /* floating point overflow or underflow */
#define EDIVERR 41 /* division by zero */
#define EINTERR 42 /* overflow on conversion of floating point
to long integer */
If one of these conditions occur, the program will send a
signal to itself with the value of one of these errors. If not
caught or ignored, this will cause termination of the program with
an error return to the parent process. However, the program can
catch the interrupt using "signal()" or "intercept()" (see C System
Calls), and in this case the service routine has the error number as
its argument.
Page 1-8
MICROWARE C COMPILER USER'S GUIDE
THE C COMPILER SYSTEM
ACHIEVING MAXIMUM PROGRAM PERFORMANCE
Programming Considerations
Because the 6809 13 ап 8/16 bit microprocessor, the compiler
can generate efficient code for 8 and 16 bit objects (CHARs, INTs,
etc.). However, code for 32 and 64 bit values (LONGs, FLOATs,
DOUBLEs) can be at least four times longer and slower. Therefore
don't use LONG, FLOAT, or DOUBLE where INT or UNSIGNED will do.
The compiler can perform extensive evaluation of constant
expressions provided they involve only constants of type CHAR, INT,
and UNSIGNED. There is no constant expression evaluation at
compile-time (except single constants and "casts" of them) where
there are constants of type LONG, FLOAT, or DOUBLE, therefore,
complex constant expressions involving these types are evaluated at
run time by the compiled program. You should manually compute the
value of constant expressions of these types if speed is essential.
The Optimizer Pass
The optimizer pass automatically occurs after the compilation
passes. It reads the assembler source code text and removes
redundant code and searches for code sequences that can be replaced
by shorter and faster equivalents. The optimizer will shorten object
code by about 11% with a significant increase in program execution
speed. The optimizer is recommended for production versions of de-
bugged programs. Because this pass takes additional time, the "-0"
compiler option can be used to inhibit it during error-checking-only
compilations.
The Profiler
The profiler is an optional method used to determine the
frequency of execution of each function in a C program, It allows
you to identify the most frequently used functions where algorithmic
ог С source code programming improvements will yield the greatest
gains,
When the "-P" compiler option is selected, code is generated at
the beginning of each function to call the profiler module (called
N prof"), which counts invocations of each function during program
execution. When the program has terminated, the profiler
automatically prints a list of all functions and the number of times
each was called. The profiler slightly reduces program execution
speed. See "prof.c" source for more information.
Page 1-9
MICROWARE C COMPILER USER'S GUIDE
THE C COMPILER SYSTEM
C COMPILER COMPONENT FILES AND FILE USAGE
Compilation of a C program by cc requires that the following
files be present in the current execution directory (CMDS).
05-9 Level I Systems:
cel compiler executive program
c.prep macro pre-processor
c.pass]1 compiler pass 1
C.pass2 compiler pass 2
c.opt assembly code optimizer
c.asm relocating assembler
c.link linkage editor
OS-9 Level II Systems:
ca? compiler executive program
c.prep macro pre-processor
CC. COMP compiler proper
c.opt assembly code optimizer
c.asm relocating assembler
c.link linkage editor
In addition a file called "clib.1" contains the standard lib-
rary, math functions, and system library. The file "estart.r” is
the setup code for compiled programs. Both of these files must be
located in a directory named "LIB" on drive /D1. The DEFS directory
must also be on /D1.
If, when specifying "#include" files for the preprocessor to
read in, the programmer uses angle brackets, "<" and ">", instead of
parentheses, the file will be sought starting at the "DEFS"
directory.
Temporary Filles
A number of temporary files are created in the current data
directory during compilation, and it is important to ensure that
enough space is available on the disk drive. As a rough guide, at
least three times the number of blocks in the largest source file
(and its included files) should be free.
The identifiers "etext","edata”", and "end" are predefined in the
linkage editor and may be used to establish the addresses of the end
of executable text, initialized data, and uninitialized data
respectively,
Page 1-10
MICROWARE C COMPILER USER'S GUIDE
THE C COMPILER SYSTEM
RUNNING THE COMPILER
There are two commands which invoke distinct versions of the
compiler. "ceci" is for 0S-9 Level I which uses a two pass compiler,
and, c¢c2 is for Level II which uses a single pass version. Both
versions of the compiler work identically, the main difference is
that ссе1 has been divided into two passes to fit the smaller memory
size of 05-9 Level I systems. In the following text, "cc" refers to
either "cc1" or "ce?" as appropriate for your system. The syntax of
the command line which calls the compiler is:
ce [ option-flags ] file {file}
One file at a time can be compiled, or a number of files may be
compiled together. The compiler manages the compilation through up
to four stages: pre-processor, compilation to assembler code,
assembly to relocatable module, and linking to binary executable
code (in 0S-9 memory module format).
The compiler accepts three types of source files, provided each
name on the command line has the relevant postfix as shown below.
Any of the above file types may be mixed on the command line.
File Name Suffix Conventions
Suffix Usage
‚ © C source file
. a assembly language source file
‚Г relocatable module
none executable binary (0S-9 memory module)
There are two modes of operation: multiple source file and
single source file. The compiler selects the mode by inspecting
the command line. The usual mode is single source and is specified
by having only one source file name on the command line. of
course, more than one source file may be compiled together by using
the "#finclude" facility in the source code. In this mode, the
compiler will use the name obtained by removing the postfix from the
name supplied on the command line, and the output file (and the
memory module produced) will have this name, For example:
ce prg.c
will leave an executable file called "prg" in the current execution
directory.
The multiple source mode is specified by having more than one
Page 1-11
MICROWARE C COMPILER USER'S GUIDE
THE C COMPILER SYSTEM
source file name on the command line. In this mode, the object code
output file will have the name "output" in the current execution
directory, unless a name is given using the "-f=" option (see
below). Also, in multiple source mode, the relocatable modules
generated as intermediate files will be left in the same directories
as their corresponding source files with the postfixes changed to
",г", For example:
ce prgli.c /d0/fred/prg2.c
will leave an executable file called "output" in the current
execution directory, one called "prgi.r" in the current data
directory, and "prg2.r" in "/d0/fred".
CC -E=3 PNAME.C -F=PROG
compiles the file called "PNAME.C" into an executable object file
named "PROG" and sets the module revision level to 3.
CC PROG.C -DIDENTIFIER=VALUE
compiles the program with a definition identifier being passed to
the compiler. The definition being passed is used within the source
to control compilation via IFDEF/IFNDEF functions.
Page 1-12
MICROWARE C COMPILER USER'S GUIDE
THE C COMPILER SYSTEM
COMPILER OPTION FLAGS
The compiler recognizes several command-line option flags which
modify the compilation process where needed. All flags are
recognized before compilation commences so the flags may be placed
anywhere on the command line. Flags may be ran together as in "-
ro", except where а flag is followed by something else; see "-f="
and "-d" for examples.
—A suppresses assembly, leaving the output as assembler code in a
file whose name is postfixed ".a",
-Ex<number> Set the edition number constant byte to the number
given. This is an 0S-9 convention for memory modules.
-0 inhibits the assembly code optimizer pass. The optimizer will
shorten object code by about 11% with a comparable increase in speed
and is recommended for production versions of de-bugged programs.
-P invokes the profiler to generate function invocation frequency
statistics after program execution.
- Е suppresses linking library modules into an executable program.
Outputs are left in files with postfixes ",r",
-M=<memory size> will instruct the linker to allocate <memory size)
for data, stack, and parameter area. Memory size may be expressed
in pages (an integer) or in kilobytes by appending "К" to an
integer, For more details of the use of this option, see the
"Memory Management" section of this manual.
-L=<filename> specifies a library to be searched by the linker
before the Standard Library and system interface.
«F=<path> overrides the above output file naming. The output file
will be left with <filename> as its name. This flag does not make
sense in multiple source mode, and either the -a or -r flag is also
present. The module will be called the last name in <path>.
-C will output the source code as comments with the assembler code.
-S stops the generation of stack-checking code. -S should only be
used with great care when the application is extremely time-critical
and when the use of the stack by compiler generated code is fully
understood.
-D identifier> is equivalent to "#define <identifier>" written in
the source file. -D is useful where different versions of a program
are maintained in one source file and differentiated by means of the
Tfifdef" or "fifndef" pre-processor directives. If the <identifier>
is used as a macro for expansion by the pre-processor, "1"(one) will
Page 1-13
MICROWARE C COMPILER USER'S GUIDE
THE C COMPILER SYSTEM
be the expanded "value" unless the form "-d<identifier>=<string>" is
used in which case the expansion will be <string>.
COMMAND LINE AND OPTION FLAG EXAMPLES
command line action output file(s)
ce prg.c compile to an executable prg
program
ce prg.c -a compile to assembly prg.a
language source code
ce prg.c -r compile to relocatable prg.r
module
cc prgi.c prg2.c prg3.c compile to executable prgi.r, prge.r,
program prg3.r, output
cc prgi.c prg2.a prg3.r compile prgi.c, pregi.r, prg2.r
assemble prg2.a and
combine all into an
executable program
ee prgl.c prg2.c -a compile to assembly prgl.a, prg2.a
language source code
ce prgl.c prg2.ec -f=prg compile to executable prg
program
Page 1-14
MICROWARE C COMPILER USER'S GUIDE
CHARACTERISTICS OF COMPILED PROGRAMS
The Object Code Module
The compiler produces position-independent, reentrant 6809 code
in a standard 0S-9 memory module format. The format of an execut-
able program module is shown below. Detailed descriptions of each
section of the module are given on following pages.
Module Section
Offset Size (bytes)
+ re ——— o ————]————]———] _——]— +
$00 ] !
! Module Header ! 8
! 1
EE
$09 ! Execution Offset В ---+ 2
aa a debate ! !
$0B ! Permanent Storage Size ! ! 2
|----еееенеененеенеенеееенеее--- ! !
$0D ! Module Name ! !
Yo e e a e e e e e e e e e | !
у у <--+
Executable Code
String Literals
Page 2-1
MICROWARE C COMPILER USER'S GUIDE
CHARACTERISTICS OF COMPILED PROGRAMS
Module Header
This is a standard module header with the type/language byte set to
$11 (Program + 6809 Object Code), and the attribute/revision byte
set to $81 (Reentrant + 1).
Execution Offset
Used Бу 05-9 to locate where to start execution of the program.
storage Size
Storage size is the initial default allocation of memory for data,
stack, and parameter area. For a full description of memory
allocation, see the section entitled "Memory Management" located
elsewhere in this manual.
Module Name
Module name is used by 0S-9 to enter the module in the module
directory, The module name is followed by the edition byte encoded
in cstart. If this situation is not desired it may be overridden by
the -E= option in ce.
Information
Any strings preceded by the directive "info" in an assembly code
file will be placed here. A major use of this facility is to place
in the module the version number and/or a copyright notice. Note
that the 'fasm' pre-compiler instruction may be used in a C source
file to enable the inclusion of this directive in the compiler-
generated assembly code file.
Executable Code
The machine code instructions of the program.
string Literals
Quoted strings in the C source are placed here. They are in the
null-terminated form expected by the functions in the Standard
Library. NOTE: the definition of the C language assumes that
strings are in the DATA area and are therefore subject to alteration
without making the program non-reentrant. However, in order to avoid
the duplication of memory requirements which would be necessary if
they were to be in the data area, they are placed in the TEXT
(executable) section of the module. Putting the strings in the
Page 2-2
MICROWARE C COMPILER USER'S GUIDE
CHARACTERISTICS OF COMPILED PROGRAMS
executable section implies that no attempt should be made by a C
programmer to alter string literals. They should be copied out
first. The exception that proves the rule is the initialization of
an array of type char like this:
char message[] = "Hello world\n";
The string will be found in the array 'message' in the data area and
can be altered.
Initializing Data and its Size
If a C program contains initializers, the data for the initial
values of the variables is placed in this section. The definition
of C states that all uninitialized global and static variables have
the value zero when the program starts running, so the startup
routine of each C program first copies the data from the module into
the data area and then clears the rest of the data memory to nulls.
Data References
No absolute addresses are known at compile time under 0S-9, so where
there are pointer values in the initializing data, they must be
adjusted at run time so that they reflect the absolute values at
that time. The startup routine uses the two data reference tables
to locate the values that need alteration and adjusts them by the
absolute values of the bases of the executable code and data re-
spectively.
For example, suppose there are the following statements in the
program being compiled:
char *p = "I'm a string!":
char **q = &р;
These declarations tell the compiler that there is to be a char
pointer variable, 'p', whose initial value is the address of the
string and a pointer to a char pointer, 'q', whose initial value is
the address of 'p'. The variables must be in the DATA section of
memory at run time because they are potentially alterable, but
absolute addresses are not known until run time, so the values that
‘р! and 'q' must have are not known at compile time. The string
will be placed by the compiler in the TEXT section and will not be
copied out to DATA memory by the startup routine. The initializing
data section of the program module will contain entries for 'p' and
та’. They will have as values the offsets of the string from the
base of the TEXT section and the offset of the location of 'p'! from
the base of the DATA section respectively.
The startup routine will first copy all the entries in the initial-
izing data section into their allotted places in the DATA section.
Page 2-3
MICROWARE C COMPILER USER'S GUIDE
CHARACTERISTICS OF COMPILED PROGRAMS
Then it will scan the data-text reference table for the offsets of
values that need to have the addresses of the base of the TEXR
section added to them. Among these will be "р" which, after
updating, will point to the string which is in the TEXT section.
Similarly, after a scan of the data-data references, "q" will point
to( contain the absolute of) "p",
MEMORY MANAGEMENT
The C compiler and its support programs have default conditions
such that the average programmer need not be concerned with details
ot memory management. However, there are situations where advanced
programmers may wish to tailor the storage allocation of a program
for special situations. The following information explains in
detail how a C program's data area is allocated and used.
Typical C Program Memory Map
A storage area is allocated by 0S-9 when the C program is executed.
The layout of this memory is as follows:
high addresses
| ! <- SBRK() adds more
! memory here
| |
1 |
+ -е-- = + <- menend
! parameters !
| !
! !
Current stack | stack | «= sp register
reservation -> le 0 0 1 00 00 5 080000000000 !
у
!
| <- standard I/O buffers
! allocated here
!
Current top
of data -> esereoce, I <- IBRK() changes this
! ! memory bound upward
! requested memory |
errr eee ! <-- end
! uninitialized !
! data !
a 1 <-- edata
! initialized !
! data !
essen !
^ ! direct page !
dpsiz ! variables !
у + + <-- y,dp registers
low addresses
Page 2-4
MICROWARE C COMPILER USER'S GUIDE
CHARACTERISTICS OF COMPILED PROGRAMS
The overall size of this memory area is defined by the "storage
size" value stored in the program's module header. This can be
overridden to assign the program additional memory if the 05-9 Shell
"7" command is used.
The parameter area is where the parameter string from the
calling process (typically the 0S-9 Shell) is placed by the system.
The initializing routine for C programs converts the parameters into
null-terminated strings and makes pointers to them available to
'main()' via 'агдс' and 'argv!.
The stack area is the currently reserved memory for exclusive
use of the stack. As each C function is entered, a routine in the
system interface is called to reserve enough stack space for the use
of the function with an addition of 64 bytes. The 64 bytes are for
the use of user-written assembly code functions and/or the system
interface and/or arithmetic routines. A record 15 kept of the
lowest address so far granted for the stack. If the area requested
would not bring this lower then the C function is allowed to
proceed. If the new lower limit would mean that the stack area
would overlap the data area, the program stops with the message:
#### STACK OVERFLOW ####
on the standard error output. Otherwise, the new lower limit is
set, and the C function resumes as before.
The direct page variables area is where variables reside
that have been defined with the storage class 'direct' in the C
source code or in the ’'direct' segment in assembly code source.
Notice that the size of this area is always at least one byte (to
ensure that no pointer to a variable can have the value NULL or 0)
and that it is not necessarily 256 bytes.
The uninitialized data area is where the remainder of the
uninitialized program variables reside. These two areas are, in
fact, cleared to all zeros by the program entry routine. The
initialized data area is where the initialized variables of the
program reside. There are two globally defined values which may be
referred to: 'edata' and 'end', which are the addresses of one byte
higher than the initialized data and one byte higher than the
uninitialized data respectively. Note that these are not variables;
the values are accessed in C by using the '&' operator as in:
high = &end;
low = &edata;
and in assembler:
leax end, y
stx high,y
The Y register points to the base of the data area and variables are
Page 2-5
MICROWARE C COMPILER USER'S GUIDE
CHARACTERISTICS OF COMPILED PROGRAMS
addresses using Y-offset indexed instructions.
When the program starts running, the remaining memory is
assigned to the "free" area. A program may call "ibrk()" to
request additional working memory (initialized to zeros) from the
free memory area. Alternatively, more memory can be dynamically
obtained using the "sbrk()" which requests additional memory from
the operating system and returns its lower bound. If this fails
because 0S-9 refuses to grant more memory for any reason "sbrk()"
will return -1.
Compile Time Memory Allocation
If not instructed otherwise, the linker will automatically
allocate 1k bytes more than the total size of the program's
variables and strings. This size will normally be adequate to cover
the parameter area, stack requirements, and Standard Library file
buffers. The allocation size may be altered when using the compiler
by using the "-m" option on the command line. The memory
requirements may be stated in pages, for example,
ce prg.c -m=2
which allocates 512 bytes extra, or in kilobytes, for example:
cc prg,c -m=10k.
The linker will ignore the request if the size is less than 256
bytes.
The following rules can serve as a rough guide to estimate how
much memory to specify:
1. The parameter area should be large enough for any anticipated
command line string.
2. The stack should be not less than 128 bytes and should take
into account the depth of function calling chains and any
recursion.
3. All function arguments and local variables occupy stack space
and each function entered needs 4 bytes more for the return
address and temporary storage of the calling function's register
variable.
4, Free memory is requested by the Standard Library I/0
functions for buffers at the rate of 256 bytes per accessed
file. This does not apply to the lower level service request I/0
functions such as "open()", "read()" or "write()" nor to
"stderr" which is always un-buffered, but it does apply to both
"stdin" and "stdout" (see the Standard Library documentation).
Page 2-6
MICROWARE C COMPILER USER'S GUIDE
CHARACTERISTICS OF COMPILED PROGRAMS
A good method for getting a feel for how much memory is
needed by your program is to allow the linker to set the memory size
to its usually conservative default value. Then, if the program runs
with a variety of input satisfactorily but memory is limited on the
system, try reducing the allocation at the next compilation. If a
stack overflow occurs or an "ibrk()" call returns -1, then try
increasing the memory next time. You cannot damage the system by
getting it wrong, but data may be lost if the program runs out of
space at a crucial time. It pays to be in error on the generous
side,
Page 2-7
MICROWARE C COMPILER USER'S GUIDE
CHARACTERISTICS OF COMPILED PROGRAMS
Page 2-8
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
INTRODUCTION TO C SYSTEM CALLS
This section of the C compiler manual is a guide to the system
calls available from C programs.
It is NOT intended as a definitive description of 0S-9 service
requests as these are described in the 05-9 SYSTEM PROGRAMMER'S
MANUAL. However, for most calls, enough information is available
here to enable the programmer to write system calls into programs
without looking further.
The names used for the system calls are chosen so that programs
transported from other machines or operating systems should compile
and run with as little modification as possible. However, care
should be taken as the parameters and returned values of some calls
may not be compatible with those on other systems. Programmers that
are already familiar with 05-9 names and values should take
particular care. Some calls do not share the same names as the 05-9
assembly language equivalents. The assembly language equivalent
call is shown, where there is one, on the relevant page of the C
call description, and a cross-reference list is provided for those
already familiar with 0S-9 calls.
The normal error indication on return from a system call is a
returned value of -1. The relevant error will be found in the pre-
defined int "errno". Errno always contains the error from the last
erroneous system call. Definitions for the errors for inclusion in
the program are in "<errno.h>",
In the "SEE ALSO" sections on the following pages, unless
otherwise stated, the references are to other system calls,
Where "finclude" files are shown, it is not mandatory to
include them, but it might be convenient to use the manifest
constants defined in them rather than integers; it certainly makes
for more readable programs.
Page 3 - 1
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Abort - stop the program and produce a core dump
USAGE
abort ()
DESCRIPTION
This call causes a memory image to be written out to the file
"core" in the current directory, and then the program exits
with a status of 1.
Page 3 - 2
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Abs - Absolute value
USAGE
int abs(i)
int 1;
DESCRIPTION
ABS returns absolute value of its integer operand.
CAVEATS
You get what the hardware gives on the largest negative number.
Page 3 - 3
USAGE
DESCR
CAVEA
DIAGN
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Access - give file accessibility
access(fname, perm)
char *name;
int perm,
IPTION
Access returns 0 if the access modes specified in "perm"
correct for the user to access "fname", -1 is returned if
file cannot be accessed.
The value for "perm" may be any legal 05-9 mode as used
"open()" or "creat()", it may be zero, which tests whether
file exists, or the path to it may be searched.
TS
are
the
for
the
NOTE that the “"perm" value is NOT compatible with other
systems,
OSTICS
The appropriate error indication, if a value of -1 is returned,
may be found in "errno",
Page 3 - 4
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Chain - load and execute a new program
USAGE
chain(modname, paramsize, paramptr,type,lang,datasize)
char *modname, *paramptr;
ASSEMBLER EQUIVALENT
os9 F$CHAIN
DESCRIPTION
The action of F$CHAIN is described fully in the 0S-9
documentation. Chain implements the service request as
described with one important exception: chain will NEVER return
to the caller. If there is an error, the process will abort
and return to its parent process. It might be wise, therefore,
for the program to check the existence and access permissions
of the module before calling chain. Permissions may be checked
by using "modlink()" or "modload()" followed by an "munlink( 3".
"Modname™ should point to the name of the desired module.
"Paramsize" is the length of the parameter string (which should
normally be terminated with a "\n"), and "paramptr" points to
the parameter string. "Type" is the module type as found in
the module header (normally 1: program), and "lang" should
match the language nibble in the module header (C programs
have 1 for 6809 machine code here). "Datasize" may be zero, or
it may contain the number of 256 byte pages to give to the new
process as initial allocation of data memory.
Page 3 - 5
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Chdir,Chxdir - change directory
USAGE
chdir(dirname)
char *dirname;
chxdir(dirname)
char *dirname;
ASSEMBLER EQUIVALENT
0OS9 I$CHGDIR
DESCRIPTION
These calis change the current data directory and the current
execution directory, respectively, for the running task.
"Dirname" is a pointer to a string that gives a pathname for a
directory.
DIAGNOSTICS
Each call returns 0 after a successful call, or -1 if "dirname"
is not a directory path name, or it is not searchable.
SEE ALSO
0S-9 shell commands "chd" and "ehx",
Page 3 - 6
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Chmod - change access permissions of a file
USAGE
#include <modes.h>
chmod(fname,perm)
char *fname;
DESCRIPTION
Chmod changes the permission bits associated with a file.
"Fname™ must be a pointer to a file name, and "perm" should
contain the desired bit pattern.
The allowable bit patterns are defined in the include file as
follows:
/* permissions */
define S_IREAD 0x01 /* owner read */
tdefine S_IWRITE 0x02 /* owner write */
define S EXEC 0x04 /* owner execute */
¿define S_IOREAD 0x08 /* public read */
#define S_IOWRITE 0x10 /* public write */
#define S_IOEXEC 0x20 /* public execute */
#define S_ISHARE Ox40 /* sharable */
#define S_IFDIR 0x80 /* directory */
Only the owner or the super user may change the permissions of
a file.
DIAGNOSTICS
A successful call returns NULL(O). А -1 18 returned if the
caller is not entitled to change permissions or "fname" cannot
be found.
SEE ALSO
OS-9 command "attr"
Page 3 - 7
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Chown - change the ownership of a file
USAGE
chown( fname,ownerid)
char *fname;
DESCRIPTION
This call is available only to the super user. "Fname" is a
pointer to a file name, and "ownerid" is the new user-id.
DIAGNOSTICS
Zero is returned from a successful call. =1 is returned on
error.
Page 3 - 8
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Close - close a file
USAGE
close(pn)
ASSEMBLER EQUIVALENT
os9 I$CLOSE
DESCRIPTION
Close takes a path number, "pn", as returned from system calls
"open()", "creat()", or "dup()", and closes the associated
file.
Termination of a task always closes all open files
automatically, but it is necessary to close files where
multiple files are opened by the task, and it is desired to
re-use path numbers to avoid going over the system or process
path number limit.
SEE ALSO
creat (),open(),dup().
Page 3 - 9
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Crc - compute a cyclic redundancy count
USAGE
crc(start,count,accum)
char *start,accum[3];
ASSEMBLER EQUIVALENT
0s9 F$CRC
DESCRIPTION
This call accumulates a crc into a three byte array at "accun”
for "count" bytes starting at "start", All three bytes of
"accum" should be initialized to Oxff before the first call to
"cre()". However, repeated calls can be subsequently made to
cover an entire module. If the result is to be used as an 05-9
module ere, it should have its bytes complemented before
insertion at the end of the module.
Page 3 - 10
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Creat ~ create a new file
USAGE
finclude <modes.,h>
creat( fname, perm)
char *fname;
ASSEMBLER EQUIVALENT
os9 I$CREATE
DESCRIPTION
Creat returns a path number to a new file available for
writing, giving it the permissions specified in "рег" and
making the task user the owner. If, however, "fname" is the
name of an existing file, the file is truncated to zero length,
and the ownership and permissions remain unchanged. NOTE,
that unlike the 0S-9 assembler service request, c¢reat does
not return an error if the file already exists. M"Access()"
should be used to establish the existence of a file if it is
important that a file should not be overwritten.
It is unnecessary to specify writing permissions in "perm" in
order to write to the file in the current task,
The permissions allowed are defined in the include file as
follows:
/* permissions */
fdefine S IPRM Oxff /* mask for permission bits */
fdefine S_IREAD 0x01 /* owner read */
#define S_IWRITE 0x02 /* owner write #/
define S_IEXEC Ox04 /* owner execute */
define S_IOREAD 0x08 /* public read */
¿define S_IOWRITE 0x10 /* public write */
define S_IOEXEC 0x20 /* public execute #/
#define S_ISHARE 00x40 /* sharable #*/
Directories may not be created with this call; use "mknod()"
instead.
DIAGNOSTICS
This call returns -1 if there are too many files open. If the
pathname cannot be searched, if permission to write is denied,
or if the file exists and is a directory.
SEE ALSO
write(),close(),chmod()
Page 3 = 11
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Defdrive - get default system drive
USAGE
char *defdrive()
DESCRIPTION
A call to defdrive returns a pointer to a string containing the
name of the default system drive. The method used is to
consult the "Tnit" module for the default directory name. The
name is copied to a static data area and a pointer to it is
returned.
DIAGNOSTICS
-1 is returned if the "Init" module cannot be linked to.
Page 3 - 12
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Dup - duplicate an open path number
USAGE
dup ( pn)
ASSEMBLER EQUIVALENT
os9 I$DUP
DESCRIPTION
Dup takes the path number, "pn", as returned from "open( )" or
"creat()" and returns another path number associated with the
same file.
DIAGNOSTICS
A -1 is returned if the call fails because there are too many
files open or the path number is invalid.
SEE ALSO
open(),creat(),close()
Page 3 - 13
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Exit, Exit - task termination
USAGE
exit(status)
_exit(status)
ASSEMBLER EQUIVALENT
os9 FS$EXIT
DESCRIPTION
Exit is the normal means of terminating a task. Exit does any
cleaning up operations required before terminating, such as
flushing out any file buffers (see Standard I/0), but _exit
does not.
A task finishing normally, that is returning from "main()",
is equivalent to a call - "exit(0)".
The status passed to exit is available to the parent task if it
is executing a "wait".
SEE ALSO
wait()
Page 3 - 14
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Getpid - get the task id
USAGE
getpid()
ASSEMBLER EQUIVALENT
0s9 F$ID
DESCRIPTION
A number unique to the current running task is often useful in
creating names for temporary files. This call returns the
task's system id (as returned to its parent by "os9fork").
SEE ALSO
,Si 5
os9fork() Standard Library function mktemp.
Page 3 - 15
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Getstat - get file status
USAGE
finclude <sgstat.h>
getstat(code,filenum, buffer) /* code 0 */
char *buffer;
getstat(code,filenum) /* codes 1 and 6 */
getstat(code,filenum,size) /* code 2 */
long *size;
getstat (code, filenum, pos) /* code 5 */
long *pos;
ASSEMBLER EQUIVALENT
os9 I$GETSTT
DESCRIPTION
A full description of getstat can be found in the 0S-9 System
Programmer's Manual.
"Code" must be the value of one of the standard codes for the
getstat service request, "filenum" must be the path number of
an open file.
The form of the call depends on the value of "code",
Code 0:
Code 1:
Code 2
Code 5
Code 6
"Buffer" must be the address of a 32 byte
buffer into which the relevant status packet
is copied. The header file has the
definitions of the various file and device
structures for use by the program,
Code 1 only applies to SCF devices and to
test for data available. The return value is
zero if there is data available. -1 is
returned if there is no data.
"Size" should be the address of a long
integer into which the current file size is
placed. The return value of the function is
-1 on error and 0 on success,
"Pos" should be the address of a long integer
into which the current file size is placed,
The return value of the function is -1 on
error and 0 on success,
Returns -1 on EOF and error and 0 on success.
Page 3 - 16
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
NOTE that when one of the previous calls returns -1, the
actual error is returned in errno.
Page 3 - 17
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Getuid - return user id
USAGE
getuid()
ASSEMBLER EQUIVALENT
0s9 F$ID
DESCRIPTION
Getuid returns the real user
maintained in the password file).
Page 3 - 18
id
of
the
current task (as
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Intercept - set function for interrupt processing
USAGE
intercept (func)
int (*func)(); /* i,e. "fune" is a pointer to a function
returning an int */
ASSEMBLER EQUIVALENT
F$ICPT
DESCRIPTION
Intercept instructs 0S-9 to pass control to the function "func"
when an interrupt(signal) is received by the current process.
If the interrupt processing function has an argument, it will
contain the value of the signal received. On return from
"func", the process resumes at the point in the program where
it was interrupted by the signal. "Interrupt()" is an
alternative to the use of "signal ()" to process interrupts.
As an example, suppose we wish to ensure that a partially
completed output file is deleted if an interrupt is received.
The body of the program might include:
char *temp_file = "temp"; /* name of temporary file */
int pn = O; /* path number */
int intrupt(); /* predeclaration */
intercept(intrupt); /* route interrupt processing */
pn = creat(temp_file,3); /* make a new file */
write(pn,string,count) /* write string to temp file */
close(pn);
pn=0;
Page 3 - 19
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
The interrupt routine might be coded:
intrupt (sig);
{
if (pn){ /* only done if pn refers to an open file */
close(pn);
unlink(temp_file); /* delete */
}
exit(sig);
}
CAVEATS
"Intercept()" and "signal()" are mutually incompatible so that
calls to both must not appear in the same program. The linker
guards against this by giving an "entry name clash - _sigint"
error if it is attempted.
SEE ALSO
signal()
Page 3 - 20
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Kill - send an interrupt to a task
USAGE
finclude <signal.h>
kill(tid,interrupt)
DESCRIPTION
Kill sends the interrupt type "interrupt" to the task with id
"tid",
Both tasks, sender and receiver, must have the same user id
unless the user is the super user.
The include file contains definitions of the defined signals as
follows:
/* 0S-9 signals #/
#define SIGKILL O /* system abort (cannot be caught or
ignored)*/
#define SIGWAKE 1 /* wake up */
define SIGQUIT 2 /* keyboard abort #/
define SIGINT 3 /* keyboard interrupt */
Other user-defined signals may, of course, be sent.
DIAGNOSTICS
Kill returns 0 from a successful call and -1 if the task does
not exist, the effective user ids do not match, or the user is
not the system manager.
SEE ALSO
signal() 0S-9 shell command "kill"
Page 3 - 21
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Lseek - position in file
USAGE
long lseek(pn,position, type)
long position;
ASSEMBLER EQUIVALENT
os9 I$SEEK
DESCRIPTION
The read or write pointer for the open file with the path
number, "pn", is positioned by lseek to the specified place in
the file. The "type" indicates from where "position" is to be
measured: if 0, from the beginning of the file, if 1, from the
current location, or if 2, from the end of the file.
Seeking to a location beyond the end of a file open for
writing and then writing to it, creates a "hole" in the file
which appears to be filled with zeros from the previous end to
the position sought,
The returned value is the resulting position in the file unless
there is an error, so to find out the current position use
lseek(pn,01,1);
CAVEATS
The argument "position" MUST be a long integer. Constants
should be explicitly made long by appending an "1", as above,
and other types should be converted using a cast;
e.g. lseek(pn,(long)pos,1);
Notice also, that the return value from lseek is itself a long
integer.
DIAGNOSTICS
-1 is returned if "pn" is a bad path number, or attempting to
seek to a position before the beginning of a file.
SEE ALSO
open(),creat() Standard Library function "fseek"
Page 3 - 22
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Mknod - create a directory
USAGE
finclude <modes.h>
mknod(fname,desc)
char *fname;
ASSEMBLER EQUIVALENT
os9 I$MAKDIR
DESCRIPTION
This call may be used to create a new directory. "Fname"
should point to a string containing the desired name of the
directory. "Desc" is a descriptor specifying the desired mode
(file type) and permissions of the new file.
The include file defines the possible values for "desc" as
follows:
#define S_IREAD 0x01 /* owner read */
define S_IWRITE 0x02 /* owner write */
#define S_IEXEC Ох 04 /* owner execute */
define S_IOREAD 0x08 /* public read */
#define S_IOWRITE 0x10 /* public write #/
define S_IOEXEC 0x20 /% public execute #/
#define S_ISHARE 0x40 /* sharable */
DIAGNOSTICS
Zero is returned if the directory has been successfully made; -
1 if the file already exists.
SEE ALSO
0S-9 command "makdir"
Page 3 - 23
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Modload, Modlink - return a pointer to a module structure
USAGE
#include <module.h>
mod_exec *modlink(modname,type,language)
char *modname;
mod_exec *modload(filename,type,language)
char *filename;
ASSEMBLER EQUIVALENT
os9 F$LINK
osg9 F$LOAD
DESCRIPTION
Each of these calls return a pointer to an 0S-9 memory module.
Modlink will search the module directory for a module with the
same name as "modname" and, if found, increment its link count.
Modload will open the file which has the path list specified by
"filename" and loads modules from the file adding them to the
module directory. The returned value is a pointer to the first
module loaded.
Above, each is shown as returning a pointer to an executable
module, but it will return a pointer to whatever type of module
is found.
DIAGNOSTICS
-1 is returned on error.
SEE ALSO
munlink()
Page 3 - 24
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Munlink - unlink a module
USAGE
#include <module.h>
munlink(mod)
mod exec *mod:
ASSEMBLER EQUIVALENT
os9% F$UNLINK
DESCRIPTION
This call informs the system that the module pointed to by
"mod" is no longer required by the current process. Its link
count is decremented, and the module is removed from the module
directory if the link count reaches zero.
SEE ALSO
modlink(),modload()
Page 3 - 25
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
_089 - system call interface from C programs
USAGE
finclude <os9.h>
_os9(code,reg)
char code;
struct registers #reg;
DESCRIPTION
.0s9 enables a programmer to access virtually any 0S-9 system
call directly from a C program without having to resort to
assembly language routines.
Code is one of the codes that are defined in os9.h. os9.h
contains codes for the F$ and I$ function/service requests, and
it also contains getstt, setstt, and error codes.
The input registers(reg) for the system calls are accessed by
the following structure that is defined in o0s9.h:
struct registers {
char rg cc,rg_a,rg b,rg dup;
unsigned re_x,rg y, rg us
} 3
An example program that uses _os9% is presented on the following
page.
DIAGNOSTICS
-1 is returned if the 05-9 call failed. 0 is returned on
success.
Page 3 - 26
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Program example:
#include <0s9.h>
#include <modes.h>
/* this program does an I$GETSTT call to get file size */
main(arge,argv)
int arge;
char ** агру;
{
struct registers reg;
int path;
/% tell linker we need longs */
pflinit();
/* low level open(file name is first command line param */
path=open(*++argv,S_IREAD);
/* set up regs for call to 0S-9 */
reg.rg_a=path;
reg.rg_b=SS_SIZE;
if(_os9(I GETSTT,éreg) == 0)
printf ("filesize = $1xWUn", /* success */
(long) (reg.rg x << 16)+reg.rg_u);
else printf("0S9 error #%d\n",reg.rg b € Oxff); /*failed*/
dumpregs(&reg); /* take a look at the registers */
}
dumpregs(r)
register struct registers tr;
{
printf("cec=%02x\n",r->rg cc € Oxff);
printf (" a=4%02xW",r->rg_a € Oxff);
printf(" b=$02xwW",r->rg_b € Oxff);
printf("dp=#02x\n",r->rg_ dp & Oxff);
printf(" x=%04x\n",r->rg x);
printf(" y=%04x\n",r->rg_y);
printf("™ u=%04x\n",r->rg u);
}
Page 3 - 27
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Open -~ open a file for read/write access
USAGE
open{( fname, mode)
char *fname;
ASSEMBLER EQUIVALENT
0s9 I$SOPEN
DESCRIPTION
This call opens an existing file for reading if "mode" is 1,
writing if "mode" is 2, or reading and writing if "mode" is 3.
NOTE that these values are 0S-9 specific and not compatible
with other systems. "Fname" should point to a string
representing the pathname of the file.
Open returns an integer as "path number" which should be used
by i/0 system calls referring to the file.
The position where reads or writes start is at the beginning of
the file.
DIAGNOSTICS
-1 is returned if the file does not exist, if the pathname
cannot be searched, if too many files are already open, or if
the file permissions deny the requested mode.
SEE ALSO
Creat(),read(),write(),dup(),close()
Page 3 - 28
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Os9fork - create a process
USAGE
os9fork(modname,paramsize,paramptr,type,lang,datasize)
char *modname, *paramptr;
ASSEMBLER EQUIVALENT
0s9 F$FORK
DESCRIPTION
The action of F$FORK is described fully in the 0S-9 System
Programmer's Manual, Os9fork will create a process that will
run concurrently with the calling process. When the forked
process terminates, it will return to the calling process.
"Modname" should point to the name of the desired module.
"Paramsize" is the length of the parameter string which should
normally be terminated with a '\n', and "paramptr" points to
the parameter string. "Type" is the module type as found in
the header (normally 1: program), and "lang" should match the
language nibble in the module header( C programs have 1 for
6809 machine code here). "Datasize" may be zero, or it may
contain the number of 256 byte pages to give to the new process
as initial allocation of memory.
DIAGNOSTICS
-1 will be returned on error, or the ID number of the child
process will be returned on success.
Page 3 - 29
MICROWARE C COMPILER USER'S GUIDE
C SISTEM CALLS
Pause - halt and wait for interrupt
USAGE
pause ( )
ASSEMBLER EQUIVALENT
0s9 I$SLEEP with a value of O
DESCRIPTION
Pause may be used to halt a task until an interrupt is received
from "kill",
Pause always returns -1.
SEE ALSO
kill(),signal() 0S-9 shell command "kill"
Page 3 - 30
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Prerr - print error message
USAGE
prerr(filnum,errcode)
ASSEMBLER EQUIVALENT
0s9 F$PERR
DESCRIPTION
PRERR prints an error message on the output path as specified
by "filnum" which must be the path number of an open file. The
message depends on "errcode" which will normally be a standard
05-9 error code.
Page 3 - 31
MICROWARE C COMPILER USER'S GUIDE
C SISTEM CALLS
Read, Readln - read from a file
USAGE
read(pn,buffer,count )
char *buffer;
readln(pn,buffer, count)
char *buffer;
ASSEMBLER EQUIVALENT
os9 I$READ
0s9 I$READLN
DESCRIPTION
The path number, "pn", is an integer which is one of the
standard path numbers 0, 1, or 2, or the path number should
have been returned by a successful call to "open", "creat", or
"dup". "Buffer" is a pointer to space with at least "count"
bytes of memory into which read will put the data from the
file.
It is guaranteed that at most "count" bytes will be read, but
often less will be, either because, for readln, the file
represents a terminal and input stops at the end of a line, or
for both, end-of-file has been reached.
Readin causes "line-editing" such as echoing to take place and
returns once the first "\n" is encountered in the input or the
number of bytes requested has been read. Readln is the
preferred call for reading from the user's terminal.
Read does not cause any such editing. See the 0S-9 manual for
a fuller description of the actions of these calls,
DIAGNOSTICS
Read and readln return the number of bytes actually read (0 at
end-of-file) or -1 for physical i/o errors, a bad path number,
or a ridiculous "count".
NOTE that end-of-file is not considered an error, and no error
indication is returned. Zero is returned on ECF.
SEE ALSO
open(),creat(),dup()
Page 3 - 32
USAGE
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Sbrk,Ibrk - request additional working memory
char *sbrk( increase)
char *ibrk(increase)
DESCRIPTION
Sbrk requests an allocation from free memory and returns a
pointer to its base.
"Sbrk()" requests the system to allocate "new" memory from
outside the initial allocation.
Users should read the Memory Management section of this manual
for a fuller explanation of the arrangement.
Ibrk requests memory from inside the initial memory allocation.
DIAGNOSTICS
Sbrk and ibrk return -1 if the requested amount of contiguous
memory is unavailable,
Page 3 - 33
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Setpr - set process priority
USAGE
setpr(pid,priority)
ASSEMBLER EQUIVALENT
os9 F$SPRIOR
DESCRIPTION
SETPR sets the process identified by "pid"( process id) to have
a priority of "priority", The lowest priority is 0 and the
highest is 255.
DIAGNOSTICS
The call will return -1 if the process does not have the same
user id as the caller.
Page 3 - 34
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Setime,Getime - Set and get system time
USAGE
finclude <time.h>
setime(byffer)
getime(buffer)
struct sgtbuf *buffer /* defined in time, h */
ASSEMBLER EQUIVALENT
os9 F$STIME
os9 G$GTIME
DESCRIPTION
GETIME returns system time in buffer.
SETIME sets system time from buffer,
Page 3 - 35
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Setuid - set user id
USAGE
setuid(uid)
ASSEMBLER EQUIVALENT
0S9 F$SUSER
DESCRIPTION
This call may be used to set the user id for the current task.
Setuid only works if the caller is the super user(user id 0).
DIAGNOSTICS
Zero 1s returned from a successful call, and -1 is returned on
error.
SEE ALSO
getuid()
Page 3 - 36
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Setstat - set file status
USAGE
#include <sgstat.h>
setstat(code,filenum, buffer) /* code 0 */
char *buffer;
setstat(code,filenum,size) /* code 2 */
long size;
ASSEMBLER EQUIVALENT
os9% F$SETSTT
DESCRIPTION
For a detailed explanation of this call, see the 05-9 System
Programmer's Manual.
"Filenum"™ must be the path number of a currently open file.
The only values for code at this time are 0 and 2. When "code"
is 0, "buffer" should be the address of a 32 byte structure
which is written to the option section of the path descriptor
of the file. The header file contains definitions of various
structures maintained by 08-9 for use by the programmer. When
code is 2, "size" should be a long integer specifying the new
file size.
Page 3 - 37
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Signal - catch or ignore interrupts
USAGE
finclude <signal.h>
(*signal(interrupt,address ))()
(address )( ) ;
(Which means:"signal" returns a pointer to a function,
"address" is a pointer to a function.)
DESCRIPTION
This call is a comprehensive method of catching or ignoring
signals sent to the current process. Notice that "kill()" does
the sending of signals, and "signal()" does the catching.
Normally, a signal sent to a process causes it to terminate
with the status of the signal. If, in advance of the
anticipated signal, this system call is used, the program has
the choice of ignoring the signal or designating a function to
be executed when it is received. Different functions may be
designated for different signals.
The values for "address" have the following meanings:
0 = reset to the default i.e. abort when received
1 = ignore; this will apply until reset to another
value
Otherwise: taken to be the address of a C function which
is to be executed on receipt of the signal.
If the latter case is chosen, when the signal is received by
the process the "address" is reset to 0, the default, before
the function is executed. This means that if the next signal
received should be caught then another call to "signal()"
should be made immediately. This is normally the first action
taken by the "interrupt" function. The function may access the
signal number which caused its execution by looking at its
argument. On completion of this function the program resumes
at the point at which it was "interrupted" by the signal.
An example should help to clarify all this. Suppose a program
needs to create a temporary file which should be deleted before
exiting. The body of the program might contain fragments like
this:
pn = creat("temp",3); /* create a temporary file */
signal(2,intrupt); /* ensure tidying up * /
signal(3,intrupt);
write(pn,string,count); /* write to temporary file */
Page 3 - 38
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
close(pn); /* finished writing */
unlink("temp"); /* delete it #/
exit(0); /* normal exit */
The call to "signal()" will ensure that if a keyboard or quit
signal is received then the function "intrupt()" will be
executed and this might be written:
intrupt(sig)
{
close(pn); /* close it if open #/
unlink("temp"); /* delete it #/
exit(sig); /* received signal as exit
status*/
}
In this case, as the function will be exiting before another
signal is received, it is unnecessary to call "signal()" again
to reset its pointer. Note that either the function
"intrupt()" should appear in the source code before the call to
"signal()", or it should be pre-declared.
The signals used by 0S5-9 are defined in the header file аз
follows:
/* 05-9 signals #/
#define SIGKILL O /* system abort (cannot be caught or
ignored)*/
define SIGWAKE 1 /* wake up */
#define SIGQUIT 2 /* keyboard abort #/
#define SIGINT 3 /* keyboard interrupt */
/* special addresses #/
#define SIG_DFL O /* reset to default */
¿define SIG_IGN 1 /* ignore */
Please note that there is another method of trapping signals,
namely "intercept()" (qg.v.). However, since "signal()" and
"intercept()" are mutually incompatible, calls to both of them
must not appear in the same program. The Jlink-loader will
prevent the creation of an executable program in which both are
called by aborting with an "entry name clash" error for
"_sigint",
SEE ALSO
intercept() 0S-9 shell command "kill" kill()
Page 3 - 39
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Stacksize, Freemem - obtain stack reservation size
USAGE
stacksize()
freemem()
DESCRIPTION
For a description of the meaning and use of this
call, the user
is referred to the Memory Management section of this manual.
If the stack check code is in effect, a call to
return the maximum number of bytes of stack used
the call. This call can be used to determine
required by a program,
Freemem() will return the number of bytes of the
not been used.
SEE ALSO
stacksize will
at the time of
the stack size
stack that has
ibrk(),sbrk(),freemem() Global variable "memend" and value
end",
Page 3 - 40
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Strass - byte by byte copy
USAGE
_Strass(s1,s2,count)
char #s1,#s2;
DESCRIPTION
Until such time as the compiler can deal with structure
assignment, this function is useful for copying one structure
to another.
"Count" bytes are copied from memory location at "s2" to memory
at "s1" regardless of the contents.
Page 3 - 41
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Tsleep - put process to sleep
USAGE
tsleep(ticks)
ASSEMBLER EQUIVALENT
089 F$SLEEP
DESCRIPTION
Tsleep deactivates the calling process for a specified number
of system "ticks" or indefinitely if "ticks" is zero. A tick
is system dependent but is usually 100ms.
For a fuller description of this call, see the 05-9 System
Programmer's Manual.
Page 3 - 42
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Unlink - remove directory entry
USAGE
unlink( fname)
ASSEMBLER EQUIVALENT
os9% I$DELETE
DESCRIPTION
Unlink deletes the directory entry whose name is pointed to by
"fname", If the entry was the last link to the file, the file
itself is deleted and the disc space occupied made available
for re-use. If, however, the file is open, in any active task,
the deletion of the actual file is delayed until the file is
closed.
ERRORS
Zero is returned from a successful call, -1 if the file does
not exist, if its directory is write-protected, or cannot be
searched, if the file is a non-empty directory or a device.
SEE ALSO
0S-9 command "kill" link()
Page 3 - 43
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Walt - walt for task termination
USAGE
wait(status) int *status;
wait(0)
ASSEMBLER EQUIVALENT
os9 F$WAIT
DESCRIPTION
Wait is used to halt the current task until a child task has
terminated.
The call returns the task id of the terminating task and places
the status of that task in the integer pointed to by "status"
unless "status" is 0. A wait must be executed for each child
task spawned.
The status will contain the argument of the "exit" or " exit"
call in the child task or the signal number if it was
interrupted. A normally terminating C program with no call to
"exit" or "_ exit" has an implied call of "exit(0)",
CAVEATS
NOTE that the status is the 08-9 status code and is not
compatible with codes on other systems.
DIAGNOSTICS
-1 is returned if there is no child to be waited for.
SEE ALSO
fork(),signal(),exit(), exit()
Page 3 - 44
MICROWARE C COMPILER USER'S GUIDE
C SYSTEM CALLS
Write,Writeln - write to a file or device
USAGE
write(pn,buffer,count) char *buffer;
writeln(pn,buffer,count) char *buffer:
ASSEMBLER EQUIVALENT
089 I$WRITE
0s9 I$WRITLN
DESCRIPTION
"Pn" must be a value returned by "open", "creat" or "dup" or
should be a O(stdin), 1(stdout), or 2(stderr).
"Buffer" should point to an area of memory from which "count"
bytes are to be written. Write returns the actual number of
bytes written, and if this is different from "count", an
error has occurred.
Writes in multiples of 256 bytes to file offset boundaries of
256 bytes are the most efficient.
Write causes no "line-editing" to occur on output. Writeln
causes line-editing and only writes up to the first "wn" in the
buffer if this is found before "count" is exhausted. For a
full description of the actions of these calls the, reader is
referred to the 05-9 documentation.
DIAGNOSTICS
-1 is returned if "pn" is a bad path number, if "count" is
ridiculous or on physical i/0 error.
SEE ALSO
creat(),open()
Page 3 - 45
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
INTRODUCTION TO THE C STANDARD LIBRARY
The Standard Library contains functions which fall into two
classes: high level I/0 and convenience.
The high level 1/0 functions provide facilities that are
normally considered part of the definition of other languages; for
example, the FORMAT "statement" of Fortran. In addition, automatic
buffering of I/0 channels improves the speed of file access because
fewer system calls are necessary.
The high level 1/0 functions should not be confused with the
low level system calls with similar names. Nor should "file
pointers" be confused with "path numbers". The standard library
functions maintain a structure for each file open that holds status
information and a pointer into the files buffer. A user program
uses a pointer to this structure as the "identity" of the file
(which is provided by "fopen()"), and passes it to the various
I/0 functions. The I/0 functions will make the low level system
calls when necessary.
USING A FILE POINTER IN A SYSTEM CALL, OR A PATH NUMBER IN A
STANDARD LIBRARY CALL, is a common mistake among beginners to C and,
if made, will be sure to CRASH YOUR PROGRAM.
The convenience functions include facilities for copying,
comparing, and concatenating strings, converting numbers to strings,
and doing the extra work in accessing system information such as the
time.
In the pages which follow, the functions available are
described in terms of what they do and the parameters they expect.
The "USAGE" section shows the name of the function and the type
returned (if not int). The declaration of arguments are shown as
they would be written in the function definition to indicate the
types expected by the function. If it is necessary to include a
file before the function can be used, it is shown in the "USAGE"
section by "#include <filename>".
Most of the header files that are required to be included, must
reside in the "DEFS" directory on the default system drive. If the
file is included in the source program using angle bracket
delimiters instead of the usual double quotes, the compiler will
append this path name to the file name. For example, "finclude
<stdio.h>" is equivalent to "#include /d0/defs/stdio.h", if "/d0" is
the path name of the default system drive.
PLEASE NOTE that if the type of the value returned by a
function is not INT, you should make a predeclaration in your
program before calling it. For example, if you wish to use
"atof()", you should predeclare by having "double atof();" somewhere
in your program before a call to it. Some functions which have
associated header files in the DEFS directory that should be
Page 4 - 1
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
included, will be pre-declared for you in the header. An example of
this is "ftell()" which is predeclared in "stdio.h", If you are in
any doubt, read the header file.
Page 4 - 2
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Atof,Atoi,Atol - ASCII to number conversions
USAGE
double atof(ptr)
char *ptr;
long atol(ptr)
char *ptr;
int atoi(ptr)
char *ptr;
DESCRIPTION
Conversions of the string pointed to by "ptr" to the relevant
number type are carried out by these functions. They cease to
convert a number when the first unrecognized character is
encountered.
Each skips leading spaces and tab characters. Atof()
recognizes an optional sign followed by a digit string that
could possibly contain a decimal point, then an optional "e"
or "E", an optional sign and a digit string. Atol() and atoi()
recognize an optional sign and a digit string.
CAVEATS
Overflow causes unpredictable results. There are no error
indications.
Page 4 - 3
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Fflush,Fclose - flush or close a file
USAGE
#include <stdio.h>
fflush(fp)
FILE #fp;
fclose(fp)
FILE #fp;
DESCRIPTION
Fflush causes a buffer associated with the file pointer "fp"
to be cleared by writing out to the file; of course, only if
the file was opened for write or update. It is not normally
necessary to call fflush, but it can be useful when, for
example, normal output is to "stdout", and it is wished to
send something to "stderr" which 1s unbuffered. If fflush
were not used and "stdout" referred to the terminal, the
"stderr" message will appear before large chunks of the
"stdout" message even though the latter was written first.
Fclose calls fflush to clear out the buffer associated with
"fp", closes the file, and frees the buffer for use by another
fopen call.
The exit() system call and normal termination of a program
causes fclose to be called for each open file,
SEE ALSO
System call close(), fopen(), setbuf().
DIAGNOSTICS
EOF is returned if "fp" does not refer to an output file or
there is an error on writing to the file.
Page 4 - 4
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Feof ,Ferror,Clearerr,Fileno - return status information of files
USAGE
finclude <stdio.h>
feof(fp)
FILE *fp;
ferror(fp)
FILE #fp;
clearerr(fp)
FILE *fp;
fileno(fp)
FILE *fp;
DESCRIPTION
Feof returns non-zero if the file associated with "fp" has
reached its end. Zero is returned on error.
Ferror returns non-zero if an error condition occurs on access
to the file "Гр"; zero is returned otherwise. The error
condition persists, preventing further access to the file by
other “Standard Library functions, until the file is closed,
or it is cleared by clearerr,
Clearerr resets the error condition on the file "fp", This
does NOT "fix" the file or prevent the error from occurring
again; it merely allows Standard Library functions at least to
try.
CAVEATS
These functions are actually macros that are defined in
"{stdio.h>"™ so their names cannot be redeclared.
SEE ALSO
System call open(), fopen().
Page 4 - 5
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Findstr,Findnstr - string search
USAGE
findstr(pos,string,pattern)
char *string,*pattern;
findnstr(pos,string,pattern,size)
char *string,*pattern;
DESCRIPTION
These functions search the string pointed to by "string" for
the first instance of the pattern pointed to by "pattern"
starting at position "pos" (where the first position is 1 not
0). The returned value is the position of the first matched
character of the pattern in the string or zero if a match is
not found.
Findstr stops searching the string when a null byte is found in
"string",
Findnstr only stops searching at position "pos" + "len" so it
may continue past null bytes.
CAVEATS
The current implementation does not use the most efficient
algorithm for pattern matching so that use on very long strings
is likely to be somewhat slower than it might be.
SEE ALSO
index(),rindex.
Page 1 - 6
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Fopen - open a file and return a file pointer
USAGE
finclude <stdio.h>
FILE *fopen( filename,action)
char *filename, *action;
FILE *freopen(filename,action,streak)
char *filename, *action;
FILE *stream;
FILE *fdopen(filedes,action)
int filedes;
char *action;
DESCRIPTION
Fopen returns a pointer to a file structure (file pointer) if
the file named in the string pointed to by "filename" can be
validly opened with the action in the string pointed to by
"action".
The valid actions are:
при open for reading
"y create for writing
"an append(write) at end of file, or create for
writing
Try open for update
Tw" create for update
na+" create or open for update at end of file
na" directory read
Any action may have an "x" after the initial letter which
indicates to "fopen()" that it should look in the current
execution directory if a full path name is not given, and
the x also specifies that the file should have execute
permission.
E.g. f = fopen("fred","wxT):
Opening for write will perform a "creat()", If a file with the
same name exists when the file is opened for write, it will be
truncated to zero length. Append means open for write and
position to the end of the file. Writes to the file via
"putc()" ete. will extend the file. Only if the file does not
already exist will it be created,
Page 4 - 7
MICROWARE C COMPILER USER'S GUIDE
C STARDARD LIBRARY
NOTE that the type of a file structure is pre-defined in
"stdio.h™ as FILE, so that a user program may declare or define
a file pointer by, for example, FILE *f;
Three file pointers are available and can be considered open
the moment the program runs:
stdin the standard input - equivalent to path number
stdout the standard output - equivalent to path number
stderr standard error output- equivalent to path number 2
-+ O
All files are automatically buffered except stderr, unless a
file is made unbuffered by a call to setbuf() (q.v.).
Freopen is usually used to attach stdin, stdout, and stderr to
specified files. Freopen substitutes the file passed to it
instead of the open stream. The original stream is closed.
NOTE that the original stream will be closed even if the open
does not succeed,
Fdopen associates a stream with a file descriptor. The streams
type(r,w,a) must be the same as the mode of the open file,
CAVEATS
The "action" passed as an argument to fopen must be a pointer
to a string, NOT a character. For example
Гр = fopen("fred","r"); is correct but
fp = fopen("fred",'r'); is not.
DIAGNOSTICS
Fopen returns NULL (0) if the call was unsuccessful.
SEE ALSO
System call open( ) Fclose()
Page 4 - 8
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Fread,Fwrite - read/write binary data
USAGE
#include <stdio.h>
fread(ptr, size, number, fp)
FILE *fp;
fwrite(ptr, size, number, fp)
FILE *fp;
DESCRIPTION
Fread reads from the file pointed to by "fp". "Number" is the
number of items of size "size" that are to be read starting at
"ptr", The best way to pass the argument "size" to fread is by
using "sizeof", Fread returns the number of items actually
read.
Fwrite writes to the file pointed to by "fp". "Number" is the
number of items of size "size! reading them from memory
starting at "ptr".
DIAGNOSTICS
Both functions return O(NULI) at end of file or error.
SEE ALSO
System calls read(),write(). Fopen(),getc(),pute(),printf().
Page 4 - 9
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Fseek,Rewind,Ftell - position in a file or report current position
USAGE
#include <stdio.h>
fseek(fp, offset, place)
FILE *fp;
long offset;
rewind(fp)
FILE #fp;
long ftell(fp)
FILE *fp;
DESCRIPTION
Fseek repositions the next character position of a file for
either read or write. The new position is at "offset" bytes
from the beginning of the file if "place" is 0, the current
position if 1, or the end if 2. Fseek sorts out the special
problems of buffering.
NOTE that using "lseek()" on a buffered file will produce
unpredictable results.
Rewind is equivalent to "fseek(fp,01,0)".
Ftell returns the current position, measured in bytes, from the
beginning of the file pointed to by "fp",
DIAGNOSTICS
Fseek returns -1 if the call is invalid.
SEE ALSO
System call lseek().
Page 4 - 10
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Getc,Getchar - return next character to be read from a file
USAGE
finclude <stdio.h>
int getc(fp)
FILE *fp;
int getchar()
int getw(fp)
FILE *fp;
DESCRIPTION
Getc returns the next character from the file pointed to by
"fp",
Getchar is equivalent to "geto(stdin)".
Getw returns the next two bytes from the file as an integer.
Under 0S-9 there is a choice of service requests to use when
reading from a file, "Read()"™ will get characters up to a
specified number in "гам" mode i.e. no editing will take
place on the input stream and the characters will appear to the
program exactly as in the file. "Readin()", on the other
hand, will honor the various mappings of characters
associated with a Serial Character device such as a terminal
and in any case will return to the caller as soon as a carriage
return is seen on the input.
In the vast majority of cases, it is preferable to use
"readln()" for accessing Serial Character devices and "read()"
for any other file input. "Getc()" uses this strategy and, as
all file input using the Standard Library functions is routed
through "getc()", so do all the other input functions. The
choice is made when the first call to "getc()" is made after
the file has been opened. The system is consulted for the
status of the file and a flag bit is set in the file structure
accordingly. The choice may be forced by the programmer by
setting the relevant bit before a call to "getc()". The flag
bits are defined in "<stdio.h>" as " SCF" and "_RBF" and the
method is as follows: assuming that the file pointer for the
file, as returned by "fopen()" is f,
f-> flag |= _SCF;
will force the use of "readln()" on input and
f-> flag != _RBF;
Page 4 - 11
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
will force the use of "read()". This trick may be played on
the standard streams "stdin", "stdout" and "stderr" without the
need for calling "fopen()" but before any input is requested
from the stream.
DIAGNOSTICS
EOF(-1) is returned for end of file or error.
SEE ALSO
Putc(),fread(),fopen(),gets() , ungetc().
Page 4 - 12
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Gets, Fgets - input a string
USAGE
finclude <stdio.h>
char *gets(s)
char ts;
char *fgets(s,n,fp)
char *s:
FILE *fp;
DESCRIPTION
Fgets reads characters from the file "fp" and places them in
the buffer pointed to by "s" up to a carriage return('\n') but
not more than "n" - 1 characters. A null character is appended
to the end of the string.
Gets is similar to fgets, but gets is applied to "stdin" and no
maximum is stipulated and the '\n' is replaced by a null.
Both functions return their first arguments.
CAVEATS
The different treatment of the "п" by these functions is
retained here for portability reasons.
DIAGNOSTICS
Both functions return NULL on end-of-file or error,
SEE ALSO
Puts(),getc(),scanf(),fread().
Page 4 - 13
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Isalpha,Isupper,Islower,Isdigit,Isalnum,Isspace,Ispunct,Isprint,
Iscntrl,Isascii - character classification
USAGE
include <ctype.h>
isalpha(e)
etc.
DESCRIPTION
These functions use table look-up to classify characters
according to their ascii value. The header file defines them
as macros which means that they are implemented as fast, in-
line code rather than subroutines.
Each results in non-zero for true or zero for false.
The correct value is guaranteed for all integer values in
isascii, but the result is unpredictable in the others if the
argument is outside the range -1 to 127.
The truth tested by each function is as follows:
isalpha ec is a letter
isdigit ec is a digit
isupper c is an upper case letter
islower ¢ is a lower case letter
isalnum ec is a letter or a digit
isspace e is a space, tab character, newline, carriage
return or formfeed
isentrl e is a control character (0 to 32) or DEL (127)
ispunct ec is neither control nor alpha-numeric
isprint е 15 printable (32 to 126)
isascii c is in the range -1 to 127
Page 4 - 14
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
L3tol,Ltol3 ~ convert between long integers and 3-byte integers
USAGE
13tol(lp,cp,n)
long *1p;
char “cp;
1lto13(cp,lp,n)
long *1p;
char “cp;
DESCRIPTION
Certain system values, such as disc addresses, are maintained
in three-byte form rather than four-byte; these functions
enable arithmetic to be used on them.
L3tol converts a vector of "n" three-byte integers pointed to
by "cp", into a vector of long integers starting at "lp".
Ltol3 does the opposite.
Page 4 - 15
USAGE
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Longimp, Set ijmp - jump to another function
include <setimp.h>
setimp(env)
jmp_buf env;
longjmp(env,val)
jmp_buf env;
DESCRIPTION
These functions allow the return of program control directly to
a higher level function. They are most useful when dealing
with errors and interrupts encountered in a low level routine,
"Coto" in C has scope only in the function in which it 18
used; i.e. the label which is the object of a "goto" may only
be in the same function. Control can only be transferred
elsewhere by means of the function call, which, of course,
returns to the caller, In certain abnormal situations a
programmer would prefer to be able to start some section of
code again, but this would mean returning up a ladder of
function calls with error indications all the way.
Setjmp is used to "mark" a point in the program where a
subsequent longjmp can reach. It places in the buffer, defined
in the header file, enough information for longjmp to restore
the environment to that existing at the relevant call to
set jmp.
Longjmp is called with the environment buffer as an argument
and also, a value which can be used by the caller of setjmp as,
perhaps, an error status.
To set the system up, a function will call setimp to set up the
buffer, and if the returned value is zero, the program will
know that the call was the "first time through", If, however,
the returned value is non-zero, it must be a longjmp returning
from some deeper level of the program.
NOTE that the function calling set jmp must NOT HAVE RETURNED
at the time of calling longjmp, and the environment buffer must
be declared GLOBALLY.
Page 4 - 16
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Malloc,Free,Calloc - memory allocation
USAGE
char *malloc(size)
unsigned size;
free(ptr)
char *ptr;
char *calloc(nel,elsize)
unsigned nel,elsize;
DESCRIPTION
Malloc returns a pointer to a block of at least "size" free
bytes.
Free requires a pointer to a block that has been allocated by
malloc; it frees the space to be allocated again.
Calloc allocates space for an array. Nel is the number of
elements in the array, and elsize is the size of each element.
Calloc initializes the space to zero.
DIAGNOSTICS
Malloc, free, and calloc return NULL(0) if no free memory can
be found or if there was an error.
Page 4 - 17
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Mktemp - create unique temporary file name
USAGE
char *mktemp(name)
char *name;
DESCRIPTION
Mktemp may be used to ensure that the name of a temporary file
is unique in the system and does not clash with any other file
name.
"Name" must point to a string whose last five characters are
TXT: the Xs will be replaced with the ascii representation of
the task id.
For example, if "name" points to "foo.XXXXX", and the task id
is 351, the returned value points at the same place, but it now
holds "foo.351",
SEE ALSO
System call "getpid()",
Page 4 - 18
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Printf,Fprintf,Sprintf - formatted output
#include <stdio.h>
printf(control [,arg0[,argl..]1])
char *control;
fprintf(fp, control [,arg0[,arg1..]])
FILE #fp;
char *control;
sprintf(string, control [,arg0[,argl..]1])
string [];
char *control;
DESCRIPTION
These three functions are used to place numbers and strings on
the output in formatted, human readable form,
Fprintf places its output on the file "fp", printf on the
standard output, and sprintf in the buffer pointed to by
"string". NOTE that it is the user's responsibility to ensure
that this buffer is large enough.
The "control" string determines the format, type, and number
of the following arguments expected by the function. If the
control does not match the arguments correctly, the results
are unpredictable.
The control may contain characters to be copied directly to
the output and/or format specifications. Each format
specification causes the function to take the next successive
argument for output.
A format specification consists of a "$" character followed by
(in this order)
An optional minus sign ("=") that means left justification
in the field.
An optional string of digits indicating the field width
required. The field will be at least this wide and may be
wider if the conversion requires it. The field will be
padded on the left unless the above minus sign is present,
in which case it will be padded on the right. The padding
character is, by default, a space, but if the digit string
starts with a zero ("0"), it will be "0".
Page 4 - 19
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
An optional dot (".") and a digit string, the precision,
which for floating point arguments indicates the number
of digits to follow the decimal point on conversion, and
for strings, the maximum number of characters from the
string argument are to be printed.
An optional character "1" indicates that the following
"а", "х", or "o" is the specification of a long integer
argument. NOTE _that _in _order for the printing of long
integers _to _take _place, the source code must have in it
somewhere _the _statement pflinit which causes routines
to be linked from the library.
A conversion character which shows the type of the
argument and the desired conversion. The recognized
conversion characters are:
d,o,x,X The argument is an integer and the
conversion is to decimal, octal, or
hexadecimal, respectively. "X" prints hex
and alpha in upper case,
u The argument is an integer and the
conversion is to an unsigned decimal in
the range 0 to 65535.
f The argument is a double, and the form of
the conversion is "[-]nnn.nnn". Where the
digits after the decimal point are
specified as above. If not specified, the
precision defaults to six digits. If the
precision is 0, no decimal point or
following digits are printed.
e,E The argument is a double and the form of
the conversion is "[-]n.nnne(+or-)nn"; one
digit before the decimal point, and the
precision controls the number following.
"E" prints the "e" in upper case.
Е, С The argument is a double, and either the
nf” format or the "e" format is chosen,
whichever is the shortest, If the "С"
format is used, the "e" is printed in
upper case,
NOTE in each of the above double conversions, the last digit is
rounded.
ALSO NOTE that in order for the printing of floats or doubles
to take place, _the _source _program _MUST have the statement
ffinit somewhere.
Page 4 - 20
SEE ALSO
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
The argument is a character.
The argument is a pointer to a string.
Characters from the string are printed up
to a null character, or until the number of
characters indicated by the precision have
been printed. If the precision is 0 or
missing, the characters are not counted.
No argument corresponding; "$" is printed.
Kernighan € Ritchie pages 145-147, Putc(),scanf().
Page 4 - 21
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Pute,Putchar,Putw - put character or word in a file
USAGE
include <stdio.h>
char pute(ch,fp)
char ch;
FILE ¥*fp;
char putchar(ch)
char *ch;
putw(n, fp)
FILE #fp;
DESCRIPTION
Pute adds the character "ch" to the file "fp" at the current
writing position and advances the position pointer,
Putchar is implemented as a macro (defined in the header file)
and is equivalent to "putce(ch,stdout)".
Putw adds the (two byte) machine word "n" to the file "fp" in
the manner of putc.
Output via putce is normally buffered except
(a) when the buffering is disabled by "setbuf()", and
(b) the standard error output is always unbuffered.
DIAGNOSTICS
Putc and putchar return the character argument from a
successful call, and EOF on end-of-file or error.
SEE ALSO
Fopen(),fclose(),fflush(),getc(),puts(),printf(),fread().
Page 4 - 22
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Puts,Fputs - put a string on a file
USAGE
#include <stdio.h>
puts(s)
char *s;
fputs(s,fp)
char #s;
FILE *fp;
DESCRIPTION
Fputs copies the
onto the file "fp",
Puts copies the
appends m"\n",
(null-terminated)
string "s" onto the
string pointed to by
standard output
The terminating null is not copied by either function,
CAVEATS
The inconsistency
not by fputs is
compatibility.
of the new-line being appended by puts
dictated by
Page 4 - 23
history
and
the
desire
Mgt
and
and
for
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Qsort - quick sort
USAGE
qsort(base,n,size, compfunc)
char *base;
int (%*compfunc)(); /* which means: a pointer to a function
returning an int */
DESCRIPTION
Qsort implements the quick-sort algorithm for sorting an
arbitrary array of items.
"Base" is the address of the array of "n" items of size "size",
"Compfune" is a pointer to a comparison routine supplied by
the user. It will be called by gsort with two pointers to
items in the array for comparison and should return an integer
which is less than, equal to, or greater than 0 where,
respectively, the first item is less than, equal to, or greater
than the second.
Page 4 - 24
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Scanf,Fscanf,Sscanf - input string interpretation
#include <stdio.h>
fscanf(fp,control,[,pointer...])
FILE *fp;
char *control;
scanf (control[,pointer...))
char *control;
sscanf(string,control[,pointer...])
char *string,*control;
DESCRIPTION
These functions perform the complement to "printf()" etc.
Fscanf performs conversions from the file "fp", scanf from the
standard input, and sscanf from the string pointed to by
"string",
Each function expects a control string containing conversion
specifications, and zero or more pointers to objects into which
the converted values are stored.
The control string may contain three types of fields:
(a) Spaces, tab characters, or "un" which match any of
the three in the input.
(b) Characters not among the above and not "$" which must
match characters in the input.
(e) A "gn followed by an optional "*" indicates
suppression of assignment, an optional field width
maximum and a conversion character indicating the
type expected.
A conversion character controls the conversion to be applied
to the next field and indicates the type of the corresponding
pointer argument. A field consists of consecutive non-space
characters and ends at either a character inappropriate for the
conversion or when a specified field width is exhausted.
When one field is finished, white-space characters are passed
over until the next field is found.
The following conversion characters are recognized
d A decimal string is to be converted to an integer.
o An octal string; the corresponding argument should
point to an integer,
X A hexadecimal string for conversion to an integer.
5 А string of non-space characters is expected and
will be copied to the buffer pointed to by the
Page 4 - 25
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
corresponding argument and a null ("\Q") appended.
The user must ensure that the buffer is large
enough. The input string is considered terminated
by a space, tab or ("wn").
с A character is expected and is copied into the byte
pointed to by the argument. The white-space
skipping is suppressed for this conversion. If a
field width is given, the argument is assumed to
point to a character array and the number of
characters indicated is copied to it. NOTE to ensure
that the next non-white-space character is read use
"218" and that TWO bytes are pointed to by the
argument.
e,f A floating point representation is expected on the
input and the argument must be a pointer to a float.
Any of the usual ways of writing floating point
numbers are recognized.
[ This denotes the start of a set of match characters;
the inclusion or exclusion of which delimits the
input field. The white-space skipping is
suppressed. The corresponding argument should be a
pointer to a character array. If the first
character in the match string is not ”"°",
characters are copied from the input as long as they
can be found in the match string, if the first
character is the copying continues while characters
cannot be found in the match string. The match
string is delimited by a "]",
D,O,X Similar to d,o,x above, but the corresponding
argument is considered to point to a long integer.
E,F Similar to e,f above, but the corresponding argument
should point to a double.
q A match for "$" is sought; no conversion takes
place.
Each of these functions returns a count of the number of
fields successfully matched and assigned.
CAVEATS
The returned count of matches/assignments does not include
character matches and assignments suppressed by "*", The
arguments must ALL be pointers. It is a common error to call
scanf with the value of an item rather than a pointer to it.
DIAGNOSTICS
These functions return EOF on end of input or error and a count
which is shorter than expected for unexpected or unmatched
items.
SEE ALSO
Atoi(),Atof(),Gete(),Printf() Kernighan and Ritchie pp 147-150
Page 4 - 26
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Setbuf - fix file buffer
USAGE
finclude <stdio.h>
setbuf(fp, buffer)
FILE *fp;
char *buffer;
DESCRIPTION
When the first character is written to or read from a file
after it has been opened by "fopen()", a buffer is obtained
from the system if required and assigned to it. Setbuf may be
used to forestall this by assigning a user buffer to the file.
Setbuf must be used after the file has been opened and before
any I/O has taken place.
The buffer must be of sufficient size and a value for a
manifest constant, BUFSIZ, is defined in the header file for
use in declarations.
If the "buffer" argument is NULL (0), the file becomes un-
buffered and characters are read or written singly.
NOTE that the standard error output is unbuffered and the
standard output is buffered.
SEE ALSO
fopen(),getc(),putc().
Page 4 - 27
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Sleep - stop execution for a time
USAGE
sleep(seconds)
unsigned seconds;
DESCRIPTION
The current task is stopped for the specified time.
If "seconds" is zero, the task will sleep for one tick.
Page 4 - 28
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Strcat, Strncat, Stremp, Strnemp, Strepy, Strhepy, Strnepy,
Strlen,Index, Rindex- string functions
USAGE
char #strcat(s1,s2)
char *s1, *s2:
char *strncat(s1,s2,mn)
char #s1,#s2;
int п;
stremp(s1,s2)
char #s1,#s2;
char *strhcpy(s1,s2)
char #s1,#s2;
strnemp(s1,s2,n)
char #s1,%#32;
int n;
char *strcepy(s1,s2)
char #s1,%#32;
char *strnepy(s1,s2,n)
char #31, #32;
int n;
strlen(s)
char *s;
char *index(s,ch)
char *s,ch;
char *rindex(s,ch)
char *s,ch;
DESCRIPTION
All strings passed to these functions are assumed mnull-
terminated.
Strcat appends a copy of the string pointed to by "s2" to the
end of the string pointed to by "si". Strncat copies at most
An” characters, Both return the first argument.
Stremp compares strings "s1" and "s2" for lexicographic order
and returns an integer less than, equal to or greater than 0
where, respectively, "s1" is less than, equal to or greater
than "s2", Strnemp compares at most "n" characters.
Page 4 - 29
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Strepy copies characters from "s2" to the space pointed to by
"s1" up to and including the null byte. Strncpy copies exactly
An” characters. If the string "s2" is too short, the "s1" will
be padded with null bytes to make up the difference. If "52"
is too long, "s1" may not be null-terminated. Both functions
return the first argument,
Strhepy copies string with sign bit terminator.
Strlen returns the number of non-null characters in ms",
Index returns a pointer to the first occurrence of "ch" in "s"
or NULL if not found,
Rindex returns a pointer to the last occurrence of "ch" in "s"
or NULL if not found.
CAVEATS
Strcat and strepy have no means of checking that the space
provided is large enough. It is the user's responsibility to
ensure that string space does not overflow.
SEE ALSO
Findstr().
Page 4 - 30
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
System - shell command request
USAGE
system(string)
char #string;
DESCRIPTION
System passes its argument to "shell" which executes it as a
command line. The task is suspended until the shell command
is completed and system returns the shell's exit status. The
maximun length of string is 80 characters. If a longer string
is needed, use os9fork.
SEE ALSO
System calls Tos9fork()","wait()".
Page 4 - 31
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Toupper, Tolower - character translation
USAGE
#include <ctype.h>
int toupper(c)
int ce;
etc.
int _toupper(c)
int c;
int _tolower(c)
int cs;
DESCRIPTION
The functions toupper and tolower have as their domain the
integers in the range -1 through 255. Toupper converts lower-
case to upper-case, and tolower converts upper-case to lower-
case. All other arguments are returned unchanged.
The macros _toupper and _tolower do the same things as the
corresponding functions, but they have restricted domains and
they are faster, The argument to _toupper must be lower-case,
and the argument to _tolower must be upper-case,
that are outside each macros domain, such as passing a lower=-
case to _tolower, yield garbage results.
Page 4 - 32
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Ungete - put character back on input
USAGE
#include <stdio.h>
ungetce(ch, fp)
char ch;
FILE *fp;
DESCRIPTION
This function alters the state of the input file buffer such
that the next call of "gete()" returns "ch",
Only one character may be pushed back, and at least one
character must have been read from the file before a call to
ungetc.
"Fseek()" erases any pushback.
DIAGNOSTICS
Ungetc returns its character argument unless no pushback could
occur, in which case EOF is returned.
SEE ALSO
gete(),fseek()
Page 4 - 33
MICROWARE C COMPILER USER'S GUIDE
C STANDARD LIBRARY
Page 4 - 34
MICROWARE C COMPILER USER'S GUIDE
APPENDIX A
COMPILER GENERATED ERROR MESSAGES
Below is a list of the error messages that the C compiler generates,
and, if applicable, probable causes and the K & R Appendix A section
number (in parenthesis) to see for more specific information.
already a local variable
Variable has already been declared at the current block level.
(8.1, 9.2)
argument : <text>
Error from preprocessor. Self-explanatory. Most common cause
of this error is not being able to find an include file.
argument error
Function argument declared as type struct, union, or function.
Pointers to such types, however, are allowed. (10.1)
argument storage
Function arguments may only be declared as storage class
register. (10.1)
bad character
A character not in the C character set (probably a control
char) was encountered in the source file. (2)
both must be integral
>> and << operands cannot be FLOAT or DOUBLE. (7.5)
break error
The break statement is allowed only inside a while, do, for, or
switch block. (9.8)
can't take address
& operator is not allowed on a register variable. Operand must
otherwise be an lvalue. (7.2)
cannot cast
Type result of cast cannot be FUNCTION or ARRAY. (7.2, 8.7)
cannot evaluate size
Could not determine size from declaration or initializer.
(8.6, 14.3)
cannot initialize
Storage class or type does not allow variable to be
initialized. (8.6)
compiler trouble
Compiler detected something it couldn't handle. Try compiling
the program again, If this error still occurs, contact Radio
Shack.
Page A-1
MICROWARE C COMPILER USER'S GUIDE
APPENDIX A
condition needed
While, do, for, switch, and if statements require a condition
expression. (9.3)
constant expression required
Initializer expressions for static or external variables cannot
reference variables. They may, however, refer to the address
of a previously declared variable. This installation allows no
initializer expressions unless all operands are of type INT or
CHAR (8.6)
constant overflow
Input numeric constant was too large for the implied or
explicit type. (2.6, [PDP-11])
constant required
Variables are not allowed for array dimensions or cases. (8.3,
8.7, 9.7)
continue error
The continue statement is allowed only inside a while, do, or
for block. (9.9)
declaration mismatch
This declaration conflicts with a previous one. This is
typically caused by declaring a function to return a non-
integer type after a reference has been made to the function.
Depending on the line structure of the declaration block, this
error may be reported on the line following the erroneous
declaration, (11, 11.1 11.2)
divide by zero
Divide by zero occurred when evaluating a constant expression.
? expected
? is any character that was expected to appear here, Missing
semicolons or braces cause this error.
expression missing
An expression is required here,
function header missing
Statement or expression encountered outside a function.
Typically caused by mismatched braces. (10.1)
function type error
A function cannot be declared as returning an array, function,
struct, or union. (8.4, 10.1)
function unfinished
End-of-file encountered before the end of function definition.
(10.1)
identifier missing
Identifier name required here but none was found.
Page A=?
MICROWARE C COMPILER USER'S GUIDE
APPENDIX A
illegal declaration
Declarations are allowed only at the beginning of a block.
(9.2)
label required
Label name required on goto statement. (9.11)
label undefined
Goto to label not defined in the current function. (9.12)
lvalue required
Left side of assignment must be able to be "stored into",
Array names, functions, structs, etc. are not lvalues. (7.1)
multiple defaults
Only one default statement is allowed in a switch block. (9.7)
multiple definition
Identifier name was declared more than once in the same block
level (9.2, 11.1)
must be integral
Type of object required here must be type int, char, or
pointer,
name clash
Struct-union member and tag names must be mutually distinct.
(8.5)
name in a cast
Identifier name found in a cast. Only types are allowed. (7.2,
8.7)
named twice
Names in a function parameter list may appear only once. (10.1)
no "if! for 'else!
Else statement found with no matching if. This is typically
caused by extra or missing braces and/or semicolons. (9.3)
no switch statement
Case statements can only appear within a switch block. (9.7)
not a function
Primary in expression is not type "function returning...", If
this is really a function call, the function name was declared
differently elsewhere. (7.1)
not an argument
Name does not appear in the function parameter list. (10.1)
operand expected
Unary operators require one operand, binary operators two.
This is typically caused by misplaced parenthesis, casts or
Page A-3
MICROWARE C COMPILER USER'S GUIDE
APPENDIX A
operators, (7.1)
out of memory
Compiler dynamic memory overflow. The compiler requires
dynamic memory for symbol table entries, block level
declarations and code generation. Three major factors affect
this memory usage, Permanent declarations (those appearing on
the outer block level (used in include files)) must be reserved
from the dynamic memory for the duration of the compilation of
the file, Each { causes the compiler to perform a block-level
recursion which may involve "pushing down" previous
declarations which consume memory. Auto class initializers
require saving expression trees until past the declarations
which may be very memory-expensive if they exist. Avoiding
excessive declarations, both permanent and inside compound
statement blocks, conserve memory. If this error occurs on an
auto initializer, try initializing the value in the code body.
pointer mismatch
Pointers refer to different types. Use a cast if required.
(7.1)
pointer or integer required
A pointer (of any type) or integer is required to the left of
the '->' operator. (7.1)
pointer required
Pointer operand required with unary * operator. (7.1)
primary expected
Primary expression required here. (7.1)
should be NULL
Second and third expression of ?: conditional operator cannot
be pointers to different types. If both are pointers, they
must be of the same type or one of the two must be null. (7.13)
#### STACK OVERFLOW *=*=**
Compiler stack has overflowed. Most likely cause is very deep
lock-level nesting or hundreds of switch cases.
storage error
Reg and auto storage classes may only be used within functions.
(8.1)
struct member mismatch
Identical member names in two different structures must have
the same type and offset in both. (8.5)
struct member required
Identifier used with . and -> operators must be a structure
member name. (7.1)
struct syntax
Brace, comma, etc. is missing in a struct declaration. (8.5)
Page A-4
MICROWARE C COMPILER USER'S GUIDE
APPENDIX A
struct or union inappropriate
Struct or union cannot be used in this context.
syntax error
Expression, declaration, or statement is incorrectly formed.
third expression missing
7 must be followed by a : with expression. This error may be
caused by unmatched parenthesis or other errors in the
expression. (7.13)
too long
Too many characters provided in a string initializing a
character array. (8.6)
too many brackets
Unmatched or unexpected brackets encountered processing an
initializer. (8.6)
too many elements
More data items supplied for aggregate level in initializer
than members of the aggregate. (8.6)
type error
Compiler type matching error. Should never happen,
type mismatch
Types and/or operators in expression do not correspond. (6)
typedef - not a variable
Typedef type name cannot be used in this manner. (8.8)
undeclared variable
No declaration exists at any block level for this identifier,
undefined structure
Union or struct declaration refers to an undefined structure
name. (8.5)
unions not allowed
Cannot initialize union members. (8.6)
unterminated character constant
Unmatched ' character delimiters. (2.4.3)
unterminated string
Unmatched " string delimiters. (2.5)
while expected
No while found for do statement. (9.5)
Page A-5
MICROWARE C COMPILER USER'S GUIDE
APPENDIX A
Page A-6
MICROWARE C COMPILER USER'S GUIDE
APPENDIX B
COMPILER PHASE COMMAND LINES
This appendix describes the command lines and options for the
individual compiler phases, Each phase of the compiler may be
executed separately. The following information describes the
options available to each phase.
cel & cc2 (C executives):
cc [options] file {file} [options]
Recognized file suffixes:
‚ © C source file
‚а Assembly language source file
‚Г Relocatable module format file
Recognized options: (UPPER and lower case is equiv.)
-a Suppress assembly. Leave output in ".a" file.
-e=n Edition number (n) is supplied to c.prep for
inclusion in module psect and/or to c.link for
inclusion as the edition number of the linked
module.
-0 Inhibits assembler code optimizer pass.
-p Invoke compiler function profiler,
-r Suppress link step. Leave output in ",r" file.
-m=<size> Size in pages (in kbytes if followed by a K) of
additional memory the linker should allocate to
object module.
-l=<path> Library file for linker to search before the
standard library,
-f-<path> Overrride other output naming. Module name (in
object module) is the last name in the pathlist.
-f is not allowed with -a or -r,
=C Output comments in assembly language code.
-S Suppress generation of stack-checking code.
-d<NAME> Is equiv to #define <NAME> 1 in the
preprocessor. -d<NAME>=<STRING> is equivalent to
#define <NAME> <STRING>.
-n=<name> output module name. <name> is used to override
the -f default output name.
CC1 only:
X Create, but do not execute c.com command file,
CC2 only:
-q Quiet mode. Suppress echo of file names.
Page B-1
MICROWARE C COMPILER USER'S GUIDE
APPENDIX B
с.ргер (С macro preprocessor)
c.prep [options] <path>
<path> is read as input. C.prep causes c.comp to generate a
psect directive with the last element of the pathlist and _c as
the psect name. If <path> is /d0/myprog.c, the psect name is
myprog_c. Output is always to stdout.
Recognized options:
-1 Cause c.comp to copy source lines to assembly
output as comments.
-E=<n>
-e=<n> Use <n> as psect edition number,
-D<NAME> Same as described above for cc1/cc2.
c.comp (One-pass compiler)
c.comp [options] [<file>] [options]
If <file> is not present, c.comp will read stdin. Input text
need not be c.prep output, but no preprocessor directives are
recognized (#include, +#define, macros etc.). Output assembly
code is normally to stdout. Error message output is always
written to stdout.
Recognized options;
-S Suppress generation of stack checking code.
-p Generate profile code.
-o=<path> Write assembly output to <path>.
c.pass1 (Pass One of Two-pass Compiler)
c.pass2 (Pass Two of Two-pass Compiler)
c.pass1 [options] [<file>] [options]
c.pass2 [options] [<file>] [options]
Command line and options are the same as c.comp. If the
options given to c.pass1 are not given to c.pass2 also, c.pass?
will not be able to read the c.pass1 output. Both ¢.pass1 and
e.pass? read stdin and write stdout normally,
Page B-2
MICROWARE C COMPILER USER'S GUIDE
APPENDIX B
c.opt (Assembly code optimizer)
c.opt [<inpath>] [<outpath>]
C.opt reads stdin and writes stdout. <inpath> must be present
if <outpath> is given. Since c.opt rearranges and changes
code, comments and assembler directives may be rearranged.
c.asm (Assembler)
c.asm <file> [options]
C.asm reads <file> as assemble language input. Errors are
written to stderr. Options are turned on or off by the
inclusion of the option character preceeded by a '-"',
Recognized options:
-o=<{path)> Write relocatable output to path. Must be a
disk file.
-1 Write listing to stdout. (default off)
-C List conditional assembly lines. (default on)
-f Formfeed for top of form. (default off)
-g List all code bytes generated. (default off)
-x Suppress macro expansion listing. (default on)
-e Print errors. (default on)
-5 Print symbol table. (default off).
-dn Set lines per page to n. (default 66).
-wn Set line width to n. (default 80).
c.link (Linker)
c.link [options] <mainline> [<sub1> {<subn>} ] [options]
C.link turns c.asm output into executable form, All input
files must contain relocatable object format (ROF) files.
<mainline> specifies the base module from which to resolve
external references. A mainline module is indicated by setting
the type/lang value in the psect directive non-zero. No other
ROF can contain a mainline psect. The mainline and all
subroutine files will appear in the final linked object module
whether actually referenced or not.
For the C Compiler, cstart.r is the mainline module. It is the
mainline module's job to perform the initialization of data and
the relocation of any data-text and data-data references within
the initialized data using the information in the object module
supplied by c.link.
Page B-3
MICROWARE C COMPILER USER'S GUIDE
APPENDIX B
(c.link continued)
Recognized options:
-o=<path>
-n=<name>
-l=<path>
-E=<n>
-e=<{n>
-M=<size>
—M
-3
-b=<ept>
Linker object output file must be a disk
file. The last element in <path> is used as the
module name unless overridden by -n.
Use <name> as output module name.
Use <path> as library file. A library file
consists of one or more merged assembly ROF
files. Each psect in the file is checked to see
if it resolves any unresolved references, If
so, the module is included in the final output
module, otherwise it is skipped. No mainline
psects are allowed in a library file. Library
files are searched in the order given on the
command line,
<n> ís used for the edition number in the final
output module. 1 is used if -e is not present.
<size> indicates the number of pages (kbytes if
size is followed by a K) of additional memory,
c.link will allocate to the data area of the
final object module. If no additional memory is
given, c.link adds up the total data stack
requirements found in the psect of the modules
in the input modules.
Prints linkage map indicating base addresses of
the psects in the final object module.
Prints final addresses assigned to symbols in
the final object module.
Link C functions to be callable by BASICOQ9.
<ept> is the name of the function to be
transferred to when BASIC09 executes the RUN
command.
Allows static data to appear in a BASICO9 call-
able module, It is assumed the C function call-
ed and the calling BASIC09 program have provided
a sufficiently large static storage data area
pointed to by the Y register.
Page B-14
MICROWARE C COMPILER USER'S GUIDE
APPENDIX B
USING AND LINKING TO USER DEFINED LIBRARIES
A library consists of a group of "C" procedures or functions that
have been separately compiled into Relocatable Object Files (ROF)
and subsequently merged into one library file.
If, hypothetically, you had created a set of higher level mathematic
functions, that you wanted to convert into a "C" library. First you
would separately compile each one using the -R option. Then you
would merge them all into one large library file, If you need to
scan the library file for available functions you can use the
example program "RDUMP.C"™ to inspect any "C" library file.
For example:
0Sg:CC1 SIN.C COS.C TAN.C ARCOS.C -R
059:CC1 ARCSIN.C ARCTAN.C EXP.C LOG.C =R
0S9:CC1 NLOG.C SQRT.C SQR.C CUBE.C -R
Then you would:
0S9:MERGE SIN.R COS.R TAM.R ARCOS.R >TEMP1
OS9:MERGE ARCSIN.R ARCTAN.R EXP.R LOG.R >TEMP2
0S9:MERGE NLOG.R SQRT.R SQR.R CUBE.R >TEMP3
0S9:MERGE TEMP1 TEMP2 TEMP3 >TRIG.L
Then to use the library simply use the -l=<pathlist> option in your
command line when you compile your program.
When the linker is executed the pathlist specified will be searched
to resolve any references made to the functions within the library.
The linker searches all specified libraries in the order specified
before searching the standard library. The linker will resolve all
references on a first found basis. This means that the linker will
use the first procedure or function whose name matches a reference
to that name and will ignore any additional functions found that
have the same name.
Procedures or functions within a library that use other functions
within the same library should always appear first. For example, in
the above example if the "ARCSIN" routine used the "SIN" routine,
the "SIN" routine should be merged into the library file after the
"ARCSIN", Another way of putting this is that all references to
other procedures within a library should be forward references.
Page B-5
MICROWARE C COMPILER USER'S GUIDE
APPENDIX B
Page B-6
MICROWARE C COMPILER USER'S GUIDE
APPENDIX C
INTERFACING TO BASICOQ9
The object code generated by the Microware C Compiler can be made
callable from the BASIC09 "RUN" statement. Certain portions of a
BASIC09 program written in C can have a dramatic effect on execution
speed, To effectively utilize this feature, one must be familiar
with both C and BASICO9 internal data representation and procedure
calling protocol.
С type "int" and BASIC09 type "INTEGER" are identical; both are two
byte two's complement integers. C type "char" and BASICOS type
"BYTE" and "BOOLEAN" are also identical. Keep in mind that C will
sign-extend characters for comparisons yielding the range -128 to
127.
BASIC09 strings are terminated by Oxff (255). C strings are
terminated by 0x00 (0). If the BASICOS string is of maximum length,
the terminator is not present. Therefore, string length as well as
terminator checks must be performed on BASIC09 strings when
processing them with C functions.
The floating point format used by C and BASICOS are not directly
compatible. Since both use a binary floating point format it is
possible to convert BASICOS reals to C doubles and vice-versa,
Multi-dimensional arrays are stored by BASIC09 in a different manner
than С. Multi-dimensional arrays are stored by BASICO9Y in a column-
wise manner; С stores them row-wise. Consider the following
example:
BASICOS matrix: DIM array(5,3):INTEGER.
The elements in consecutive memory locations (read left to
right, line by line) are stored as:
(1,1),(2,1),(3,1),(4,1),(5,1)
(1,2),(2,2),(3,2),(4,2),(5,2)
(1,3),(2,3),(3,3),(4,3),(5,3)
С matrix: int array[5][3];
The elements in consecutive memory locations (read left to
right, line by line) are stored as:
(1,1),(1,2),(1,3)
(2,1),(2,2),(2,3)
(3,1),(3,2),(3,3)
(4,1),(4,2),(4,3)
(5,1),(5,2),(5,3)
Therefore to access BASIC09 matrix elements in C, the subscripts
must be transposed. To access element array(4,2) in BASICO9 use
array[2][4] in C.
The details on interfacing BASIC09 {бо С are best described by
example, The remainder of this appendix is a mini tutorial
demonstrating the process starting with simple examples and working
up to more complex ones.
Page C-1
MICROWARE C COMPILER USER'S GUIDE
APPENDIX C
EXAMPLE 1 ~ SIMPLE INTEGER ARITHMETIC CASE
This first example illustrates a simple case. Write a C function to
add an integer value to three integer variables.
build bt1.ec
? addints(ent,value,s1,arg1,s2,arg2,S3,arg3,s4)
? int *value, *arg1l, *arg?, *arg3;
? |
? targ1 + *value;
? arg? += tvalue:
? targ3 += *value;
?
?
That's the C function. The name of the function is "addints". The
name is information for C and c.link; BASICOS will not know anything
about the name. Page 9-13 of the BASICOS Reference manual describes
how BASIC09 passes parameters to machine language modules. Since
BASIC09 and C pass parameters in a similar fashion, it is easy to
access BASICOS values. The first parameter on the BASICOS stack is
a two byte count of the number of following parameter pairs. Each
pair consists of an address and size of value. For most C
functions, the parameter count and pair size is not used. The
address, however, is the useful piece of information. The address
is declared in the C function to always be a "pointer to..." type.
BASICOS always passes addresses to procedures, even for constant
values. The arguments ent, s1, s2, s3, and s4 are just place
holders to indicate the presence of the parameter count and argument
sizes on the stack. These can be used to check validity of the
passed arguments if desired.
The line "int *value,*argl,*arg2,*arg3" declares the parameters (in
this case all "pointers to int"), so the compiler will generate the
correct code to access the BASICOS values. The remaining lines
increment each arg by the passed value. Notice that a simple
arithmetic operation is performed here (addition), so C will not
have to call a library function to do the operation.
To compile this function, the following C compiler command line is
used:
cc2 bt1.c -rs
Cc2 uses the Level-Two compiler. Replace cc2 with cc1 if you are
using the Level-One compiler. The -r option causes the compiler to
leave bt1.r as output, ready to be linked. The -s option suppresses
the call to the stack checking function. Since we will be making a
module for BASICOS, cstart.r will not be used. Therefore, no
initialized data, static data, or stack checking is allowed. More
on this later.
Page C-2
MICROWARE C COMPILER USER'S GUIDE
APPENDIX C
The bt1.r file must now be converted to a loadable module that
BASIC09 can link to by using a special linking technique as follows:
c.link bt1.r -b-addints -o-zaddints
This command tells the linker to read bt1.r as input. The option
"-b=addints" tells the linker to make the output file a module that
BASICOY can link to and that the function "addints" is to be the
entrypoint in the module, You may give many input files to c.link
in this mode. It resolves references in the normal fashion. The
name given to the "-b=" option indicates which of the functions is
to be entered directly by the BASICO9Y RUN command. The option
"-ozaddints" says what the name of the output file is to be, in this
case "addints", This name should be the name used in the BASICOS
RUN command to call the C procedure. The name given in the "-o="
option is the name of the procedure to RUN. The "-b=" option is
merely information to the linker so it can fill in the correct
module entrypoint offset.
Enter the following BASICOS program:
PROCEDURE btest
DIM i,j,kK: INTEGER
i=1
j=132
k=-1033
RUN addints(#,i,j,k)
PRINT i, j,k
END
When this procedure is RUN, it should print:
5 136 - 1029
indicating that our C function worked!
Page C-3
MICROWARE C COMPILER USER'S GUIDE
APPENDIX C
EXAMPLE 2 - MORE COMPLEX INTEGER ARITHMETIC CASE
The next example shows how static memory area can be used. Take the
C function from the previous example and modify it to add the number
of times it has been entered to the increment:
build bt2.c
? static int entent;
?
? addints(ent,cmem,cmemsiz,value,s1,arg1,52,arg2,53,arg3,s4#)
? char *emen;
? int *value,*arg1,targ2,targ3;
? {
? fasm
? ldy 6,s base of static area
? #endasn
? int j = *value + entent++;
?
? Targl += J;
? “arg? += Jj;
? t*arg3 + j;
? }
7
This example differs from the first in a number of ways. The line
"static int entent" defines an integer value named entent global to
bt2.c. The parameter cmem and the line "char *cmem" indicate a
character array, The array will be used in the C function for
global/static storage. С accesses non-auto and non-register
variables indexed off the Y register. Cstart.r normally takes care
of setting this up. Since estart.r will not be used for this
BASIC09 callable function, we have to take measures to make sure the
Y register points to a valid and sufficiently large area of memory.
The line "ldy 6,s" is assembly language code embedded in C source
that loads the Y register with the first parameter passed by
BASICOS. If the first parameter in the BASICO9Y RUN statement is an
array, and the "ldy 6,s" is placed IMMEDIATELY after the "(" opening
the function body, the offset will always be "6,s", Note the line
beginning "int j = ...". This line uses an initializer which, in
this case, is allowed because j is of class "auto". No classes but
"auto" and "register" car be initialized in BASICOS callable C
functions.
To compile this function, the following C compiler command line is
used:
ce bt2.ec -rs
Where ce is cel or ce2.
Again, the -r option leaves bt2.r as output and the -s option
suppresses stack checking.
Normally, the linker considers it to be an error if the "-b=" option
appears and the final linked module requires a data memory
Page C-4
MICROWARE C COMPILER USER'S GUIDE
APPENDIX C
allocation. In our case here, we require a data memory allocation
and we will provide the code to make sure everything is set up
correctly. The "-t" linker option causes the linker to print the
total data memory requirement so we can allow for it rather than
complaining about it. Our linker command line is:
c.link bt2.r -ozaddints -b=addints -t
The linker will respond with "BASICOS static data size is 2 bytes".
We must make sure cmem points to at least 2 bytes of memory. The
memory should be zeroed to conform to C specifications.
Enter the following BASICOS program:
PROCEDURE btest
DIM i, j,k,n:INTEGER
DIM cmem(10):INTEGER
FOR i=1 TO 10
cmem(i)=0
NEXT 1
FOR n=1 TO 5
i=1
j=132
k=-1033
RUN addints(cmem,4,i,j,k)
PRINT i,j,k
NEXT n
END
This program is similar to the previous example. Our area for data
memory is a 10 integer array (20 bytes) which is way more than the 2
bytes for this example. It is better to err on the generous side.
Cmem is an integer array for convenience in initializing it to zero
(per C data memory specifications). When the program is run, it
calls addints 5 times with the same data values. Because addints
adds the number of times it was called to the value, the i, j,k
values should be d+number of times called, When run, the program
prints:
5 136 -1029
6 137 -1028
7 138 -1027
8 139 -1026
9 140 -1025
Works again!
Page C-5
This
MICROWARE C COMPILER USER'S GUIDE
APPENDIX C
EXAMPLE 3 - SIMPLE STRING MANIPULATION
example shows how to access BASICOS strings through С
functions. For this example, write the C version of SUBSTR:
build bt3.c
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
?
/* Find substring from BASICOS string:
RUN findstr(A$,B$,fndpos)
returns in fndpos the position in A$ that B$ vas found or
0 if not found. A$ and B$ must be strings, fndpos must be
INTEGER.
* /
findstr(ent,string,strent,srehstr,srechent,result)
char *string, *srchstr;
int strent,srchent,*result;
{
}
*result = finder(string,strent,srchstr,srchent);
static finder(str,strlen,pat,patlen)
char *str,*pat;
int strlen,patlen;
{
int i;
for(i=1;strlen-- > 0 && *str!=0xff; ++i)
if(smatch(str++,pat,patlen))
return 1;
}
static smatch(str,pat,patlen)
register char *str, *pat;
int patlen;
{
while(patlen-- > 0 && *pat != Oxff)
if(#str++ != *pat++)
return 0;
return 1;
Compile the program:
cc bt3.c -rs
Where ce is cel or ce?
And link it:
с.
link bt3.r -o=findstr -b=findstr
Page C-6
MICROWARE C COMPILER USER'S GUIDE
APPENDIX C
The BASICO9 test program is:
PROCEDURE btest
DIM a,b:STRING[ 20]
DIM matchpos:INTEGER
LOOP
INPUT "String ",a
INPUT "Match ",b
RUN findstr(a,b,matchpos)
PRINT "Matched at position ",matchpos
ENDLOOP
When the program is run, it should print the position where the
matched string was found in the source string.
Page C-7
MICROWARE C COMPILER USER'S GUIDE
APPENDIX C
EXAMPLE 4 - QUICKSORT
The next example programs demonstrate how one might implement a
quicksort written in C to sort some BASICO9 data.
C integer quicksort program:
#define swap(a,b) { int t; t=a; a=b; b=t; }
/* gsort to be called by BASICO09:
dim d(100):INTEGER any size INTEGER array
run cqsort(d, 100) calling gsort.
*/
qsortí(argent,iarray,iasize,icount,icsiz)
int argent, /* BASICOS argument count */
iarray[], /* Pointer to BASICOS integer array */
iasize, /* and it's size */
ticount, /* Pointer to BASICOS (sort count) */
iesiz; /* Size of integer */
{
sort(iarray,0,*icount); /®* initial gsort partition #/
}
/* standard quicksort algorithm from Horowitz-Sahni #/
static sort(a,m,n)
register int *a,m,n;
{
register 1i, j,x;
if(m < п) {
1 = п;
J=n+ 1;
x = a[m];
for(;;) {
do i += 1; while(a[i] < x); /* left partition */
do j -= 1; while(a[ j] > x); /#* right partition */
if(i < 3)
swap(a[i],al[j]) /* swap */
else break;
}
swap(a[m],al jl);
sort(a,m, j=1); /* sort left */
sort(a, j+1,n); /* sort right */
Page C-8
MICROWARE C COMPILER USER'S GUIDE
APPENDIX C
The BASIC09 program is:
PROCEDURE sorter
DIM i,n,d(1000):INTEGER
n=1000
i=RND(-(PI))
FOR i=1 TO n
d(i):=INT(RND( 1000) )
NEXT i
PRINT "Before;"
RUN prin(1,n,d)
RUN gsortb(d,n)
PRINT "After:"
RUN prin(1,n,d)
END
PROCEDURE prin
PARAM n,m,d(1000):INTEGER
DIM i:INTEGER
FOR i=n TO m
PRINT d(i); " ";
NEXT 1
PRINT
END
C string quicksort program:
/* qsort to be called by BASICO9:
dim cmemory:STRING[10] This should be at least as large as
the linker says the data size should
be.
dim d(100): INTEGER Any size INTEGER array.
run cqsort(cmemory,d,100) calling gsort. Note that the pro-
cedure name run is the linked 05-9
subroutine module. The module name
need not be the name of the C func-
tion.
#/
int maxstr; /* string maximum length */
static strbemp(str1,str2) /* basic09 string compare */
register char *str1,*str2;
{
int maxlen;
for (maxlen = maxstr; *str1 == #str2 ;++str1)
if (maxlen-- > 0 !! *str2++ == Oxff)
return 0;
return (*str1 - *str2);
}
Page C-9
MICROWARE C COMPILER USER'S GUIDE
APPENDIX C
cssort(argent,stor,storsiz,iarray,iasize,elemlen,elsiz,
icount,icsiz)
int argent; /* BASICOS argument count */
char #stor; /* Pointer to string (C data storage) */
char iarray[]; /* Pointer to BASICO9 integer array */
int 1аз12е, /* and it's size */
*elenlen, /* Pointer integer value (string length) #/
elsiz; /* Size of integer */
*icount, /* Pointer to integer (sort count) */
icsiz; /* Size of integer */
{
/* The following assembly code loads Y with the first
arg provided by BASICOS. This code MUST be the first code
in the function after the declarations. This code assumes the
address of the data area is the first parameter in the BASICOS
RUN command. */
fasm
ldy 6,s get addr for C data storage
#endasm
/* Use the C library gsort function to do the sort. Our
own BASICOS string compare function will compare the strings.
* /
qsort(iarray, *icount,maxstr=*elemlen,strbemp);
}
/% define stuff cstart.r normally defines */
fasm
_stkcheck:
rts dummy stack check function
vsect
errno: rmb 2 C function system error number
_flace: rmb 8 C library float/long accumulator
endsect
fendasm
The BASICOS calling program: (words file contains strings to sort)
PROCEDURE ssorter
DIM a(200):STRING[20]
DIM cmemory:STRING[ 20]
DIM i,n:INTEGER
DIM path:INTEGER
OPEN #path,"words";READ
n=100
FOR i=1 TO n
INPUT #path,a(i)
NEXT i
CLOSE #path
RUN prin(a,n)
RUN c¢ssort(cmemory,a,20,n)
Page C-10
MICROWARE C COMPILER USER'S GUIDE
APPENDIX C
RUN prin(a,n)
END
PROCEDURE prin
PARAM a(100):STRING[{20]; n:INTEGER
DIM i:INTEGER
FOR i=1 TO n
PRINT 1; " "; а(1)
NEXT i
PRINT
END
The next example shows how to access BASICOS reals from C functions:
flmult(cent,cmemory,cmemsiz,realarg,realsize)
int ent; /* number of arguments */
char tememory; /* pointer to some memory for C use #/
double trealarg; /* pointer a real */
{
ffasm
1ау 6,8 get static memory address
#endasm
double number;
getbreal(&number,realarg); /* get the BASICOS real */
number *= 2.; /* number times twot/
putbreal(realarg, &number); /* give back to BASICOS */
}
/* getbreal(creal,breal)
get a 5-byte real from BASIC09 format to C format #/
getbreal(creal,breal)
double *creal, *breal;
{
register char “cr, *br; /* setup some char pointers #/
er = creal;
br = breal;
fasm
* At this point U reg contains address of C double
* 0,s contains address of BASICOS real
ldx 0,s get address of B real
clra clear the C double
clrb
std O,u
std 2,u
std 4,u
stb 6,u
ldd O,x
Page C-11
MICROWARE C COMPILER USER'S GUIDE
APPENDIX C
bed g3 BASICO9 real is zero
ldd 1,x get hi B mantissa
anda #$7f clear place for sign
std 0,u put hi C mantissa
ldd 3,x get lo B mantissa
andb #$fe mask off sign
std 2,u put lo C mantissa
lda 4,x get B sign byte
lsra shift out sign
bec g1
lda 0,u get C sign byte
ora #$80 turn on sign
sta O,u put C sign byte
g1 lda 0,x get B exponent
suba #128 excess 128
sta 7,u put C exponent
g3 clra clear carry
#endasm
}
/* putbreal(breal,creal)
put C format double into a 5-byte real from BASICO9 #/
putbreal(breal,creal)
double *breal,*creal;
{
register char ter,*br; /* setup some char pointers #/
cr = creal;
br = breal;
ffasm
* At this point U reg contains address of C double
* 0,s contains address of BASICOS real
ldx 0,s get address of B real
lda 7,u get C exponent
bne pO not zero?
clra clear the BASICOS
clrb real
std 0,x
std 2,x
sta 4,x
bra p3 and exit
pO ldd 0,u get hi C mantissa
ora #$80 this bit always on for normalized real
std 1,x put hi B mantissa
ldd 2,u get lo C mantissa
std 3,x put lo B mantissa
incb round mantissa
bne p1
inc 3,x
bne p1
Page C-12
MICROWARE C COMPILER USER'S GUIDE
APPENDIX C
inc 2,x
bne p1
ine 1,x
p1 andb #$fe turn off sign
stb 4,x put B sign byte
lda 0,u get C sign byte
lsla shift out sign
bce p2 bra if positive
orb #$01 turn on sign
stb 4,x put B sign byte
p2 lda 7,u get C exponent
adda #128 less 128
sta 0,x put B exponent
p3 clra clear carry
fendasm
}
/* replace cstart.r definitions for BASICOS */
#asm
_stkcheck:
_stkchec:
rts
vsect
_flace: rmb 8
errno: rmb 2
endsect
#endasm
BASIC09 calling program:
PROCEDURE btest
DIM a:REAL
DIM i: INTEGER
DIM cmemory:STRING[32]
a=1.
FOR i=1 TO 10
RUN flmult(cmemory,a)
PRINT a
NEXT i
END
Page C-13
MICROWARE C COMPILER USER'S GUIDE
APPENDIX C
The last program is an example of accessing BASIC09 matrix elements.
The C program:
matmult(ent,cmemory,cmemsiz,matxaddr,matxsize,scalar,scalsize)
char *cmemory; /* pointer to some memory for C use */
int matxaddr[5][3]; /* pointer a double dim integer array */
int *scalar; /* pointer to integer */
{
fasm
ldy 6,s get static memory address
#endasm
int i,j;
for(i=0; i<5; ++i)
for(j=1; j<3; ++j)
matxaddr[j][i]) #= *#scalar; /* multiply by value
% /
}
#asm
_stkcheck:
_stkchec:
rts
vsect
_flacc: rmb 8
errno: rmb 2
endsect
#endasm
BASIC09 calling program:
PROCEDURE btest
DIM im(5,3):INTEGER
DIM i,j:INTEGER
DIM cmem:STRING[32]
FOR i=1 TO 5
FOR j=1 TO 3
READ im(i, j)
NEXT j
NEXT i
DATA 11,13,7,3,4,0,5,7,2,8,15,0,0,14,4
FOR i=1 TO 5
PRINT im(i,1),im(i,2),im(i,3)
NEXT i
PRINT
RUN matmult(cmem,im,64)
FOR i=1 TO 5
PRINT im(i,1),im(i,2),im(i,3)
NEXT i
END
Page C-14
MICROWARE C COMPILER USER'S GUIDE
APPENDIX D
RELOCATING MACRO ASSEMBLER REFERENCE
This appendix gives a summary of the operation of the "Relocating
Macro Assembler" (named c.asm as distributed with the C Compiler).
This appendix and the example assembly source files supplied with
the C compiler should provide basic information on how to use the
"Relocating Macro Assembler" to create relocatable-object format
files (ROF). It is further assumed that you are familiar with the
6809 instruction set and mnemonics. See the Microware Relocating
Assembler Manual for a more detailed description. The main function
of this appendix is to enable the reader to understand the output
produced by c.asm. The Relocating Macro Assembler allows programs
to be compiled separately and then linked together, and it also
allows macros to be defined within programs.
Differences between the Relocating Macro Assembler(RMA) and the
Microware Interactive Assembler (MIA):
RMA is does not have an interactive mode. Only a disk file is
allowed as input.
RMA output is an ROF file. The ROF file must be processed by
the linker to produce an executable 0S9 memory module. The
layout of the ROF file is described later.
RMA has a number of new directives to control the placement of
code and data in the executable module. Since RMA does not
produce memory modules, the MIA directives "mod" and "emod" are
not present, Instead, new directives PSECT and VSECT control
the allocation of code and data areas by the linker.
RMA has no equivalent to the MIA "setdp" directive. Data (and
DP) allocation is handled by the linker.
Page D-1
MICROWARE C COMPILER USER'S GUIDE
APPENDIX D
Symbolic Names.
A symbolic name is valid if it consists of from one to nine
uppercase or lowercase characters, decimal digits or the characters
ngn, mn, MM or MEN, RMA does not fold lowercase letters to
uppercase, The names "Hi.you" and "HI, YOU" are distinct names.
Label field.
If a symbolic name in the label field of a source statement is
followed by a ":" (colon), the name will be known GLOBALLY (by all
modules linked together), If no colon appears, the name will be
known only in the PSECT in which it was defined, PSECT will be
described later.
Undefined names.
If a symbolic name is used in an expression and hasn't been defined,
RMA assumes the name is external to the PSECT. RMA will record
information about the reference so the linker can adjust the operand
accordingly. External names cannot appear in operand expressions
for assembler directives.
Listing format,
00098 0032 59 + rolb
00117 0045=17ffb8 label lbsr _ dmove Comment
| Start of comment
Start of operand
Start of mnemonic
Start of label
A "+" indicates a line generated by a macro
expansion.
¡Start of object code bytes.
An "=" here indicates that the operand contains an
external reference.
Location counter value,
ine number.
= оное Тс окне ок Rn
tr —— нон нон кн ны =
—— = ===
|
|
|
|
|
i
|
|
|
|
L
Section location counters.
Each section contains the following location counters:
PSECT - instruction location counter
VSECT - initialized direct page location counter
non-initialized direct page location counter
initialized data location counter
non-initialized data location counter
CSECT - base offset counter
Section directives.
RMA contains 3 section directives. PSECT indicates to the linker
the beginning of a relocatable-object-format file(ROF) and
Page D-2
MICROWARE C COMPILER USER'S GUIDE
APPENDIX D
initializes the instruction and data location counters and assembles
code into the ROF object code area. VSECT causes RMA to change to
the data location counters and place any generated code into the
appropriate ROF data area, CSECT initializes a base value for
assigning offsets to symbols. The end of these sections is
indicated by the ENDSECT directive.
The source statements placed in a particular section cause the
linker to perform a function appropriate for the statement.
Therefore, the mnemonics allowed within a section are restricted as
follows:
These mnemonics are allowed inside or outside any section: nam,
opt, ttl, pag, spe, use, fail, rept, endr, ifeq, ifne, iflt,
ifle, 1ifge, ifgt, ifp1, ende, else, equ, set, macro, endm,
csect, and endsect.
Within a CSECT: rmb.
Within a PSECT: any 6809 instruction mnemonic, fec, fdb, fes,
feb, rzb, vsect, endsect, 059 and end.
Within a VSECT: rmb, fee, fdb, fes, feb, rzb and endsect.
PSECT directive.
The main difference between PSECT and MOD is that MOD set up
information for 05-9 and PSECT sets up information for the
linker(c.link in the C compiler).
PSECT (name, typelang,attrrev,edition,stacksize,entrypoint)
name Up to 20 bytes (any printable character except space
or comma) for a name to be used by the linker to
identify this PSECT. This name need not be distinct
from all other PSECTs linked together, but it helps
to identify PSECTs the linker has a problem with if
the names are different.
typelang byte expression for the executable module type/lang-
uage byte. If this PSECT 15 not a "mainline"(a
module that has been designed to be forked to) mod-
ule this byte must be zero.
attrrev byte expression for executable module attribute/rev-
ision byte.
edition byte expression for executable module edition byte.
stacksize word expression estimating the amount of stack stor-
age required by this psect. The linker totals this
value in all PSECTs to appear in the executable mod-
ule and adds this value to any data storage require-
ment for the entire program.
Page D-3
MICROWARE C COMPILER USER'S GUIDE
APPENDIX D
entrypoint word expression entrypoint offset for this PSECT.
If the PSECT is not a mainline module, this should
be set to zero.
PSECT must have either no operand list or an operand list containing
a name and five expressions. If no operand list is provided, the
PSECT name defaults to "program" and all other expressions to zero.
There can only be one PSECT per assembly language file.
The PSECT directive initializes all counter orgs and marks the start
of the program module. No VSECT data reservations or object code
may appear before or after the PSECT/ENDSECT block.
Example:
psect myprog, Prgrm+0bjct,Reent+1,Edit,0,progent
psect another _prog,0,0,0,0,0
VSECT directive.
VSECT {DP}
The VSECT directive causes RMA to change to the data location
counters. If DP appears after VSECT, the direct page counters are
used, otherwise the non-direct page data is used. The RMB directive
within this section reserves the specified number of bytes in the
appropriate uninitialized data section. The fecc, fdb, fes, fob and
rzb (reserve zeroed bytes) directives place data into the
appropriate initialized data section. If an operand for fdb or feb
contains an external reference, this information is placed in the
external reference part of the ROF to be adjusted at link or
execution time. ENDSECT marks the end of the VSECT block. Any
number of VSECT blocks can appear within a PSECT. Note, however,
that the data location counters maintain their values between one
VSECT block and the next. Since the linker handles the actual data
allocation, there is no facility provided to adjust the data
location counters.
CSECT directive.
CSECT {expression}
The CSECT directive provides a means for assigning consecutive
offsets to labels without resorting to EQUs, If the expression is
present, the CSECT base counter is set to that value, otherwise it
is set to zero.
RZB statement.
Syntax: RZB <expression>
The reserve zeroed bytes pseudo-instruction generates sequences of
zero bytes in the code or initialized data sections, the number of
Page D-4
MICROWARE C COMPILER USER'S GUIDE
APPENDIX D
which is specified by the expression.
COMPARISON BETWEEN ASSEMBLY PROGRAMS FOR THE MICROWARE INTERACTIVE
ASSEMBLER AND THE RELOCATING MACRO ASSEMBLER
The following two program examples simply fork BASIC09. The purpose
of the examples are to show some of the differences in the new
relocating assembler.
* this program forks basic09
ifp1
use ..../defs/os9defs.a
ende
PRGRM equ $10
OBJCT equ $01
stk equ 200
psect rmatest, $11,$81,0,stk, entry
name fes /basic09/
prm feb $D
prmsize equ *-prm
entry leax name, per
leau prm,per
ldy #prmsize
lda #PRGRM+0OBJCT
clrb
0s9 F$FORK
089 FS$WAIT
os9 F$EXIT
endsect
MACRO INTERACTIVE ASSEMBLER SOURCE
ifp1
use defsfile
ende
mod siz,prnam,type,revs,start,size
prnam fes /testshell/
type set prgrm+objct
revs set reent+1
rmb 250
rmb 200
name fes /basic09/
prm $D
prmsize equ *-prm (continued)
Page D-5
The differences are apparent.
size
start
Siz
MICROWARE C COMPILER USER'S GUIDE
APPERDIX D
equ
equ *
leax name, per
leau prm,per
ldy #prmsize
lda #PRGRM+OBJCT
clrb
os9 F$FORK
о59 F$WAIT
os9 F$EXIT
emod
equ
Page D-6
MICROWARE C COMPILER USER'S GUIDE
APPENDIX D
MACROS
Sometimes identical or similar sequences of instructions may be
repeated in different places in a program. The problem is that if
the sequence of instructions is long or must be used a number of
times, writing it repeatedly can be tedious.
A macro is a definition of an instruction seguence that can be
used numerous places within a program, The macro is given a name
which is used similarly to any other instruction mnemonic. Whenever
RMA encounters the name of a macro in the instruction field, it
outputs all the instructions given in the macro definition. In
effect, macros allow the programmer to create "new" machine language
instructions.
For example, suppose a program frequently must perform 16 bit
left shifts of the D register. The two instruction sequence can be
defined as a macro, for example:
dasl macro
aslb
rola
endm
The "macro" and "endm" directives specify the beginning and the
end of the macro definition, respectively. The label of the "macro"
directive specifies the name of the macro, "dasl" in this example.
Now the "new" instruction can be used in the program:
ldd 12,s get operand
dasl double it
std 12,s save operand
In the example above, when ВМА encountered the "dasl" macro, it
actually outputted code for m"aslb™ and "rola", Normally, only the
macro name is listed as above, but an RMA option can be used to
cause all instructions of the "macro expansion" to be listed.
Macros should not be confused with subroutines although they
are similar in some ways. Macros repetitively duplicate an "in
line" code sequence every time they are used and allow some
alteration of the instruction operands. Subroutines appear exactly
once, never change, and are called using special instructions (BSR,
JSR, and RTS). In those cases where they can be used
interchangeably, macros usually produce longer but slightly faster
programs, and subroutines produce shorter and slightly slower
programs. Short macros (up to 6 bytes or so) will almost always be
faster and shorter than subroutines because of the overhead of the
BSR and RTS instructions needed.
D-7
MICROWARE C COMPILER USER'S GUIDE
APPENDIX D
MACRO STRUCTURE
A macro definition consists of three sections:
The macro header - assigns a name to the macro
. The body - contains the macro statements
3. The terminator =- indicates the end of the macro
N) —
<name> MACRO /* macro header */
body /* macro body */
ENDM /* macro terminator */
The macro name must be defined by the label given in the MACRO
statement. The name can be any legal assembler label. It is
possible to redefine the 6809 instructions (LDA, CLR, ete.)
themselves by defining macros having identical names. Caution:
redefinition of assembler directives such as "RMB" can have
unpredictable consequences.
The body of the macro can contain any number of legal RMA
instruction or directive statements including references to
previously defined macros, The last statement of a macro definition
must be ENDM.
The text of macro definitions are stored on a temporary file
that is created and maintained by RMA. This file has a large (1K
byte) buffer to minimize disk accesses. Therefore, programs that
use more than 1K of macro storage space should be arranged so that
short, frequently used macros are defined first so they are kept in
the memory buffer instead of disk space.
Macro calls may be nested, that is, the body of a macro
definition may contain a call to another macro. For example:
times4 MACRO
dasl
dasl
ENDM
The macro above consists of the "dasl” macro used twice. The
definition of a new macro within another is not permitted. Macro
calls may be nested up to eight deep.
D-8
MICROWARE C COMPILER USER'S GUIDE
APPENDIX D
MACRO ARGUMENTS
Arguments permit variations in the expansion of a macro,
Arguments can be used to specify operands, register names,
constants, variables, etc., in each occurence of a macro,
A macro can have up to nine formal arguments in the operand
fields. Each argument consists of a backslash character and the
sequence number of the formal argument, e.g, \1, \2 ... \9. When
the macro is expanded, each formal argument is replaced by the
corresponding text string "actual argument" given in the macro call.
Arguments can be used in any part of the operand field not in the
instruction or label fields. Formal arguments can be used in any
order and any number of times.
For example, the macro below performs the typical instruction
sequence to create an 0S-9 file:
create MACRO
leax \1,per get addr of file name string
lda #\2 set path number
1db #\3 set file access modes
089 I$CREATE
ENDM
This macro uses three arguments: "\1" for the file name string
address; "\2" for the path number; and "\3" for the file access mode
code. When "create" is referenced, each argument is replaced by the
corresponding string given in the macro call, for example:
create outname,2,$1E
The macro call above will be expanded to the code sequence:
leax outname, pcr
lda #22
1db #$1E
os9 I$CREATE
If an argument string includes special characters such as
backslashes or commas, the string must be enclosed in double quotes,
For example, this macro reference has two arguments:
double count,"2,s"
An argument may be declared null by omitting all or some
arguments in the macro call to make the corresponding argument an
empty string so no substitution occurs when it is referenced.
MICROWARE C COMPILER USER'S GUIDE
APPENDIX D
There are two special argument operators that can be useful in
constructing more complex macros. They are:
\Ln - Returns the length of the actual
argument n, in bytes.
\# - Returns the number of actual arguments
passed in a given macro call.
These special operators are most commonly used in conjunction with
RMA's conditional assembly facilities to test the validity of
arguments used in a macro call, or to change the way a macro works
according to the actual arguments used. When macros are performing
error checking they can report errors using the FAIL directive.
Here is an example using the "create" macro given on the previous
page but expanded for error checking:
create MACRO
ifne \# - 3 must have exactly 3 args
FAIL create: must have three arguments
endc
ifgt \L1 - 29 file name can be 1 - 29 chars
FAIL create: file name too long
ende
leax \1,per get addr of file name string
lda #\2 set path number
ldb #\3 set file access modes
os9 I$CREATE
ENDM
MICROWARE C COMPILER USER'S GUIDE
APPENDIX D
MACRO AUTOMATIC INTERNAL LABELS
Sometimes it is necessary to use labels within a macro. Labels
are specified by "ve", Each time the macro is called, a unique
label will be generated to avoid multiple definition errors. Within
the expanded code "\@" will take on the form "@xxx", where xxx will
be a decimal number between 000 to 999.
More than one label may be specified in a macro by the addition
of an extra character(s). For example, if two different labels are
required in a macro, they can be specified by "\@A" and "\€B". In
the first expansion of the macro, the labels would be "@001A" and
"@001B", and in the second expansion they would be "е002А" апа
"002B", The extra characters may be appended before the "\" or
after the "e",
Here is an example of macro that uses internal labels:
testovr MACRO
cmpd E compare to arg
bls \ ВА bra if in range
orce #1 set carry bit
bra \êB and skip next instr.
\eA andec #$FE clear carry
\eB equ * continue...
Suppose the first macro call is:
testovr $80
The expansion will be:
стра # $80 compare to arg
bls €0014A bra if in range
orec #1 set carry bit
bra 8001B and skip next instr.
@001A апасс #$FE clear carry
8001B equ * continue...
If the second macro call is:
testovr 240
The expansion will be:
стра #240 compare to arg
bls 80024 bra if in range
orcc #1 set carry bit
bra @002B and skip next instr.
8002A andec #$FE clear carry
@002B equ * continue...
MICROWARE C COMPILER USER'S GUIDE
APPENDIX D
ADDITIONAL COMMENTS ABOUT MACROS
Macros can be an important and useful programming tool that can
significantly extend RMA's capabilities. In addition to creating
instruction sequences, they can also be used to create complex
constant tables and data structures,
Macros can also be dangerous in the sense that if they are used
indiscriminately and unnecessarily they can impair the readability
of a program and make it difficult for programmers other than the
original author to understand the program logic. Therefore, when
macros are used they should be carefully documented.
MICROWARE C COMPILER USER'S GUIDE
INDEX
abort 3-2 getchar 4-11 qsort N= 21
abs 3-3 getime 3=35 read 3-32
access 3-4 getpid 3-15 readln 3-32
atof 4-3 gets 4-13 rewind 4-10
atoi 4-3 getstat 3-16 rindex 4-30
atol 4-3 getuid 3-18 sbrk 3-33
calloc 4-17 getw 4-11 scanf 4-25
chain 3-5 ibrk 3-33 setbuff 4.27
chdir 3-6 index 4-30 setime 3-35
chmod 3-7 intercept 3-19 set jmp 4-16
chown 3-8 isalnum 4-14 setpr 3-34
chxdir 3-6 isalpha 4-14 setstat 3-37
clearerr 4-5 isascii 4-14 setuid 3-36
close 3-9 isentrl 4-14 signal 3-38
ere 3-10 isdigit 4-14 sleep 4-28
creat 3-11 islower 4-14 sprintf 4-19
defdrive 3-12 isprint 4-14 sscanf 4-25
dup 3-13 ispunct 4-14 stacksize 3-39
exit 3-14 isspace 4-14 strcat 4-29
fclose 4 — | isupper 4-14 strcmp 4-29
fdopen Y=7 kill 3-21 strepy 4-30
feof 4-5 13tol 4-15 strhepy 4-30
ferror 4-5 longjmp 4-16 strlen 4-30
fflush 4-1 lseek 3-22 strncat 4-29
fgets 4-13 ltol3 4-15 strnepy 4-30
fileno 4-5 malloc 4-17 system 4-31
findnstr 4-6 mknod 3-23 toascii 4-32
findstr 4-6 mktemp 4-18 tolower 4-32
fopen 4-7 modlink 3-24 toupper 4-32
fprintf 4-19 modload 3-24 tsleep 3-42
fputs 4-23 munlink 3-25 ungete 4-32
fread 4-9 open 3-28 unlink 3-43
free 4-17 os9fork 3-29 wait 3-41
freemem 3-40 pause 3-30 write 3-45
freopen 4-7 prerr 3-31 writeln 3-45
fscanf 4-25 printf 4-19 exit 3-13
fseek 4-10 pute 4-22 _0s9 3-25
ftell 4-10 putchar 4-22 _strass 4-41
fwrite 4-9 puts 4-23 _tolower 4-32
getc 4-11 putw 4-22 _toupper 4-32
INDEX-1
">