mirror of https://github.com/wwarthen/RomWBW.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
11351 lines
296 KiB
11351 lines
296 KiB
|
|
HI-TECH C USER'S MANUAL i
|
|
|
|
CONTENTS
|
|
|
|
|
|
|
|
1. Introduction 1
|
|
1.1. Features 1
|
|
1.2. System Requirements 2
|
|
1.3. Using this Manual 2
|
|
|
|
2. Getting Started 3
|
|
|
|
3. Compiler Structure 5
|
|
|
|
4. Operating Details 7
|
|
|
|
5. Specific Features 13
|
|
5.1. ANSI C Standard Compatibility 13
|
|
5.2. Type Checking 13
|
|
5.3. Member Names 13
|
|
5.4. Unsigned Types 14
|
|
5.5. Arithmetic Operations 14
|
|
5.6. Structure Operations 15
|
|
5.7. Enumerated Types 16
|
|
5.8. Initialization Syntax 16
|
|
5.9. Function Prototypes 17
|
|
5.10. Void and Pointer to Void 18
|
|
5.11. Type qualifiers 19
|
|
5.12. 20
|
|
5.13. Pragma Directives 20
|
|
|
|
6. Machine Dependencies 21
|
|
6.1. Predefined Macros 21
|
|
|
|
7. Error Checking and Reporting 23
|
|
|
|
8. Standard Libraries 25
|
|
8.1. Standard I/O 25
|
|
8.2. Compatibility 25
|
|
8.3. Libraries for Embedded Systems 25
|
|
8.4. Binary I/O 26
|
|
8.5. Floating Point Library 27
|
|
|
|
9. Stylistic Considerations 29
|
|
9.1. Member Names 29
|
|
9.2. Use of Int 30
|
|
9.3. Extern Declarations 30
|
|
|
|
10. Memory Models 31
|
|
|
|
11. What Went Wrong 33
|
|
|
|
12. Z80 Assembler Reference Manual 35
|
|
12.1. Introduction 35
|
|
12.2. Usage 35
|
|
12.3. The Assembly Language 36
|
|
12.3.1. Symbols 36
|
|
12.3.1.1. Temporary Labels 37
|
|
12.3.2. Constants 37
|
|
12.3.2.1. Character Constants 38
|
|
|
|
|
|
|
|
|
|
|
|
ii HI-TECH C USER'S MANUAL
|
|
|
|
12.3.2.2. Floating Constants 38
|
|
12.3.2.3. Opcode Constants 38
|
|
12.3.3. Expressions 38
|
|
12.3.3.1. Operators 38
|
|
12.3.3.2. Relocatability 39
|
|
12.3.4. Pseudo-ops 40
|
|
12.3.4.1. DEFB, DB 40
|
|
12.3.4.2. DEFF 41
|
|
12.3.4.3. DEFW 41
|
|
12.3.4.4. DEFS 41
|
|
12.3.4.5. EQU 41
|
|
12.3.4.6. DEFL 41
|
|
12.3.4.7. DEFM 42
|
|
12.3.4.8. END 42
|
|
12.3.4.9. COND, IF, ELSE, ENDC 42
|
|
12.3.4.10. ELSE 42
|
|
12.3.4.11. ENDC 42
|
|
12.3.4.12. ENDM 43
|
|
12.3.4.13. PSECT 43
|
|
12.3.4.14. GLOBAL 43
|
|
12.3.4.15. ORG 44
|
|
12.3.4.16. MACRO 44
|
|
12.3.4.17. LOCAL 45
|
|
12.3.4.18. REPT 46
|
|
12.3.5. IRP and IRPC 47
|
|
12.3.6. Extended Condition Codes 48
|
|
12.4. Assembler Directives 48
|
|
12.5. Diagnostics 49
|
|
12.6. Z80/Z180/64180 Instruction Set 50
|
|
|
|
13. Linker Reference Manual 69
|
|
13.1. Relocation and Psects 69
|
|
13.1.1. Program Sections 69
|
|
13.1.2. Local Psects and the Large Model 70
|
|
13.2. Global Symbols 70
|
|
13.3. Operation 71
|
|
13.4. Examples 74
|
|
13.5. Invoking the Linker 74
|
|
|
|
14. Librarian 75
|
|
14.1. The Library Format 75
|
|
14.2. Using 75
|
|
14.3. Examples 76
|
|
14.4. Supplying Arguments 77
|
|
14.5. Listing Format 77
|
|
14.6. Ordering of Libraries 77
|
|
14.7. Error Messages 78
|
|
|
|
15. Objtohex 79
|
|
|
|
16. Cref 83
|
|
APPENDIX 1 Error Messages 85
|
|
|
|
APPENDIX 2 Standard Library Functions 99
|
|
|
|
|
|
INDEX 165
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C COMPILER
|
|
|
|
User's Manual
|
|
|
|
March 1989
|
|
|
|
|
|
|
|
|
|
1. Introduction
|
|
|
|
|
|
The HI-TECH C Compiler is a set of software which
|
|
translates programs written in the C language to executable
|
|
machine code programs. Versions are available which compile
|
|
programs for operation under the host operating system, or
|
|
which produce programs for execution in embedded systems
|
|
without an operating system.
|
|
|
|
1.1. Features
|
|
|
|
Some of HI-TECH C's features are:
|
|
|
|
A single command will compile, assemble and link entire
|
|
programs.
|
|
|
|
The compiler performs strong type checking and issues
|
|
warnings about various constructs which may represent
|
|
programming errors.
|
|
|
|
The generated code is extremely small and fast in exe-
|
|
cution.
|
|
|
|
A full run-time library is provided implementing all
|
|
standard C input/output and other functions.
|
|
|
|
The source code for all run-time routines is provided.
|
|
|
|
A powerful general purpose macro assembler is included.
|
|
|
|
Programs may be generated to execute under the host
|
|
operating system, or customized for installation in
|
|
ROM.
|
|
|
|
PC-DOS/MS-DOS
|
|
CP/M-86
|
|
Concurrent DOS
|
|
Atari ST
|
|
Xenix
|
|
Unix
|
|
CP/M-80
|
|
|
|
|
|
Table 1. Supported Hosts
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 2 HI-TECH C USER'S MANUAL
|
|
|
|
1.2. System Requirements
|
|
|
|
The HI-TECH C Compilers operate under the operating
|
|
sytems listed in table 1. Ensure that the version of the
|
|
compiler you have matches the system you have. Note that in
|
|
general you must have a hard disk or two floppy disks on
|
|
your system (it is possible to use one floppy disk of 800K
|
|
or more). A hard disk is strongly recommended. Note that
|
|
the CP/M-80 native compiler does not have all the features
|
|
described in this manual, as it has not been upgraded past
|
|
V3.09 due to memory limitations. The Z80 cross compiler
|
|
does support all of the features described here and can be
|
|
used to generate programs to execute under CP/M-80.
|
|
|
|
1.3. Using this Manual
|
|
|
|
The documentation supplied with the HI-TECH C compiler
|
|
comprises two separate manuals within the one binder. The
|
|
manual you are reading now covers all versions of the com-
|
|
piler (reflecting the portable nature of the compiler). A
|
|
separate manual covers machine dependent aspects of your
|
|
compiler, e.g. installation.
|
|
|
|
This manual assumes you are familiar with the C
|
|
language already. If you are not, you should have at least
|
|
one reference book covering C, of which a large number are
|
|
available from most computer bookstores, e.g. "A Book on C"
|
|
by Kelley and Pohl. Other suitable texts are "Programming in
|
|
ANSI C" by S. Kochan and "The C Programming Language", by
|
|
Kernighan and Ritchie. You should read the "Getting Started"
|
|
chapter in this manual, and the "Installation" chapter in
|
|
the machine-specific manual. This will provide you with
|
|
sufficient information to work through the introductory
|
|
examples in the C reference you are using.
|
|
|
|
Once you have a basic grasp of the C language, the
|
|
remainder of this manual will provide you with information
|
|
to enable you to explore the more advanced aspects of C.
|
|
|
|
Most of the manual covers all implementations of the
|
|
HI-TECH C compiler. A separate manual is provided for the
|
|
macro assembler for your particular machine, and other
|
|
machine-dependent information.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 3
|
|
|
|
|
|
2. Getting Started
|
|
|
|
|
|
If using the compiler on a hard disk system you will
|
|
need to install the compiler before using it. See the
|
|
"Installation" chapter for more details. If using a floppy
|
|
disk based system, in general you should have a copy of the
|
|
distribution disk #1 in drive A: and maintain your files on
|
|
a disk in the B: drive. Again see the "Installation" chapter
|
|
for more information.
|
|
|
|
main()
|
|
{
|
|
printf("Hello, world\n");
|
|
}
|
|
|
|
|
|
Fig. 1. Sample C Program
|
|
|
|
|
|
Before compiling your program it must be contained in a
|
|
file with an extension (or file type, i.e. that part of the
|
|
name after the '.') of .C. For example you may type the
|
|
program shown in fig. 1 into a file called HELLO.C. You will
|
|
need a text editor to do this. Generally any text editor
|
|
that can create a straight ASCII file (i.e. not a "word pro-
|
|
cessor" type file) will be suitable. If using editors such
|
|
as Wordstar, you should use the "non-document mode". Once
|
|
you have the program in such a file all that is required to
|
|
compile it is to issue the C command, e.g. to compile
|
|
HELLO.C simply type the command
|
|
|
|
C -V HELLO.C
|
|
|
|
Cross compilers (i.e. compilers that operate on one system
|
|
but produce code for a separate target system) will have a
|
|
compiler driver named slightly differently, e.g. the 68HC11
|
|
cross compiler driver is called C68.
|
|
|
|
If you are using a floppy disk based system (or a CP/M
|
|
system) it may be necessary to specify where to find the C
|
|
command, e.g. if the C command is on a disk in drive A: and
|
|
you are working on B:, type the command
|
|
|
|
A:C -V HELLO.C
|
|
|
|
|
|
The compiler will issue a sign on message, then proceed
|
|
to execute the various passes of the compiler in sequence to
|
|
compile the program. If you are using a floppy disk based
|
|
system where the compiler will not fit on a single disk you
|
|
will be prompted to change disks whenever the compiler can-
|
|
not find a pass. In this case you should insert a copy of
|
|
the next distribution disk in drive A: and press RETURN.
|
|
|
|
As each pass of the compiler is about to be executed, a
|
|
command line to that pass will be displayed on the screen.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 4 HI-TECH C USER'S MANUAL
|
|
|
|
This is because the -V option has been used. This stands for
|
|
Verbose, and had it not been given the compilation would
|
|
have been silent except for the sign on message. Error mes-
|
|
sages can be redirected to a file by using the standard out-
|
|
put redirection notation, e.g. > _s_o_m_e_f_i_l_e.
|
|
|
|
After completion of compilation, the compiler will exit
|
|
to command level. You will notice that several temporary
|
|
files created during compilation will have been deleted, and
|
|
all that will be left on the disk (apart from the original
|
|
source file HELLO.C) will be an executable file. The name of
|
|
this executable file will be HELLO.EXE for MS-DOS, HELLO.PRG
|
|
for the Atari ST, HELLO.COM for CP/M-80 and HELLO.CMD for
|
|
CP/M-86. For cross compilers it will be called HELLO.HEX or
|
|
HELLO.BIN depending on the default output format for the
|
|
particular compiler. To execute this program, simply type
|
|
|
|
HELLO
|
|
|
|
and you should be rewarded with the message "Hello, world!"
|
|
on your screen. If you are using a cross compiler you will
|
|
need to put the program into EPROM or download to the target
|
|
system to execute it. Cross compilers do not produce pro-
|
|
grams executable on the host system.
|
|
|
|
There are other options that may be used with the C
|
|
command, but you will not need to use them unless you wish
|
|
to do so. If you are new to the C language it will be advis-
|
|
able to enter and compile a few simple programs (e.g. drawn
|
|
from one of the C reference texts mentioned above) before
|
|
exploring other capabilities of the HI-TECH C compiler.
|
|
|
|
There is one exception to the above; if you compile a
|
|
program which uses floating point arithmetic (i.e. real
|
|
numbers) you MUST specify to the compiler that the floating
|
|
point library should be searched. This is done with a -LF
|
|
option at the END of the command line, e.g.
|
|
|
|
C -V FLOAT.C -LF
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 5
|
|
|
|
|
|
3. Compiler Structure
|
|
|
|
|
|
The compiler is made up of several passes; each pass is
|
|
implemented as a separate program. Note that it is not
|
|
necessary for the user to invoke each pass individually, as
|
|
the C command runs each pass automatically. Note that the
|
|
machine dependent passes are named differently for each pro-
|
|
cessor, for example those with 86 in their name are for the
|
|
8086 and those with 68K in their name are for the 68000.
|
|
|
|
The passes are:
|
|
|
|
CPP The pre-processor - handles macros and conditional com-
|
|
pilation
|
|
|
|
P1 The syntax and semantic analysis pass. This writes
|
|
intermediate code for the code generator to read.
|
|
|
|
CGEN, CG86 etc.
|
|
The code generator - produces assembler code.
|
|
|
|
OPTIM, OPT86 etc.
|
|
The code improver - may optionally be omitted, reducing
|
|
compilation time at a cost of larger, slower code pro-
|
|
duced.
|
|
|
|
ZAS, AS86 etc.
|
|
The assembler - in fact a general purpose macro assem-
|
|
bler.
|
|
|
|
LINK
|
|
The link editor - links object files with libraries.
|
|
|
|
OBJTOHEX
|
|
This utility converts the output of LINK into the
|
|
appropriate executable file format (e.g. .EXE or .PRG
|
|
or .HEX).
|
|
|
|
The passes are invoked in the order given. Each pass
|
|
reads a file and writes a file for its successor to read.
|
|
Each intermediate file has a particular format; CPP produces
|
|
C code without the macro definitions and with uses of macros
|
|
expanded; P1 writes a file containing a program in an inter-
|
|
mediate code; CGEN translates this to assembly code; AS pro-
|
|
duces object code, a binary format containing code bytes
|
|
along with relocation and symbol information. LINK accepts
|
|
object files and libraries of object files and writes
|
|
another object file; this may be in absolute form or it may
|
|
preserve relocation information and be input to another LINK
|
|
command.
|
|
|
|
There are also other utility programs:
|
|
|
|
LIBR
|
|
Creates and maintains libraries of object modules
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 6 HI-TECH C USER'S MANUAL
|
|
|
|
CREF
|
|
Produces cross-reference listings of C or assembler
|
|
programs.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 7
|
|
|
|
|
|
4. Operating Details
|
|
|
|
|
|
HI-TECH C was designed for ease of use; a single com-
|
|
mand will compile, assemble and link a C program. The syntax
|
|
of the C command is as follows:
|
|
|
|
C [ options ] files [ libraries ]
|
|
|
|
The options are zero or more options, each consisting
|
|
of a dash ('-'), a single key letter, and possibly an argu-
|
|
ment following the key letter with no intervening space. The
|
|
files are one or more C source files, assembler source
|
|
files, or object files. Libraries may be zero or more
|
|
library names, or the abbreviated form -lname which will be
|
|
expanded to the library name libname.lib.
|
|
|
|
The C command will, as determined by the specified
|
|
options, compile any C source files given, assemble them
|
|
into object code unless requested otherwise, assemble any
|
|
assembler source files specified, then link the results of
|
|
the assemblies with any object or library files specified.
|
|
|
|
If the C command is invoked without arguments, then it
|
|
will prompt for a command line to be entered. This command
|
|
line may be extended by typing a backslash ('\') on the end
|
|
of the line. Another line will then be requested. If the
|
|
standard input of the command is from a file (e.g. by typing
|
|
C < afile) then the command lines will be read from that
|
|
file. Within the file more than one line may be given if
|
|
each line but the last ends with a backslash. Note that this
|
|
mechanism does not work in MS-DOS batch file, i.e. the com-
|
|
mand file for the C command must be a separate file. MS-DOS
|
|
has no mechanism for providing long command lines or stan-
|
|
dard input from inside a batch file.
|
|
|
|
The options recognized by the C command are as follows:
|
|
|
|
-S Leave the results of compilation of any C files as
|
|
assembler output. C source code will be interspersed as
|
|
comments in the assembler code.
|
|
|
|
-C Leave the results of all compiles and assemblies as
|
|
object files; do not invoke the linker. This allows the
|
|
linker to be invoked separately, or via the C command
|
|
at a later stage.
|
|
|
|
-CR Produce a cross reference listing. -CR on its own will
|
|
leave the raw cross-reference information in a tem-
|
|
porary file, allowing the user to run CREF explicitly,
|
|
while supplying a file name, e.g. -CR_F_R_E_D._C_R_F will
|
|
cause CREF to be invoked to process the raw information
|
|
into the specified file, in this case _F_R_E_D._C_R_F.
|
|
|
|
-CPM
|
|
For the Z80 cross compiler only, produce CP/M-80 COM
|
|
files. Unless the -CPM option is given, the Z80 cross
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 8 HI-TECH C USER'S MANUAL
|
|
|
|
compiler uses the ROM runtime startoff module and pro-
|
|
duces hex or binary images. If the -CPM option is
|
|
given, CP/M-80 runtime startoff code is linked used and
|
|
a CP/M-80 COM file is produced.
|
|
|
|
-O Invoke the optimizer on all compiled code; also
|
|
requests the assembler to perform jump optimization.
|
|
|
|
-O_O_U_T_F_I_L_E
|
|
Specify a name for the executable file to be created.
|
|
By default the name for the executable file is derived
|
|
from the name of the first source or object file speci-
|
|
fied to the compiler. This option allows the default to
|
|
be overridden. If no dot ('.') appears in the given
|
|
file name, an extension appropriate for the particular
|
|
operating system will be added, e.g. -O_F_R_E_D will gen-
|
|
erate a file _F_R_E_D._E_X_E on MS-DOS or _F_R_E_D._C_M_D on CP/M-86.
|
|
For cross compilers this also provides a means for
|
|
specifying the output format, e.g. specifying an output
|
|
file _P_R_O_G._B_I_N will make the compiler generate a binary
|
|
file, while specifying _P_R_O_G._H_E_X will make it generate a
|
|
hexadecimal file.
|
|
|
|
-V Verbose: each step of the compilation will be echoed as
|
|
it is executed.
|
|
|
|
-I Specify an additional filename prefix to use in search-
|
|
ing for #include files. For CP/M the default prefix is
|
|
0:A: (user number 0, disk drive A). For MS-DOS the
|
|
default prefix is A:\HITECH\. Under Unix and Xenix the
|
|
default prefix is /usr/hitech/include/. Note that on
|
|
MS-DOS a trailing backslash must be appended to any
|
|
directory name given as an argument to -I; e.g.
|
|
-I\FRED\ not -I\FRED. Under Unix a trailing slash
|
|
should be added.
|
|
|
|
-D Define a symbol to the preprocessor: e.g. -DCPM will
|
|
define the symbol CPM as though via #define CPM 1.
|
|
|
|
-U Undefine a pre-defined symbol. The complement of -D.
|
|
|
|
-F Request the linker to produce a symbol file, for use
|
|
with the debugger.
|
|
|
|
-R For the Z80 CP/M compiler only this option will link in
|
|
code to perform command line I/O redirection and wild
|
|
card expansion in file names. See the description of
|
|
_getargs() in appendix 5 for details of the syntax of
|
|
the redirections.
|
|
|
|
-X Strip local symbols from any files compiled, assembled
|
|
or linked. Only global symbols will remain.
|
|
|
|
-M Request the linker to produce a link map.
|
|
|
|
-A This option, for the Z80 only, will cause the compiler
|
|
to produce an executable program that will, on execu-
|
|
tion, self-relocate itself to the top of the TPA
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 9
|
|
|
|
(Transient Program Area). This allows the writing of
|
|
programs which may execute other programs under them-
|
|
selves. Note that a program compiled in such a manner
|
|
will not automatically reset the bdos address at loca-
|
|
tion 6 in order to protect itself. This must be done by
|
|
the program itself.
|
|
|
|
For cross compilers this provides a way of specifying
|
|
to the linker the addresses that the compiled program
|
|
is to be linked at. The format of the option is
|
|
-A_R_O_M_A_D_R,_R_A_M_A_D_R,_R_A_M_S_I_Z_E. _R_O_M_A_D_R is the address of the
|
|
ROM in the system, and is where the executable code and
|
|
initialized data will be placed. _R_A_M_A_D_R is the start
|
|
address of RAM, and is where the bss psect will be
|
|
placed, i.e. uninitialized data. _R_A_M_S_I_Z_E is the size
|
|
of RAM available to the program, and is used to set the
|
|
top of the stack.
|
|
|
|
For the 6801/6301/68HC11 compiler, the -A option takes
|
|
a fourth value which is the address of a four byte
|
|
direct page area called ctemp which the compiled code
|
|
uses as a scratch pad. If the ctemp address is omitted
|
|
from the -A option, it defaults to address 0. Normally
|
|
this will be acceptable, however some 6801 variants
|
|
(like the 6303) have memory mapped I/O ports at address
|
|
0 and start their direct page RAM at address $80.
|
|
|
|
For the large memory model of the 8051 compiler, the -A
|
|
option takes the form -A_R_O_M_A_D_R,_I_N_T_R_A_M,_E_X_T_R_A_M,_E_X_T_S_I_Z_E.
|
|
_R_O_M_A_D_R is the address of ROM in the system. _I_N_T_R_A_M is
|
|
the start address of internal RAM, and is where the
|
|
rbss psect will be placed. The 8051 internal stack
|
|
will start after the end of the rbss psect. _E_X_T_R_A_M is
|
|
the start address of external RAM, and is where the bss
|
|
psect will be placed. _E_X_T_S_I_Z_E is the size of external
|
|
RAM available to the program, and is used to set the
|
|
top of the external stack.
|
|
|
|
-B For compilers which support more than one "memory
|
|
model", this option is used to select which memory
|
|
model code is to be generated for. The format of this
|
|
option is -Bx where x is one or more letters specifying
|
|
which memory model to use. For the 8086, this option
|
|
is used to select which one of five memory models
|
|
(Tiny, Small, Medium, Compact or Large) is to be used.
|
|
|
|
For the 8051 compiler this this option is used to
|
|
select which one of the three memory models (Small,
|
|
Medium or Large) is to be used. For the 8051 compiler
|
|
only, this option can also be used to select static
|
|
allocation of _a_u_t_o variables by appending an A to the
|
|
end of the -B option. For example, -Bsa would select
|
|
small model with static allocation of all variables,
|
|
while -Bm would select medium model with _a_u_t_o variables
|
|
dynamically allocated on the stack.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 10 HI-TECH C USER'S MANUAL
|
|
|
|
-E By default the 8086 compiler will initialize the exe-
|
|
cutable file header to request a 64K data segment at
|
|
run time. This may be overridden by the -E option. It
|
|
takes an argument (usually in hexadecimal representa-
|
|
tion) which is the number of BYTES (not paragraphs) to
|
|
be allocated to the program at run time. For example
|
|
-E0ffff0h will request a megabyte. Since this much will
|
|
not be available, the operating system will allocate as
|
|
much as it can.
|
|
|
|
-W This options sets the warning level, i.e. it determines
|
|
how picky the compiler is about legal but dubious type
|
|
conversions etc. -W0 will allow all warning messages
|
|
(default), -W1 will suppress the message "Func()
|
|
declared implicit int". -W3 is recommended for compil-
|
|
ing code originally written with other, less strict,
|
|
compilers. -W9 will suppress all warning messages.
|
|
|
|
-H This option generates a symbol file for use with
|
|
debuggers. The format of the symbol file is described
|
|
elsewhere. The default name of the symbol file is
|
|
_l._s_y_m. An alternate name may be specfied with the
|
|
option, e.g. -H_s_y_m_f_i_l_e._a_b_c.
|
|
|
|
-G Like -H, -G also generates a symbol file, but one that
|
|
contains line and file number information for a source
|
|
level debugger. Like -H a file name may be specified.
|
|
When used in conjunction with -O, only partial optimi-
|
|
zation will be performed to avoid confusing the
|
|
debugger.
|
|
|
|
-P Execution profiling is available on native compilers
|
|
running under DOS, CP/M-86 and on the Atari ST. This
|
|
option generates code to turn on execution profiling
|
|
when the program is run. A -H option should also be
|
|
specified to provide a symbol table for the profiler
|
|
EPROF.
|
|
|
|
-Z For version 5.xx compilers only, the -Z option is used
|
|
to select global optimization of the code generated.
|
|
For the 8086 and 6801/6301/68HC11 compilers the only
|
|
valid -Z option is -Zg. For the 8051 compiler, the
|
|
valid -Z options are -Zg which invokes global optimiza-
|
|
tion, -Zs which optimizes for space, and -Zf which
|
|
optimizes for speed. The s and f options may be used
|
|
with the g option, thus the options -Zgf and -Zgs are
|
|
valid. Speed and space optimization are mutually
|
|
exclusive, i.e. the s and f options cannot be used
|
|
together.
|
|
|
|
-1 For the 8086 compiler only, request the generation of
|
|
code which takes advantage of the extra instructions of
|
|
the 80186 processor. A program compiled with -1 will
|
|
not execute on an 8086 or 8088 processor. For the 68000
|
|
compiler, generate instructions for the 68010 proces-
|
|
sor.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 11
|
|
|
|
-2 Like -1 but for the 80286 and 68020.
|
|
|
|
-11 For the 6801/HC11 compiler, this option will request
|
|
generation of instructions specific to the 68HC11 pro-
|
|
cessor.
|
|
|
|
-6301
|
|
For the 6801/HC11 compiler, this option will request
|
|
generation of instructions specific to the 6301/6303
|
|
processors.
|
|
|
|
Some examples of the use of the C command are:
|
|
|
|
c prog.c
|
|
|
|
c -mlink.map prog.c x.obj -lx
|
|
|
|
c -S prog.c
|
|
|
|
c -O -C -CRprog.crf prog.c prog2.c
|
|
|
|
c -v -Oxfile.exe afile.obj anfile.c -lf
|
|
|
|
|
|
Upper and lower case has been used in the above exam-
|
|
ples for emphasis: the compiler does not distinguish between
|
|
cases, although arguments specifying names, e.g. -D, are
|
|
inherently case sensitive.
|
|
|
|
Taking the above examples in order; the first compiles
|
|
and links the C source file prog.c with the standard C
|
|
library. The second example will compile the file prog.c and
|
|
link it with the object file x.obj and the library libx.lib;
|
|
a link map will be written to the file link.map.
|
|
|
|
The third example compiles the file prog.c, leaving the
|
|
assembler output in a file prog.as. It does not assemble
|
|
this file or invoke the linker. The next example compiles
|
|
both prog.c and prog2.c, invoking the optimizer on both
|
|
files, but does not perform any linking. A cross reference
|
|
listing will be left in the file _p_r_o_g._c_r_f.
|
|
|
|
The last example pertains to the 8086 version of the
|
|
compiler, It runs the compiler with the verbose option, and
|
|
will cause anfile.c to be compiled without optimization to
|
|
object code, yielding anfile.obj, then afile.obj and
|
|
anfile.obj will be linked together with the floating point
|
|
library (from the -LF option) and the standard library to
|
|
yield the executable program xfile.exe (assuming this is
|
|
performed on an MS-DOS system). One would expect this pro-
|
|
gram to use floating point, if it did not then the -LF
|
|
option would have been required.
|
|
|
|
If more than one C or assembler source file is given to
|
|
the C command, the name of each file will be printed on the
|
|
console as it is processed. If any fatal errors occur dur-
|
|
ing the compilation or assembly of source files, further
|
|
source files will be processed, but the linker will not be
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 12 HI-TECH C USER'S MANUAL
|
|
|
|
invoked.
|
|
|
|
|
|
Other commands which may be issued by the user, rather
|
|
than automatically by the C command, are:
|
|
|
|
ZAS The Z80 assembler.
|
|
|
|
AS86
|
|
The 8086 assembler.
|
|
|
|
LINK
|
|
The linker
|
|
|
|
LIBR
|
|
The library maintainer
|
|
|
|
OBJTOHEX
|
|
Object to hex converter
|
|
|
|
CREF
|
|
Cross reference generator.
|
|
|
|
In general, these commands accept the same type of com-
|
|
mand line as the C command, i.e. zero or more options (indi-
|
|
cated by a leading '-') followed by one or more file argu-
|
|
ments. If the linker or the librarian is invoked with no
|
|
arguments, it wll prompt for a command line. This allows
|
|
command lines of more than 128 bytes to be entered. Input
|
|
may also be taken from a file by using the redirection capa-
|
|
blities (see _getargs() in the library function listing).
|
|
See the discussion above of the C command. These commands
|
|
are described in further detail in their respective manuals.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 13
|
|
|
|
|
|
5. Specific Features
|
|
|
|
|
|
The HI-TECH C compiler has a number of features, which
|
|
while largely compatible with other C compilers, contribute
|
|
to more reliable programming methods.
|
|
|
|
5.1. ANSI C Standard Compatibility
|
|
|
|
At the time of writing the Draft ANSI Standard for the
|
|
C Language was at an advanced stage, though not yet an offi-
|
|
cial standard. Accordingly it is not possible to claim com-
|
|
pliance with that standard, however HI-TECH C includes the
|
|
majority of the new and altered features in the draft ANSI
|
|
standard. Thus it is in the sense that most people under-
|
|
stand it "ANSI compatible".
|
|
|
|
5.2. Type Checking
|
|
|
|
Previous C compilers have adopted a lax approach to
|
|
type checking. This is typified by the Unix C compiler,
|
|
which allows almost arbritary mixing of types in expres-
|
|
sions. The HI-TECH C compiler performs much more strict type
|
|
checking, although in most cases only warning messages are
|
|
issued, allowing compilation to proceed if the user knows
|
|
that the errors are harmless. This would occur, for example,
|
|
when an integer value was assigned to a pointer variable.
|
|
The generated code would almost certainly be what the user
|
|
intended, however if in fact it represented an error in the
|
|
source code, the user is prompted to check and correct it
|
|
where necessary.
|
|
|
|
5.3. Member Names
|
|
|
|
In early C compilers member names in different struc-
|
|
tures were required to be distinct except under certain cir-
|
|
cumstances. HI-TECH C, like most recent implementations of
|
|
C, allows member names in different structures and unions to
|
|
overlap. A member name is recognized only in the context of
|
|
an expression whose type is that of the structure in which
|
|
the member is defined. In practice this means that a member
|
|
name will be recognized only to the right of a '.' or '->'
|
|
operator, where the expression to the left of the operator
|
|
is of type structure or pointer to structure the same as
|
|
that in which the member name was declared. This not only
|
|
allows structure names to be re-used without conflict in
|
|
more than one structure, it permits strict checking of the
|
|
usage of members; a common error with other C compilers is
|
|
the use of a member name with a structure pointer of the
|
|
wrong type, or worse with a variable which is a pointer to a
|
|
simple type.
|
|
|
|
There is however an escape from this, where the user
|
|
desires to use as a structure pointer something which is not
|
|
declared as such. This is via the use of a typecast. For
|
|
example, suppose it is desired to access a memory-mapped i/o
|
|
device, consisting of several registers. The declarations
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 14 HI-TECH C USER'S MANUAL
|
|
|
|
and use may look something like the code fragment in fig. 2.
|
|
|
|
struct io_dev
|
|
{
|
|
short io_status; /* status */
|
|
char io_rxdata; /* rx data */
|
|
char io_txdata; /* tx data */
|
|
};
|
|
|
|
#define RXRDY 01 /* rx ready */
|
|
#define TXRDY 02 /* tx ready */
|
|
|
|
/* define the (absolute) device address */
|
|
|
|
#define DEVICE ((struct io_dev *)0xFF00)
|
|
|
|
send_byte(c)
|
|
char c;
|
|
{
|
|
/* wait till transmitter ready */
|
|
while(!(DEVICE->io_status & TXRDY))
|
|
continue;
|
|
/* send the data byte */
|
|
DEVICE->io_txdata = c;
|
|
}
|
|
|
|
Fig. 2. Use of Typecast on an Absolute Address
|
|
|
|
|
|
In this example, the device in question has a 16 bit
|
|
status port, and two 8 bit data ports. The address of the
|
|
device (i.e. the address of its status port) is given as
|
|
(hex)0FF00. This address is typecast to the required struc-
|
|
ture pointer type to enable use of the structure member
|
|
names. The code generated by this will use absolute memory
|
|
references to access the device, as required.
|
|
|
|
Some examples of right and wrong usage of member names
|
|
are shown in fig. 3.
|
|
|
|
5.4. Unsigned Types
|
|
|
|
HI-TECH C implements unsigned versions of all integral
|
|
types; i.e. unsigned char, short, int and long. If an
|
|
unsigned quantity is shifted right, the shift will be per-
|
|
formed as a logical shift, i.e. bringing zeros into the
|
|
rightmost bits. Similarly right shifts of a signed quantity
|
|
will sign extend the rightmost bits.
|
|
|
|
5.5. Arithmetic Operations
|
|
|
|
On machines where arithmetic operations may be per-
|
|
formed more efficiently in lengths shorter than int,
|
|
operands shorter than int will not be extended to int length
|
|
unless necessary.
|
|
|
|
For example, if two characters are added and the result
|
|
stored into another character, it is only necessary to
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 15
|
|
|
|
|
|
struct fred
|
|
{
|
|
char a;
|
|
int b;
|
|
} s1, * s2;
|
|
|
|
struct bill
|
|
{
|
|
float c;
|
|
long b;
|
|
} x1, * x2;
|
|
|
|
main()
|
|
{
|
|
/* wrong - c is not a member of fred */
|
|
s1.c = 2;
|
|
|
|
/* correct */
|
|
s1.a = 2;
|
|
|
|
/* wrong - s2 is a pointer */
|
|
s2.a = 2;
|
|
|
|
/* correct */
|
|
x2->b = 24L;
|
|
|
|
/* right, but note type conversion
|
|
from long to int */
|
|
s2->b = x2->b;
|
|
}
|
|
|
|
Fig. 3. Examples of Member Usage
|
|
|
|
perform arithmetic in 8 bits, since any overflow into the
|
|
top 8 bits will be lost. However, if the sum of two charac-
|
|
ters is stored into an int, the addition should be done in
|
|
16 bits to ensure the correct result.
|
|
|
|
In accordance with the draft ANSI standard, operations
|
|
on float rather than double quantities will be performed in
|
|
the shorter precision rather than being converted to double
|
|
precision then back again.
|
|
|
|
5.6. Structure Operations
|
|
|
|
HI-TECH C implements structure assignments, structure
|
|
arguments and structure-valued functions in their full gen-
|
|
erality. The example in fig. 4 is a function returning a
|
|
structure. Some legal (and illegal) uses of the function are
|
|
also shown.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 16 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
struct bill
|
|
{
|
|
char a;
|
|
int b;
|
|
}
|
|
afunc()
|
|
{
|
|
struct bill x;
|
|
|
|
return x;
|
|
}
|
|
|
|
main()
|
|
{
|
|
struct bill a;
|
|
|
|
a = afunc(); /* ok */
|
|
pf("%d", afunc().a); /* ok */
|
|
|
|
/* illegal, afunc() cannot be assigned
|
|
to, therefore neither can
|
|
afunc().a */
|
|
afunc().a = 1;
|
|
|
|
/* illegal, same reason */
|
|
afunc().a++;
|
|
}
|
|
|
|
Fig. 4. Example of a Function Returning a Structure
|
|
|
|
5.7. Enumerated Types
|
|
|
|
HI-TECH C supports enumerated types; these provide a
|
|
structured way of defining named constants.
|
|
|
|
The uses of enumerated types are more restricted than
|
|
that allowed by the Unix C compiler, yet more flexible than
|
|
permitted by LINT. In particular, an expression of
|
|
enumerated type may be used to dimension arrays, as an array
|
|
index or as the operand of a switch statement. Arithmetic
|
|
may be performed on enumerated types, and enumerated type
|
|
expressions may be compared, both for equality and with the
|
|
relation operators. An example of the use of an enumerated
|
|
type is given in fig. 5.
|
|
|
|
5.8. Initialization Syntax
|
|
|
|
Kernighan and Ritchie in "The C Programming Language"
|
|
state that pairs of braces may be omitted from an initial-
|
|
izer in certain contexts; the draft ANSI standard provides
|
|
that a conforming C program must either include all braces
|
|
in an initializer, or leave them all out. HI-TECH C allows
|
|
any pairs of braces to be omitted providing that the front
|
|
end of the compiler can determine the size of any arrays
|
|
being initialized, and providing that there is no ambiguity
|
|
as to which braces have been omitted. To avoid ambiguity if
|
|
any pairs of braces are present then any braces which would
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 17
|
|
|
|
|
|
/* a represents 0, b -> 1 */
|
|
enum fred { a, b, c = 4 };
|
|
|
|
main()
|
|
{
|
|
enum fred x, y, z;
|
|
|
|
x = z;
|
|
if(x < z)
|
|
func();
|
|
x = (enum fred)3;
|
|
switch(z) {
|
|
case a:
|
|
case b:
|
|
default:
|
|
}
|
|
}
|
|
|
|
Fig. 5. Use of an Enumerated Type
|
|
|
|
enclose those braces must also be present. The compiler will
|
|
complain ("initialization syntax") if any ambiguity is
|
|
present.
|
|
|
|
5.9. Function Prototypes
|
|
|
|
A new feature of C included in the proposed ANSI for C,
|
|
known as "function prototypes", provides C with an argument
|
|
checking facility, i.e. it allows the compiler to check at
|
|
compile time that actual arguments supplied to a function
|
|
invocation are consistent with the formal parameters
|
|
expected by the function. The feature allows the programmer
|
|
to include in a function declaration (either an external
|
|
declaration or an actual definition) the types of the param-
|
|
eters to that function. For example, the code fragment
|
|
shown in fig. 6 shows two function prototypes.
|
|
|
|
void fred(int, long, char *);
|
|
|
|
char *
|
|
bill(int a, short b, ...)
|
|
{
|
|
return a;
|
|
}
|
|
|
|
Fig. 6. Function Prototypes
|
|
|
|
|
|
The first prototype is an external declaration of the
|
|
function _f_r_e_d(), which accepts one integer argument, one
|
|
long argument, and one argument which is a pointer to char.
|
|
Any usage of _f_r_e_d() while the prototype declaration is in
|
|
scope will cause the actual parameters to be checked for
|
|
number and type against the prototype, e.g. if only two
|
|
arguments were supplied or an integral value was supplied
|
|
for the third argument the compiler would report an error.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 18 HI-TECH C USER'S MANUAL
|
|
|
|
In the second example, the function _b_i_l_l() expects two
|
|
or more arguments. The first and second will be converted to
|
|
int and short respectively, while the remainder (if present)
|
|
may be of any type. The ellipsis symbol (...) indicates to
|
|
the compiler that zero or more arguments of any type may
|
|
follow the other arguments. The ellipsis symbol must be last
|
|
in the argument list, and may not appear as the only argu-
|
|
ment in a prototype.
|
|
|
|
All prototypes for a function must agree exactly, how-
|
|
ever it is legal for a definition of a function in the old
|
|
style, i.e. with just the parameter names inside the
|
|
parentheses, to follow a prototype declaration provided the
|
|
number and type of the arguments agree. In this case it is
|
|
essential that the function definition is in scope of the
|
|
prototype declaration.
|
|
|
|
Access to unspecified arguments (i.e. arguments sup-
|
|
plied where an ellipsis appeared in a prototype) must be via
|
|
the macros defined in the header file <stdarg.h>. This
|
|
defines the macros _v_a__s_t_a_r_t, _v_a__a_r_g and _v_a__e_n_d. See _v_a__s_t_a_r_t
|
|
in the library function listing for more information.
|
|
|
|
NOTE that is is a grave error to use a function which
|
|
has an associated prototype unless that prototype is in
|
|
scope, i.e. the prototype MUST be declared (possibly in a
|
|
header file) before the function is invoked. Failure to
|
|
comply with this rule may result in strange behaviour of the
|
|
program. HI-TECH C will issue a warning message ("func()
|
|
declared implicit int") whenever a function is called
|
|
without an explicit declaration. It is good practice to
|
|
declare all functions and global variables in one or more
|
|
header files which are included wherever the functions are
|
|
defined or referenced.
|
|
|
|
5.10. Void and Pointer to Void
|
|
|
|
The _v_o_i_d type may be used to indicate to the compiler
|
|
that a function does not return a value. Any usage of the
|
|
return value from a void function will be flagged as an
|
|
error.
|
|
|
|
The type _v_o_i_d *, i.e. pointer to void, may be used as a
|
|
"universal" pointer type. This is intended to assist in the
|
|
writing of general purpose storage allocators and the like,
|
|
where a pointer is returned which may be assigned to another
|
|
variable of some other pointer type. The compiler permits
|
|
without typecasting and without reporting an error the
|
|
conversion of _v_o_i_d * to any other pointer type and vice
|
|
versa. The programmer is advised to use this facility care-
|
|
fully and ensure that any _v_o_i_d * value is usable as a
|
|
pointer to any other type, e.g. the alignment of any such
|
|
pointer should be suitable for storage of any object.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 19
|
|
|
|
5.11. Type qualifiers
|
|
|
|
The ANSI C standard introduced the concept of _t_y_p_e
|
|
_q_u_a_l_i_f_i_e_r_s to C; these are keywords that qualify the type to
|
|
which they are applied. The type qualifiers defined by ANSI
|
|
C are const and volatile. HI-TECH C also implements several
|
|
other type qualifiers. The extra qualifiers include:
|
|
|
|
far
|
|
near
|
|
interrupt
|
|
fast interrupt
|
|
port
|
|
|
|
Not all versions of the compilers implement all of the extra
|
|
qualifiers. See the machine dependent section for further
|
|
information.
|
|
|
|
When constructing declarations using type qualifiers,
|
|
it is very easy to be confused as to the exact semantics of
|
|
the declaration. A couple of rules-of-thumb will make this
|
|
easier. Firstly, where a type qualifier appears at the left
|
|
of a declaration it may appear with any storage class
|
|
specifier and the basic type in any order, e.g.
|
|
|
|
static void interrupt func();
|
|
|
|
is semantically the same as
|
|
|
|
interrupt static void func();
|
|
|
|
|
|
Where a qualifier appears in this context, it applies
|
|
to the basic type of the declaration. Where a qualifier
|
|
appears to the right of one or more '*' (_s_t_a_r) pointer
|
|
modifiers, then you should read the declaration from right
|
|
to left, e.g.
|
|
|
|
char * far fred;
|
|
|
|
should be read as "fred is a far pointer to char". This
|
|
means that fred is qualified by _f_a_r, not the char to which
|
|
it points. On the other hand,
|
|
|
|
char far * bill;
|
|
|
|
should be read as "bill is a pointer to a far char", i.e.
|
|
the char to which bill points is located in the far address
|
|
space. In the context of the 8086 compiler this will mean
|
|
that bill is a 32 bit pointer while fred is a 16 bit
|
|
pointer. You will hear bill referred to as a "far pointer",
|
|
however the terminology "pointer to far" is preferred.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 20 HI-TECH C USER'S MANUAL
|
|
|
|
5.12.
|
|
|
|
There are two methods provided for in-line assembler
|
|
code in C programs. The first allows several lines of
|
|
assembler anywhere in a program. This is via the #asm and
|
|
#endasm preprocessor directives. Any lines between these
|
|
two directives will be copied straight through to the assem-
|
|
bler file produced by the compiler. Alternatively you can
|
|
use the asm("_s_t_r_i_n_g"); construct anywhere a C statement is
|
|
expected. The _s_t_r_i_n_g will be copied through to the assembler
|
|
file. Care should be taken with using in-line assembler
|
|
since it may interact with compiler generated code.
|
|
|
|
5.13. Pragma Directives
|
|
|
|
The draft ANSI C standard provides for a #pragma
|
|
preprocessor directive that allows compiler implementations
|
|
to control various aspects of the compilation process.
|
|
Currently HI-TECH C only supports one pragma, the _p_a_c_k
|
|
directive. This allows control over the manner in which
|
|
members are allocated inside a structure. By default, some
|
|
of the compilers (especially the 8086 and 68000 compilers)
|
|
will align structure members onto even boundaries to optim-
|
|
ize machine accesses. It is sometimes desired to override
|
|
this to achieve a particular layout inside a structure. The
|
|
_p_a_c_k pragma allows specification of a maximum packing fac-
|
|
tor. For example, #pragma pack1(1) will instruct the com-
|
|
piler that no additional padding be inserted between struc-
|
|
ture members, i.e. that all members should be aligned on
|
|
boundaries divisible by 1. Similarly #pragma pack(2) will
|
|
allow alignment on boundaries divisible by 2. In no case
|
|
will use of the _p_a_c_k pragma force a greater alignment than
|
|
would have been used for that data type anyway.
|
|
|
|
More that one _p_a_c_k pragma may be used in a program. Any
|
|
use will remain in force until changed by another _p_a_c_k or
|
|
until the end of the file. Do not use a _p_a_c_k pragma before
|
|
include files such as <_s_t_d_i_o._h> as this will cause incorrect
|
|
declarations of run-time library data structures.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 21
|
|
|
|
|
|
6. Machine Dependencies
|
|
|
|
|
|
HI-TECH C eliminates many of the machine dependent
|
|
aspects of C, since it uniformly implements such features as
|
|
unsigned char. There are however certain areas where machine
|
|
dependencies are inherent in the C language; programmers
|
|
should be aware of these and take them into account when
|
|
writing portable code.
|
|
|
|
The most obvious of these machine dependencies is the
|
|
varying size of C types; on some machines an int will be 16
|
|
bits, on others it may be 32 bits. HI-TECH C conforms to the
|
|
following rules, which represent common practice in most C
|
|
compilers.
|
|
|
|
char is at least 8 bits
|
|
short is at least 16 bits
|
|
long is at least 32 bits
|
|
int is the same as either short or long
|
|
float is at least 32 bits
|
|
double is at least as wide as float
|
|
|
|
|
|
Because of the variable width of an int, it is recom-
|
|
mended that short or long be used wherever possible in
|
|
preference to int. The exception to this is where a quantity
|
|
is required to correspond to the natural word size of the
|
|
machine.
|
|
|
|
Another area of machine differences is that of byte
|
|
ordering; the ordering of bytes in a short or long can vary
|
|
significantly between machines. There is no easy approach to
|
|
this problem other than to avoid code which depends on a
|
|
particular ordering. In particular you should avoid writing
|
|
out whole structures to a file (via _f_w_r_i_t_e()) unless the
|
|
file is only to be read by the same program then deleted.
|
|
Different compilers use different amounts of padding between
|
|
structure members, though this can be modified via the
|
|
#pragma pack(n) construct.
|
|
|
|
6.1. Predefined Macros
|
|
|
|
One technique through which machine unavoidable machine
|
|
dependencies may be managed is the predefined macros pro-
|
|
vided by each compiler to identify the target processor and
|
|
operating system (if any). These are defined by the compiler
|
|
driver and may be tested with conditional compilation
|
|
preprocessor directives.
|
|
|
|
The macros defined by various compilers are listed in
|
|
table 2. These can be used as shown in the example in fig .
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 22 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
___________________________________________
|
|
|_M_a_c_r_o_______________D_e_f_i_n_e_d__f_o_r_____________|
|
|
| i8051 8051 processor family |
|
|
| i8086 8086 processor family |
|
|
| i8096 8096 processor family |
|
|
| z80 Z80 processor and derivatives |
|
|
| m68000 68000 processor family |
|
|
| m6800 6801, 68HC11 and 6301 processors|
|
|
| m6809 6809 processor |
|
|
| DOS MS-DOS and PC-DOS |
|
|
| CPM CP/M-80 and CP/M-86 |
|
|
| TOS Atari ST |
|
|
|___________________________________________|
|
|
|
|
|
|
Table 2. Predefined Macros
|
|
|
|
|
|
#if DOS
|
|
char * filename = "c:file";
|
|
#endif /* DOS */
|
|
#if CPM
|
|
char * filename = "0:B:afile";
|
|
#endif /* CPM */
|
|
|
|
|
|
|
|
|
|
Use this page for notes
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 23
|
|
|
|
|
|
7. Error Checking and Reporting
|
|
|
|
|
|
Errors may be reported by any pass of the compiler,
|
|
however in practice the assembler and optimizer will not
|
|
encounter any errors in the generated code. The types of
|
|
errors produced by each pass are summarized below. In gen-
|
|
eral any error will be indentified by the name of the source
|
|
file in which it was encountered, and the line number at
|
|
which it was detected. P1 will also nominate the name of
|
|
the function inside which the error was detected.
|
|
|
|
Errors may be redirected to a file with the usual syn-
|
|
tax, i.e. a 'greater than' symbol ('>') followed by the name
|
|
of a file into which the errors should be written. The file
|
|
name may of course be a device name, e.g. LST: for CP/M or
|
|
PRN for MS-DOS.
|
|
|
|
CPP will report errors relating to macro definitions
|
|
and expansions, as well as conditional compilation.
|
|
|
|
P1 is the pass which reports most errors; it performs
|
|
syntax and semantic checking of the input, and will report
|
|
both fatal and warning errors when encountered. Syntax
|
|
errors will normally be expressed as "symbol expected" or
|
|
"symbol unexpected". Semantic errors may relate to unde-
|
|
clared, redeclared or misdeclared variables. P1 will also
|
|
report variable definitons which are unused or unreferenced.
|
|
These errors are warnings, as are most type checking errors.
|
|
|
|
When P1 encounters errors it will list the source line
|
|
containing the error on the screen, and underneath display
|
|
the error message and an up arrow pointing to the point at
|
|
which the compiler detected the error. In some cases the
|
|
actual cause of the error may be earlier in the line or even
|
|
on previous line.
|
|
|
|
CGEN may occasionally report errors, usually warnings,
|
|
and mostly related to unusual combinations of types with
|
|
constants, for example testing if an unsigned quantity is
|
|
less than zero. One fatal error produced by CGEN is "can't
|
|
generate code for this expression" and means that the
|
|
expression currently being compiled is in some way too com-
|
|
plicated to produce code for. This can usually be overcome
|
|
by rewriting the source code. Such errors are rare and will
|
|
occur only for unusual constructs.
|
|
|
|
The linker will report undefined or multiply defined
|
|
symbols. Note that variable declarations inside a header
|
|
file which is included in more than one source file must be
|
|
declared as extern, to avoid multiply defined symbol errors.
|
|
These symbols must then be defined in one and one only
|
|
source file.
|
|
|
|
A comprehensive list of error messages is included in
|
|
an appendix.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 24 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
|
|
|
|
Use this page for notes
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 25
|
|
|
|
|
|
8. Standard Libraries
|
|
|
|
|
|
8.1. Standard I/O
|
|
|
|
C is a language which does not specify the I/O facil-
|
|
ites in the language itself; rather all I/O is performed via
|
|
library routines. In practice this results in I/O handling
|
|
which is no less convenient than any other language, with
|
|
the added possibility of customising the I/O for a specific
|
|
application. For example it is possible to provide a routine
|
|
to replace the standard getchar() (which gets one character
|
|
from the standard input) with a special getchar(). This is
|
|
particulary useful when writing code which is to run on a
|
|
special hardware configuration, while maintaining a high
|
|
level of compatibility with "standard" C I/O.
|
|
|
|
There is in fact a Standard I/O library (STDIO) which
|
|
defines a portable set of I/O routines. These are the rou-
|
|
tines which are normally used by any C application program.
|
|
These routines, along with other non-I/O library routines,
|
|
are listed in detail in a subsequent section of the manual.
|
|
|
|
8.2. Compatibility
|
|
|
|
The libraries supplied with HI-TECH C are highly compa-
|
|
tible with the ANSI libraries, as well as the V7 UNIX
|
|
libraries, both at the Standard I/O level and the UNIX sys-
|
|
tem call level. The Standard I/O library is complete, and
|
|
conforms in all respects with the UNIX Standard I/O library.
|
|
The library routines implementing UNIX system call like
|
|
functions are as close as possible to those system calls,
|
|
however there are some UNIX system calls that cannot be
|
|
simulated on other systems, e.g. the link() operation. How-
|
|
ever the basic low level I/O routines, i.e. open, close,
|
|
read, write and lseek are identical to the UNIX equivalents.
|
|
This means that many programs written to run on UNIX, even
|
|
if they do not use Standard I/O, will run with little modif-
|
|
ication when compiled with HI-TECH C.
|
|
|
|
8.3. Libraries for Embedded Systems
|
|
|
|
The cross compilers, designed to produce code for tar-
|
|
get systems without operating systems, are supplied with
|
|
libraries implementing a subset of the STDIO functions. Not
|
|
provided are those functions dealing with files. Included
|
|
are _p_r_i_n_t_f(), _s_c_a_n_f() etc. These operate by calling two low
|
|
level functions _p_u_t_c_h and _g_e_t_c_h() which typically send and
|
|
receive characters via a serial port. Where the compiler is
|
|
aimed at a single-chip micro with on-board UART this is
|
|
used. The source code for all these functions is supplied
|
|
enabling the user to modify it to address a different serial
|
|
port.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 26 HI-TECH C USER'S MANUAL
|
|
|
|
8.4. Binary I/O
|
|
|
|
On some operating systems, notably CP/M, files are
|
|
treated differently according to whether they contain ASCII
|
|
(i.e. printable) or binary data. MD-DOS also suffers from
|
|
this problem, not due to any lack in the operating system
|
|
itself, but rather because of the hangover from CP/M which
|
|
results in many programs putting a redundant ctrl-Z at the
|
|
end of files. Unfortunately there is no way to determine
|
|
which type of data a file contains (except perhaps by the
|
|
name or type of the file, and this is not reliable). To
|
|
overcome this difficulty, there is an extra character which
|
|
may be included in the MODE string to a fopen() call. To
|
|
open a file for ASCII I/O, the form of the fopen() call is:
|
|
|
|
fopen("filename.ext", "r") /* for reading */
|
|
fopen("filename.ext", "w") /* for writing */
|
|
|
|
To open a file for binary I/O, the character 'b' may be
|
|
appended to the
|
|
|
|
fopen("filename.ext", "rb")
|
|
fopen("filename.ext", "wb")
|
|
|
|
|
|
The additional character instructs the STDIO library
|
|
that this file is to be handled in a strict binary fashion.
|
|
On CP/M or MS-DOS, a file opened in ASCII mode will have the
|
|
following special character handling performed by the STDIO
|
|
routines:
|
|
|
|
newline
|
|
('\n') converted to carriage return/newline on output.
|
|
|
|
return
|
|
('\r') ignored on input
|
|
|
|
Ctrl-Z
|
|
interpreted as End-Of-File on input and, for CP/M only,
|
|
appended when closing the file.
|
|
|
|
The special actions performed on ASCII files ensure
|
|
that the file is written in a format compatible with other
|
|
programs handling text files, while eliminating the require-
|
|
ment for any special handling by the user program - the file
|
|
appears to the user program as though it were a UNIX-like
|
|
text file.
|
|
|
|
None of these special actions are performed on a file
|
|
opened in binary mode. This is required when handling any
|
|
kind of binary data, to ensure that spurious bytes are not
|
|
inserted, and premature EOF's are not seen.
|
|
|
|
Since the binary mode character is additional to the
|
|
normal mode character, this usage is quite compatible with
|
|
UNIX C. When compiled on UNIX, the additional character will
|
|
be ignored.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 27
|
|
|
|
A mention here of the term `stream' is appropriate;
|
|
stream is used in relation to the STDIO library routines to
|
|
mean the source or sink of bytes (characters) manipulated by
|
|
those routines. Thus the FILE pointer supplied as an argu-
|
|
ment to the STDIO routines may be regarded as a handle on
|
|
the corresponding stream. A stream may be viewed as a
|
|
featureless sequence of bytes, originating from or being
|
|
sent to a device or file or even some other indeterminate
|
|
source. A FILE pointer should not be confused with the 'file
|
|
descriptors' used with the low-level I/O functions _o_p_e_n(),
|
|
_c_l_o_s_e(), _r_e_a_d() and _w_r_i_t_e(). These form an independent group
|
|
of I/O functions which perform unbuffered reads and writes
|
|
to files.
|
|
|
|
8.5. Floating Point Library
|
|
|
|
HI-TECH C supports floating point as part of the
|
|
language, however the Z80 implementation provides single
|
|
precision only; double floats are permitted but are no dif-
|
|
ferent to floats. In addition, the standard library,
|
|
LIBC.LIB, does not contain any floating point routines.
|
|
These have been separated out into another library,
|
|
LIBF.LIB. This means that if this library is not searched no
|
|
floating point support routines will be linked in, thus
|
|
avoiding any size penalty for the floating point support if
|
|
it is not used. This is particulary important for printf and
|
|
scanf, and thus LIBF.LIB contains versions of printf and
|
|
scanf that do support floating point formats.
|
|
|
|
Thus, if floating point is used, a -LF option should be
|
|
used AFTER the source and/or object files to the C command.
|
|
E.g.:
|
|
|
|
C -V -O x.c y.c z.obj -LF
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 28 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
|
|
|
|
Use this page for notes
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 29
|
|
|
|
|
|
9. Stylistic Considerations
|
|
|
|
|
|
Although it is not the purpose of this manual to set
|
|
out a coding standard for C, some comments regarding use of
|
|
some of the features of HI-TECH C may be useful.
|
|
|
|
9.1. Member Names
|
|
|
|
Although HI-TECH C allows the same structure or union
|
|
member name to be used in more than one structure or union,
|
|
this may not be allowed by another C compiler. To help
|
|
ensure portability of the code, it is recommended that
|
|
member names all be distinct, and a useful way of ensuring
|
|
this is to prefix each member name with one or two letters
|
|
derived from the name of the structure itself. An example is
|
|
given in fig. 7.
|
|
|
|
struct tree_node
|
|
{
|
|
struct tree_node * t_left;
|
|
struct tree_node * t_right;
|
|
short t_operator;
|
|
};
|
|
|
|
|
|
Fig. 7. Member Naming
|
|
|
|
|
|
Because HI-TECH C insists on use of all intermediate
|
|
names when referencing a member nested inside several struc-
|
|
tures, some simple macro definitions can serve as a short-
|
|
hand. An example is given in fig. 8.
|
|
|
|
struct tree_node
|
|
{
|
|
short t_operator;
|
|
union
|
|
{
|
|
struct tree_node * t_un_sub[2];
|
|
char * t_un_name;
|
|
long t_un_val;
|
|
} t_un;
|
|
};
|
|
|
|
#define t_left t_un.t_un_sub[0]
|
|
#define t_right t_un.t_un_sub[1]
|
|
#define t_name t_un.t_un_name
|
|
#define t_val t_un.t_un_val
|
|
|
|
|
|
Fig. 8. Member Name Shorthand
|
|
|
|
|
|
This enables the variant components of the structure to
|
|
be referred to by short names, while guaranteeing portabil-
|
|
ity and presenting a clean definition of the structure.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 30 HI-TECH C USER'S MANUAL
|
|
|
|
9.2. Use of Int
|
|
|
|
It is recommended that the type int be avoided wherever
|
|
possible, in preference to the types short or long. This is
|
|
because of the variable size of int, whereas short is com-
|
|
monly 16 bits and long 32 bits in most C implementations.
|
|
|
|
9.3. Extern Declarations
|
|
|
|
Some compilers permit a non-initialized global variable
|
|
to be declared in more than one place, with the multiple
|
|
definitions being resolved by the linker as all defining the
|
|
same thing. HI-TECH C specifically disallows this, since it
|
|
may lead to subtle bugs. Instead, global variables may be
|
|
declared extern in as many places as you wish, and must be
|
|
defined in one and one only place. Typically this will mean
|
|
declaring global variables in a header file as extern, and
|
|
defining each variable in the file most closely associated
|
|
with that variable.
|
|
|
|
This usage will be portable to virually all other C
|
|
implementations.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 31
|
|
|
|
|
|
10. Memory Models
|
|
|
|
|
|
With many of the processors supported by the HI-TECH C
|
|
compilers there are more than one address space accessible
|
|
to a program. Typically one address space is more economical
|
|
to access than another, larger address space. Thus it is
|
|
desirable to be able to tailor a prorgram's use of memory to
|
|
achieve the greatest economy in addressing (thus minimizing
|
|
program size and maximizing speed) while allowing access to
|
|
as much memory as the program requires.
|
|
|
|
This concept of different address spaces is not catered
|
|
for by either K&R or ANSI C (except to recognize the possi-
|
|
bility of separate address spaces for code and data).
|
|
Without any extensions to the language itself it is possible
|
|
to devise more than one memory model for a given processor,
|
|
selected at compile time. This has the effect of selecting
|
|
one addressing method for all data and/or code. This permits
|
|
the model for a particular program to be chosen depending on
|
|
that program's memory requirements.
|
|
|
|
In many programs, however, only one or two data struc-
|
|
tures are large enough to need to be placed in the larger
|
|
address space. Selection of a "large" memory model for the
|
|
whole of the program makes the whole program larger and
|
|
slower just to allow a few large data structures. This can
|
|
be overcome by allowing individual selection of the address
|
|
space for each data structure. Unfortunately this entails
|
|
extensions to the language, never a desirable approach. To
|
|
minimize the effect of such extensions they should satisfy
|
|
the following criteria:
|
|
|
|
1. As far as possible the extensions should be consistent
|
|
with common practice.
|
|
|
|
2. The extensions should fit a machine-independent model
|
|
to maximize portability across processors and operating
|
|
systems.
|
|
|
|
These goals have been achieved within HI-TECH C by
|
|
means of the following model:
|
|
|
|
Each memory model defines three address spaces
|
|
each for code and data. These address spaces are
|
|
known as the _n_e_a_r, _f_a_r and _d_e_f_a_u_l_t spaces. Any
|
|
object qualified by the near keyword will be
|
|
placed in the _n_e_a_r address space, any object qual-
|
|
ified by the far keyword shall be placed in the
|
|
_f_a_r address space, and all other objects shall be
|
|
placed in the _d_e_f_a_u_l_t address space. The _n_e_a_r
|
|
address space shall be a (possibly improper) sub-
|
|
space of the _d_e_f_a_u_l_t address space, while the
|
|
_d_e_f_a_u_l_t address space shall be a (possibly
|
|
improper) subspace of the _f_a_r address space. There
|
|
shall be up to three kinds of pointers correspond-
|
|
ing to the three address spaces, each capable of
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 32 HI-TECH C USER'S MANUAL
|
|
|
|
addressing an object in its own address space or a
|
|
subspace of that address space.
|
|
|
|
This implies that the address of an object may be con-
|
|
verted to a pointer into a larger address space, e.g. a _n_e_a_r
|
|
object may have its address converted to a pointer to _f_a_r,
|
|
but a _f_a_r object may not be able to be addressed by a
|
|
pointer to _n_e_a_r.
|
|
|
|
In practice the _d_e_f_a_u_l_t address space will usually
|
|
correspond exactly to either the _n_e_a_r or _f_a_r address spaces.
|
|
If all three address spaces correspond to the same memory
|
|
then there is only one memory model possible. This occurs
|
|
with the 68000 processor. Where the _d_e_f_a_u_l_t code and data
|
|
spaces may each correspond to either the _n_e_a_r or _f_a_r address
|
|
spaces then there will be a total of four memory models.
|
|
This is the case with the 8086 processor.
|
|
|
|
The keywords far and near are supported by all the HI-
|
|
TECH C compilers, but the exact correspondence of address
|
|
spaces is determined by the individual characteristics of
|
|
each processor and the choice of memory model (if there is a
|
|
choice). However code written using these keywords will be
|
|
portable providing it obeys the constraints of the model
|
|
described above.
|
|
|
|
This model also corresponds well with other implementa-
|
|
tions using the near and far keywords, although such imple-
|
|
mentations do not appear to have been designed around a for-
|
|
mal, portable model.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 33
|
|
|
|
|
|
11. What Went Wrong
|
|
|
|
|
|
There are numerous error messages that the compiler may
|
|
produce. Most of these relate to errors in the source code
|
|
(syntax errors of various kinds and so forth) but some
|
|
represent limitations, particularly of memory. The two
|
|
passes most likely to be affected by memory limitations are
|
|
the code generator and the optimizer. The code generator
|
|
will issue the message "No room" if it runs out of dynamic
|
|
memory. This can usually be eliminated by simplifying the
|
|
expression at the line nominated in the error message. The
|
|
more complex the expression, the more memory is required to
|
|
store the tree representing it. Reducing the number of sym-
|
|
bols used in the program will also help.
|
|
|
|
Note that this error is different from the message
|
|
"Can't generate code for this expression" which indicates
|
|
that the expression is in some way too difficult for the
|
|
code generator to handle. This message will be encountered
|
|
very infrequently, and can be eliminated by changing the
|
|
expression in some way, e.g. computing an intermediate value
|
|
into a temporary variable.
|
|
|
|
The optimizer reads the assembler code for a whole
|
|
function into memory at one time. Very large functions will
|
|
not fit, giving the error message "Optim: out of memory in
|
|
_func" where func is the name of the function responsible.
|
|
In this case the function should be broken up into smaller
|
|
functions. This will only occur with functions with several
|
|
hundred lines of C source code. Good coding practice will
|
|
normally limit functions to less than 50 lines each.
|
|
|
|
If a pass exits with the message "Error closing file",
|
|
or "Write error on file", this usually indicates that there
|
|
is insufficient room on the current disk.
|
|
|
|
If you use a wordprocessing editor such as Wordstar,
|
|
ensure that you use the "non-document" mode or whatever the
|
|
corresponding mode is. The edited file should not contain
|
|
any characters with the high bit set, and the line feed at
|
|
the end of the line must be present. Lines should be not
|
|
more than 255 characters long.
|
|
|
|
When using floating point, ensure that you use a -LF
|
|
flag at the END of the command line, to cause the floating
|
|
point library to be searched. This will cause floating ver-
|
|
sions of printf and scanf to be linked in, as well as
|
|
specific floating point routines.
|
|
|
|
If the non-floating version of printf is used with a
|
|
floating format such as %f then it will simply print the
|
|
letter f.
|
|
|
|
If the linker gives an "Undefined symbol" message for
|
|
some symbol which you know nothing about, it is possible
|
|
that it is a library routine which was not found during the
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 34 HI-TECH C USER'S MANUAL
|
|
|
|
library search due to incorrect library ordering. In this
|
|
case you can search the library twice, e.g. for the stan-
|
|
dard library add a -LC to the end of the C command line, or
|
|
-LF for the floating library. If you have specified the
|
|
library by name simply repeat its name.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 35
|
|
|
|
|
|
12. Z80 Assembler Reference Manual
|
|
|
|
|
|
12.1. Introduction
|
|
|
|
The assembler incorporated in the HI-TECH C compiler
|
|
system is a full-featured relocating macro assembler accept-
|
|
ing Zilog mnemonics. These mnemonics and the syntax of the
|
|
Z80 assembly language are described in the "Z80 Assembly
|
|
Language Handbook" published by Zilog and are included at
|
|
the end of this manual as a reference. The assembler imple-
|
|
ments certain extensions to the operands allowed, and cer-
|
|
tain additional pseudo-ops, which are described here. The
|
|
assembler also accepts the additional opcodes for the Hita-
|
|
chi 64180 and Z180 processors.
|
|
|
|
12.2. Usage
|
|
|
|
The assembler is named zas, and is invoked as follows:
|
|
|
|
ZAS options files ...
|
|
|
|
|
|
The files are one or more assembler source files which
|
|
will be assembled, but note that all the files are assembled
|
|
as one, not as separate files. To assemble separate files,
|
|
the assembler must be invoked on each file separately. The
|
|
options are zero or more options from the following list:
|
|
|
|
-N Ignore arithmetic overflow in expressions. The -N
|
|
option suppresses the normal check for arithmetic over-
|
|
flow. The assembler follows the "Z80 Assembly Language
|
|
Handbook" in its treatment of overflow, and in certain
|
|
instances this can lead to an error where in fact the
|
|
expression does evaluate to what the user intended.
|
|
This option may be used to override the overflow check-
|
|
ing.
|
|
|
|
-J Attempt to optimize jumps to branches. The -J option
|
|
will request the assembler to attempt to assemble jumps
|
|
and conditional jumps as relative branches where possi-
|
|
ble. Only those conditional jumps with branch
|
|
equivalents will be optimized, and jumps will only be
|
|
optimized to branches where the target is in branch
|
|
range. Note that the use of this option slows the
|
|
assembly down, due to the necessity for the assembler
|
|
to make an additional pass over the input code.
|
|
|
|
-U Treat undefined symbols as external. The -U option
|
|
will suppress error messages relating to undefined sym-
|
|
bols. Such symbols are treated as externals in any
|
|
case. The use of this option will not alter the object
|
|
code generated, but merely serves to suppress the error
|
|
messages.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 36 HI-TECH C USER'S MANUAL
|
|
|
|
-O_f_i_l_e
|
|
Place the object code in _f_i_l_e. The default object file
|
|
name is constructed from the name of the first source
|
|
file. Any suffix or file type (i.e. anything following
|
|
the rightmost dot ('.') in the name is stripped, and
|
|
the suffix .obj appended. Thus the command
|
|
|
|
ZAS file1.as file2.z80
|
|
|
|
will produce an object file called file1.obj. The use
|
|
of the -O option will override this default convention,
|
|
allowing the object file to be arbitrarily named. For
|
|
example:
|
|
|
|
ZAS -ox.obj file1.obj
|
|
|
|
will place the object code in x.obj.
|
|
|
|
-L_l_i_s_t
|
|
Place an assembly listing in the file _l_i_s_t, or on stan-
|
|
dard output if _l_i_s_t is null A listfile may be produced
|
|
with the -L option. If a file name is supplied to the
|
|
option, the list file will be created with that name,
|
|
otherwise the listing will be written to standard out-
|
|
put (i.e. the console). List file names such as CON:
|
|
and LST: are acceptable.
|
|
|
|
-W_w_i_d_t_h
|
|
The listing is to be formatted for a printer of given
|
|
_w_i_d_t_h The -W option specifies the width to which the
|
|
listing is to be formatted. E.g.
|
|
|
|
ZAS -Llst: -W80 x.as
|
|
|
|
will output a listing formatted for an 80 column
|
|
printer to the list device.
|
|
|
|
-C This options requests ZAS to produce cross reference
|
|
information in a file. The file will be called _x_x_x.crf
|
|
where _x_x_x is the base part of the first source file
|
|
name. It will then be necessary to run the CREF utility
|
|
to turn this information into a formatted listing.
|
|
|
|
12.3. The Assembly Language
|
|
|
|
As mentioned above, the assembly language accepted by
|
|
zas is based on the Zilog mnemonics. You should have some
|
|
reference book such as the "Z80 Assembly Language Handbook".
|
|
Described below are those areas in which zas differs, or has
|
|
extensions, compared to the standard Zilog assembly
|
|
language.
|
|
|
|
12.3.1. Symbols
|
|
|
|
The symbols (labels) accepted by the assembler may be
|
|
of any length, and all characters are significant. The char-
|
|
acters used to form a symbol may be chosen from the upper
|
|
and lower case alphabetics, the digits 0-9, and the special
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 37
|
|
|
|
symbols underscore ('_'), dollar ('$') and question mark
|
|
('?'). The first character may not be numeric. Upper and
|
|
lower case are distinct. The following are all legal and
|
|
distinct symbols.
|
|
|
|
An_identifier
|
|
an_identifier
|
|
an_identifier1
|
|
$$$
|
|
?$_123455
|
|
|
|
|
|
Note that the symbol $ is special (representing the
|
|
current location) and may not be used as a label. Nor may
|
|
any opcode or pseudo-op mnemonic, register name or condition
|
|
code name. You should note the additional condition code
|
|
names described later.
|
|
|
|
12.3.1.1. Temporary Labels
|
|
|
|
The assembler implements a system of temporary labels,
|
|
useful for use within a localized section of code. These
|
|
help eliminate the need to generate names for labels which
|
|
are referenced only in the immediate vicinity of their
|
|
definition, for example where a loop is implemented.
|
|
|
|
A temporary label takes the form of a digit string. A
|
|
reference to such a label requires the same digit string,
|
|
plus an appended b or f to signify a backward or forward
|
|
reference respectively. Here is an example of the use of
|
|
such labels.
|
|
|
|
entry_point: ;This is referenced from far away
|
|
ld b,10
|
|
1: dec c
|
|
jr nz,2f ;if zero, branch forward to 2:
|
|
ld c,8
|
|
djnz 1b ;decrement and branch back to 1:
|
|
jr 1f ;this does not branch to the
|
|
;same label as the djnz
|
|
2: call fred ;get here from the jr nz,2f
|
|
1: ret ;get here from the jr 1f
|
|
|
|
|
|
The digit string may be any positive decimal number 0
|
|
to 65535. A temporary label value may be re-used any number
|
|
of times. Where a reference to e.g. 1b is made, this will
|
|
reference the closest label 1: found by looking backwards
|
|
from the current point in the file. Similarly 23f will
|
|
reference the first label 23: found by looking forwards from
|
|
the current point in the file.
|
|
|
|
12.3.2. Constants
|
|
|
|
Constants may be entered in one of the radices 2, 8, 10
|
|
or 16. The default is 10. Constants in the other radices may
|
|
be denoted by a trailing character drawn from the following
|
|
set:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 38 HI-TECH C USER'S MANUAL
|
|
|
|
Character Radix Name
|
|
|
|
B 2 binary
|
|
O 8 octal
|
|
Q 8 octal
|
|
o 8 octal
|
|
q 8 octal
|
|
H 16 hexadecimal
|
|
h 16 hexadecimal
|
|
|
|
|
|
Hexadecimal constants may also be specified in C style,
|
|
for example LD A,0x21. Note that a lower case b may not be
|
|
used to indicate a binary number, since 1b is a backward
|
|
reference to a temporary label 1:.
|
|
|
|
12.3.2.1. Character Constants
|
|
|
|
A character constant is a single character enclosed in
|
|
single quotes ('). Multi character constants may be used
|
|
only as an operand to a DEFM pseudo-op.
|
|
|
|
12.3.2.2. Floating Constants
|
|
|
|
A floating constant in the usual notation (e.g. 1.234
|
|
or 1234e-3) may be used as the operand to a DEFF pseudo-op.
|
|
|
|
12.3.2.3. Opcode Constants
|
|
|
|
Any z80 opcode may be used as a constant in an expres-
|
|
sion. The value of the opcode in this context will be the
|
|
byte that the opcode would have assembled to if used in the
|
|
normal way. If the opcode is a 2-byte opcode (CB or ED pre-
|
|
fix byte) only the second byte of the opcode will be used.
|
|
This is particularly useful when setting up jump vectors.
|
|
For example:
|
|
|
|
ld a,jp ;a jump instruction
|
|
ld (0),a ;0 is jump to warm boot
|
|
ld hl,boot ;done here
|
|
ld (1),hl
|
|
|
|
|
|
12.3.3. Expressions
|
|
|
|
Expressions are constructed largely as described in the
|
|
"Z80 Assembly Language Handbook".
|
|
|
|
12.3.3.1. Operators
|
|
|
|
The following operators may be used in expressions:
|
|
|
|
Operator Meaning
|
|
|
|
& Bitwise AND
|
|
* Multiplication
|
|
+ Addition
|
|
- Subtraction
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 39
|
|
|
|
.and. Bitwise AND
|
|
.eq. Equality test
|
|
.gt. Signed greater than
|
|
.high. Hi byte of operand
|
|
.low. Low byte of operand
|
|
.lt. Signed less than
|
|
.mod. Modulus
|
|
.not. Bitwise complement
|
|
.or. Bitwise or
|
|
.shl. Shift left
|
|
.shr. Shift right
|
|
.ult. Unsigned less than
|
|
.ugt. Unsigned greater than
|
|
.xor. Exclusive or
|
|
/ Divison
|
|
< Signed less than
|
|
= Equality
|
|
> Signed greater than
|
|
^ Bitwise or
|
|
|
|
|
|
Operators starting with a dot "." should be delimited
|
|
by spaces, thus label .and. 1 is valid but label.and.1 is
|
|
not.
|
|
|
|
12.3.3.2. Relocatability
|
|
|
|
Zas produces object code which is relocatable; this
|
|
means that it is not necessary to specify assembly time
|
|
where the code is to be located in memory. It is possible to
|
|
do so, by use of the ORG pseudo-op, however the preferred
|
|
approach is to use program sections or psects. A psect is a
|
|
named section of the program, in which code or data may be
|
|
defined at assembly time. All parts of a psect will be
|
|
loaded contiguously into memory, even if they were defined
|
|
in separate files, or in the same file but separated by code
|
|
for another psect. For example, the following code will load
|
|
some executable instructions into the psect named text, and
|
|
some data bytes into the data psect.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 40 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
psect text, global
|
|
|
|
alabel:
|
|
ld hl,astring
|
|
call putit
|
|
ld hl,anotherstring
|
|
|
|
psect data, global
|
|
astring:
|
|
defm 'A string of chars'
|
|
defb 0
|
|
anotherstring:
|
|
defm 'Another string'
|
|
defb 0
|
|
|
|
psect text
|
|
|
|
putit:
|
|
ld a,(hl)
|
|
or a
|
|
ret z
|
|
call outchar
|
|
inc hl
|
|
jr putit
|
|
|
|
|
|
Note that even though the two blocks of code in the
|
|
text psect are separated by a block in the data psect, the
|
|
two text psect blocks will be contiguous when loaded by the
|
|
linker. The instruction "ld hl,anotherstring" will fall
|
|
through to the label "putit:" during execution. The actual
|
|
location in memory of the two psects will be determined by
|
|
the linker. See the linker manual for information on how
|
|
psect addresses are determined.
|
|
|
|
A label defined in a psect is said to be relocatable,
|
|
that is, its actual memory address is not determined at
|
|
assembly time. Note that this does not apply if the label is
|
|
in the default (unnamed) psect, or in a psect declared abso-
|
|
lute (see the PSECT pseudo-op description below). Any
|
|
labels declared in an absolute psect will be absolute, that
|
|
is their address will be determined by the assembler.
|
|
|
|
With the version of ZAS supplied with version 7 or
|
|
later of HI-TECH C, relocatable expressions may be combined
|
|
freely in expressions. Older versions of ZAS allowed only
|
|
limited arithmetic on relocatable expressions.
|
|
|
|
12.3.4. Pseudo-ops
|
|
|
|
The pseudo-ops are based on those described in the "Z80
|
|
Assembly Language Handbook", with some additions.
|
|
|
|
12.3.4.1. DEFB, DB
|
|
|
|
This pseudo-op should be followed by a comma-separated
|
|
list of expressions, which will be assembled into sequential
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 41
|
|
|
|
byte locations. Each expression must have a value between
|
|
-128 and 255 inclusive. DB can be used as a synonym for
|
|
DEFB. Example:
|
|
|
|
DEFB 10, 20, 'a', 0FFH
|
|
DB 'hello world',13,10,0
|
|
|
|
|
|
|
|
12.3.4.2. DEFF
|
|
|
|
This pseudo-op assembles floating point constants into
|
|
32 bit HI-TECH C format floating point constants. For exam-
|
|
ple:
|
|
|
|
pi: DEFF 3.14159
|
|
|
|
|
|
|
|
12.3.4.3. DEFW
|
|
|
|
This operates in a similar fashion to DEFB, except that
|
|
it assembles expressions into words, without the value res-
|
|
triction. Example:
|
|
|
|
DEFW -1, 3664H, 'A', 3777Q
|
|
|
|
|
|
|
|
12.3.4.4. DEFS
|
|
|
|
Defs reserves memory locations without initializing
|
|
them. Its operand is an absolute expression, representing
|
|
the number of bytes to be reserved. This expression is
|
|
added to the current location counter. Note however that
|
|
locations reserved by DEFS may be initialized to zero by the
|
|
linker if the reserved locations are in the middle of the
|
|
program. Example:
|
|
|
|
DEFS 20h ;reserve 32 bytes of memory
|
|
|
|
|
|
|
|
12.3.4.5. EQU
|
|
|
|
Equ sets the value of a symbol on the left of EQU to
|
|
the expression on the right. It is illegal to set the value
|
|
of a symbol which is already defined. Example:
|
|
|
|
SIZE equ 46
|
|
|
|
|
|
|
|
12.3.4.6. DEFL
|
|
|
|
This is identical to EQU except that it may redefine
|
|
existing symbols. Example:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 42 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
SIZE defl 48
|
|
|
|
|
|
|
|
12.3.4.7. DEFM
|
|
|
|
Defm should be followed by a string of characters,
|
|
enclosed in single quotes. The ASCII values of these char-
|
|
acters are assembled into successive memory locations.
|
|
Example:
|
|
|
|
DEFM 'A string of funny *@$ characters'
|
|
|
|
|
|
|
|
12.3.4.8. END
|
|
|
|
The end of an assembly is signified by the end of the
|
|
source file, or the END pseudo-op. The END pseudo-op may
|
|
optionally be followed by an expression which will define
|
|
the start address of the program. This is not actually use-
|
|
ful for CP/M. Only one start address may be defined per pro-
|
|
gram, and the linker will complain if there are more. Exam-
|
|
ple:
|
|
|
|
END somelabel
|
|
|
|
|
|
|
|
12.3.4.9. COND, IF, ELSE, ENDC
|
|
|
|
Conditional assembly is introduced by the COND pseudo-
|
|
op. The operand to COND must be an absolute expression. If
|
|
its value is false (zero) the code following the COND up to
|
|
the corresponding ENDC pseudo-op will not be assembled.
|
|
COND/ENDC pairs may be nested. IF may be used as a synonym
|
|
for COND. The ELSE pseudo operation may be included within
|
|
a COND/ENDC block, for example:
|
|
|
|
IF CPM
|
|
call 5
|
|
ELSE
|
|
call os_func
|
|
ENDC
|
|
|
|
|
|
|
|
12.3.4.10. ELSE
|
|
|
|
See COND.
|
|
|
|
12.3.4.11. ENDC
|
|
|
|
See COND.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 43
|
|
|
|
12.3.4.12. ENDM
|
|
|
|
See MACRO.
|
|
|
|
12.3.4.13. PSECT
|
|
|
|
This pseudo-op allows specification of relocatable pro-
|
|
gram sections. Its arguments are a psect name, optionally
|
|
followed by a list of psect flags. The psect name is a sym-
|
|
bol constructed according to the same rules as for labels,
|
|
however a psect may have the same name as a label without
|
|
conflict. Psect names are recognized only after a PSECT
|
|
pseudo-op. The psect flags are as follows:
|
|
|
|
ABS Psect is absolute
|
|
|
|
GLOBAL Psect is global
|
|
|
|
LOCAL Psect is not global
|
|
|
|
OVRLD Psect is to be overlapped by linker
|
|
|
|
PURE Psect is to be read-only
|
|
|
|
|
|
If a psect is global, the linker will merge it with any
|
|
other global psects of the same name from other modules.
|
|
Local psects will be treated as distinct from any other
|
|
psect from another module. Psects are global by default.
|
|
|
|
By default the linker concatenates code within a psect
|
|
from various modules. If a psect is specified as OVRLD, the
|
|
linker will overlap each module's contribution to that
|
|
psect. This is particularly useful when linking modules
|
|
which initialize e.g. interrupt vectors.
|
|
|
|
The PURE flag instructs the linker that the psect is to
|
|
be made read-only at run time. The usefulness of this flag
|
|
depends on the ability of the linker to enforce the require-
|
|
ment. CP/M fails miserably in this regard.
|
|
|
|
The ABS flag makes a psect absolute. The psect will be
|
|
loaded at zero. This is useful for statically initializing
|
|
interrupt vectors and jump tables. Examples:
|
|
|
|
|
|
PSECT text, global, pure
|
|
PSECT data, global
|
|
PSECT vectors, ovrld
|
|
|
|
|
|
|
|
12.3.4.14. GLOBAL
|
|
|
|
Global should be followed by one more symbols (comma
|
|
separated) which will be treated by the assembler as global
|
|
symbols, either internal or external depending on whether
|
|
they are defined within the current module or not. Example:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 44 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
GLOBAL label1, putchar, _printf
|
|
|
|
|
|
|
|
12.3.4.15. ORG
|
|
|
|
An ORG pseudo-op sets the current psect to the default
|
|
(absolute) psect, and the location counter to its operand,
|
|
which must be an absolute expression. Example:
|
|
|
|
ORG 100H
|
|
|
|
|
|
|
|
12.3.4.16. MACRO
|
|
|
|
This pseudo-op defines a macro. It should be either
|
|
preceded or followed by the macro name, then optionally fol-
|
|
lowed by a comma-separated list of formal parameters. The
|
|
lines of code following the MACRO pseudo-op up to the next
|
|
ENDM pseudo-op will be stored as the body of the macro. The
|
|
macro name may subsequently be used in the opcode part of an
|
|
assembler statement, followed by actual parameters. The text
|
|
of the body of the macro will be substituted at that point,
|
|
with any use of the formal parameters substituted with the
|
|
corresponding actual parameter. For example:
|
|
|
|
print MACRO string
|
|
psect data
|
|
999: db string,'$'
|
|
psect text
|
|
ld de,999b
|
|
ld c,9
|
|
call 5
|
|
ENDM
|
|
|
|
|
|
|
|
When used, this macro will expand to the 3 instructions
|
|
in the body of the macro, with the actual parameters substi-
|
|
tuted for func and arg. Thus
|
|
|
|
print 'hello world'
|
|
|
|
|
|
expands to
|
|
|
|
psect data
|
|
999: db 'hello world','$'
|
|
psect text
|
|
ld de,999b
|
|
ld c,9
|
|
call 5
|
|
|
|
|
|
|
|
Macro arguments can be enclosed in angle brackets ('<'
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 45
|
|
|
|
and '>') to pass arbitrary text including delimiter charac-
|
|
ters like commas as a single argument. For example, suppose
|
|
you wanted to use the print macro defined above to print a
|
|
string which includes the carriage return and linefeed char-
|
|
acters. The macro invocation:
|
|
|
|
print 'hello world',13,10
|
|
|
|
|
|
would fail because 13 and 10 are treated as extra arguments
|
|
and ignored. In order to pass a string which includes commas
|
|
as a single argument, you could write:
|
|
|
|
print <'hello world',13,10>
|
|
|
|
|
|
which would cause the text 'hello world',13,10 to be passed
|
|
through as a single argument. This would expand to the fol-
|
|
lowing code:
|
|
|
|
psect data
|
|
999: db 'hello world',13,10,'$'
|
|
psect text
|
|
ld de,999b
|
|
ld c,9
|
|
call 5
|
|
|
|
|
|
|
|
ZAS supports two forms of macro declaration for compa-
|
|
tibility with older versions of ZAS and other Z80 assem-
|
|
blers. The macro name may be declared either in the label
|
|
field before the MACRO pseudo-op, or in the operand field
|
|
after the MACRO pseudo-op. Thus these two MACRO declara-
|
|
tions are equivalent:
|
|
|
|
bdos MACRO func,arg
|
|
ld de,arg
|
|
ld c,func
|
|
call 5
|
|
ENDM
|
|
|
|
and
|
|
|
|
MACRO bdos,func,arg
|
|
ld de,arg
|
|
ld c,func
|
|
call 5
|
|
ENDM
|
|
|
|
|
|
|
|
12.3.4.17. LOCAL
|
|
|
|
The LOCAL pseudo-op allows unique labels to be defined
|
|
for each expansion of a macro. Any symbols listed after the
|
|
LOCAL directive will have a unique assembler-generated sym-
|
|
bol substituted for them when the macro is expanded. For
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 46 HI-TECH C USER'S MANUAL
|
|
|
|
example:
|
|
|
|
copy MACRO source,dest,count
|
|
LOCAL nocopy
|
|
push af
|
|
push bc
|
|
ld bc,source
|
|
ld a,b
|
|
or c
|
|
jr z,nocopy
|
|
push de
|
|
push hl
|
|
ld de,dest
|
|
ld hl,source
|
|
ldir
|
|
pop hl
|
|
pop de
|
|
nocopy: pop bc
|
|
pop af
|
|
ENDM
|
|
|
|
|
|
when expanded will include a unique assembler generated
|
|
label in place of nocopy. For example, copy
|
|
(recptr),buf,(recsize) will expand to:
|
|
|
|
push af
|
|
push bc
|
|
ld bc,(recsize)
|
|
ld a,b
|
|
or c
|
|
jr z,??0001
|
|
push de
|
|
push hl
|
|
ld de,buf
|
|
ld hl,(recptr)
|
|
ldir
|
|
pop hl
|
|
pop de
|
|
??0001: pop bc
|
|
pop af
|
|
|
|
if invoked a second time, the label nocopy would expand to
|
|
??0002.
|
|
|
|
12.3.4.18. REPT
|
|
|
|
The REPT pseudo-op defines a temporary macro which is
|
|
then expanded a number of times, as determined by its argu-
|
|
ment. For example:
|
|
|
|
REPT 3
|
|
ld (hl),0
|
|
inc hl
|
|
ENDM
|
|
|
|
|
|
will expand to
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 47
|
|
|
|
|
|
ld (hl),0
|
|
inc hl
|
|
ld (hl),0
|
|
inc hl
|
|
ld (hl),0
|
|
inc hl
|
|
|
|
|
|
|
|
12.3.5. IRP and IRPC
|
|
|
|
The IRP and IRPC directives are similar to REPT, how-
|
|
ever instead of repeating the block a fixed number of times
|
|
it is repeated once for each member of an argument list. In
|
|
the case of IRP the list is a conventional macro argument
|
|
list, in the case of IRPC it is successive characters from a
|
|
string. For example:
|
|
|
|
IRP string,<'hello world',13,10>,'arg2'
|
|
LOCAL str
|
|
psect data
|
|
str: db string,'$'
|
|
psect text
|
|
ld c,9
|
|
ld de,str
|
|
call 5
|
|
ENDM
|
|
|
|
|
|
would expand to
|
|
|
|
psect data
|
|
??0001: db 'hello world',13,10,'$'
|
|
psect text
|
|
ld c,9
|
|
ld de,??0001
|
|
call 5
|
|
psect data
|
|
??0002: db 'arg2','$'
|
|
psect text
|
|
ld c,9
|
|
ld de,??0002
|
|
call 5
|
|
|
|
|
|
Note the use of LOCAL labels and angle brackets in the same
|
|
manner as with conventional macros.
|
|
|
|
IRPC is best demonstrated using the following example:
|
|
|
|
IRPC char,ABC
|
|
ld c,2
|
|
ld e,'char'
|
|
call 5
|
|
ENDM
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 48 HI-TECH C USER'S MANUAL
|
|
|
|
will expand to:
|
|
|
|
ld c,2
|
|
ld e,'A'
|
|
call 5
|
|
ld c,2
|
|
ld e,'B'
|
|
call 5
|
|
ld c,2
|
|
ld e,'C'
|
|
call 5
|
|
|
|
|
|
|
|
12.3.6. Extended Condition Codes
|
|
|
|
The assembler recognizes several additional condition
|
|
codes. These are:
|
|
|
|
_________________________________________________
|
|
| Code| Equivalent| Meaning |
|
|
| alt | m | Arithmetic less than |
|
|
| llt | c | Logical less than |
|
|
| age | p | Arithmetic greater or equal|
|
|
| lge | nc | Logical greater or equal |
|
|
| di | | Use after ld a,i for test-|
|
|
| ei | | ing state of interrupt|
|
|
| | | enable flag - enabled or|
|
|
||______||_____________||__d_i_s_a_b_l_e_d__r_e_s_p_e_c_t_i_v_e_l_y_._______||
|
|
|
|
|
|
12.4. Assembler Directives
|
|
|
|
An assembler directive is a line in the source file
|
|
which produces no code, but rather which modifies the
|
|
behaviour of the assembler. Each directive is recognized by
|
|
the presence of an asterisk in the first column of the line,
|
|
followed immediately by a word, only the first character of
|
|
which is looked at. the line containing the directive itself
|
|
is never listed. The directives are:
|
|
|
|
*Title
|
|
Use the text following the directive as a title for the
|
|
listing.
|
|
|
|
*Heading
|
|
Use the text following the directive as a subtitle for
|
|
the listing; also causes an *Eject.
|
|
|
|
*List
|
|
May be followed by ON or OFF to turn listing on or off
|
|
respectively. Note that this directive may be used
|
|
inside a macro or include file to control listing of
|
|
that macro or include file. The previous listing state
|
|
will be restored on exit from the macro or include
|
|
file.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 49
|
|
|
|
*Include
|
|
The file named following the directive will be included
|
|
in the assembly at that point.
|
|
|
|
*Eject
|
|
A new page will be started in the listing at that
|
|
point. A form feed character in the source will have
|
|
the same effect.
|
|
|
|
Some examples of the use of these directives:
|
|
|
|
|
|
*Title Widget Control Program
|
|
*Heading Initialization Phase
|
|
|
|
*Include widget.i
|
|
|
|
|
|
|
|
12.5. Diagnostics
|
|
|
|
An error message will be written on the standard error
|
|
stream for each error encountered in the assembly. This mes-
|
|
sage identifies the file name and line number and describes
|
|
the error. In addition the line in the listing where the
|
|
error occurred will be flagged with a single character to
|
|
indicate the error. The characters and the corresponding
|
|
messages are:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 50 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
|
|
A: Absolute expression required
|
|
|
|
B: Bad arg to *L
|
|
Bad arg to IM
|
|
Bad bit number
|
|
Bad character constant
|
|
Bad jump condition
|
|
|
|
D: Directive not recognized
|
|
Digit out of range
|
|
|
|
E: EOF inside conditional
|
|
Expression error
|
|
|
|
G: Garbage after operands
|
|
Garbage on end of line
|
|
|
|
I: Index offset too large
|
|
|
|
J: Jump target out of range
|
|
|
|
L: Lexical error
|
|
|
|
M: Multiply defined symbol
|
|
|
|
O: Operand error
|
|
|
|
P: Phase error
|
|
Psect may not be local and global
|
|
|
|
R: Relocation error
|
|
|
|
S: Size error
|
|
Syntax error
|
|
|
|
U: Undefined symbol
|
|
Undefined temporary label
|
|
Unterminated string
|
|
|
|
|
|
12.6. Z80/Z180/64180 Instruction Set
|
|
|
|
The remainder of this chapter is devoted to a complete
|
|
instruction set listing for the Z80, Z180, 64180 and NSC800
|
|
processors. The Z180 and 64180 will execute all Z80
|
|
instructions, although the timing is different.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 51
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 52 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 53
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 54 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 55
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 56 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 57
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 58 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 59
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 60 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 61
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 62 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 63
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 64 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 65
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 66 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 67
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 68 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 69
|
|
|
|
|
|
13. Linker Reference Manual
|
|
|
|
|
|
HI-TECH C incorporates a relocating assembler and
|
|
linker to permit separate compilation of C source files.
|
|
This means that a program may be divided into several source
|
|
files, each of which may be kept to a manageable size for
|
|
ease of editing and compilation, then each object file com-
|
|
piled separately and finally all the object files linked
|
|
together into a single executable program.
|
|
|
|
The assembler is described in the machine-specific
|
|
manual. This appendix describes the theory behind and the
|
|
usage of the linker.
|
|
|
|
13.1. Relocation and Psects
|
|
|
|
The fundamental task of the linker is to combine
|
|
several relocatable object files into one. The object files
|
|
are said to be relocatable since the files have sufficient
|
|
information in them so that any references to program or
|
|
data addresses (e.g. the address of a function) within the
|
|
file may be adjusted according to where the file is ulti-
|
|
mately located in memory after the linkage process. Thus the
|
|
file is said to be relocatable. Relocation may take two
|
|
basic forms; relocation by name, i.e. relocation by the
|
|
ultimate value of a global symbol, or relocation by psect,
|
|
i.e. relocation by the base address of a particular section
|
|
of code, for example the section of code containing the
|
|
actual excutable instructions.
|
|
|
|
13.1.1. Program Sections
|
|
|
|
Any object file may contain bytes to be stored in
|
|
memory in one or more program sections, which will be
|
|
referred to as psects. These psects represent logical group-
|
|
ings of certain types of code bytes in the program. The
|
|
section of the program containing executable instructions is
|
|
normally referred to as the text psect. Other sections are
|
|
the initialized data psect, called simply the data psect,
|
|
and the uninitialized data psect, called the bss psect.
|
|
|
|
In fact the linker will handle any number of psects,
|
|
and in fact more may be used in special applications. How-
|
|
ever the C compiler uses only the three mentioned, and the
|
|
names text, data and bss are simply chosen for identifica-
|
|
tion; the linker assigns no special significance to the name
|
|
of a psect.
|
|
|
|
The difference between the data and bss psects may be
|
|
exemplified by considering two external variables; one is
|
|
initialized to the value 1, and the other is not initial-
|
|
ized. The first will be placed into the data psect, and the
|
|
second in the bss psect. The bss psect is always cleared to
|
|
zeros on startup of the program, thus the second variable
|
|
will be initialized at run time to zero. The first will how-
|
|
ever occupy space in the program file, and will maintain its
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 70 HI-TECH C USER'S MANUAL
|
|
|
|
initialized value of 1 at startup. It is quite possible to
|
|
modify the value of a variable in the data psect during exe-
|
|
cution, however it is better practice not to do so, since
|
|
this leads to more consistent use of variables, and allows
|
|
for restartable and romable programs.
|
|
|
|
The text psect is the section into which all executable
|
|
instructions are placed. On CP/M-80 the text psect will nor-
|
|
mally start at the base of the TPA, which is where execution
|
|
commences. The data psect will normally follow the text
|
|
psect, and the bss will be last. The bss does not occupy
|
|
space in the program (.COM) file. This ordering of psects
|
|
may be overridden by an option to the linker. This is espe-
|
|
cially useful when producing code for special hardware.
|
|
|
|
For MS-DOS and CP/M-86 the psects are ordered in the
|
|
same way, but since the 8086 processor has segment registers
|
|
providing relocation, both the text and data psects start at
|
|
0, even though they will be loaded one after the other in
|
|
memory. This allows 64k code and 64k data and stack. Suffi-
|
|
cient information is placed in the executable file (.EXE or
|
|
.CMD) for the operating system to load the program in
|
|
memory.
|
|
|
|
13.1.2. Local Psects and the Large Model
|
|
|
|
Since for practical purposes the psects are limited to
|
|
64K on the 8086, to allow more than 64K code the compiler
|
|
makes use of local psects. A psect is considered local if
|
|
the .psect directive has a LOCAL flag. Any number of local
|
|
psects may be linked from different modules without being
|
|
combined even if they have the same name. Note however that
|
|
no local psect may have the same name as a global psect.
|
|
|
|
All references to a local psect within the same module
|
|
(or within the same library) will be treated as references
|
|
to the same psect. Between modules however two local psects
|
|
of the same name are treated as distinct. In order to allow
|
|
collective referencing of local psects via the -P option
|
|
(described later) a local psect may have a class name asso-
|
|
ciated with it. This is achieved witht the _C_L_A_S_S flag on the
|
|
.psect directive.
|
|
|
|
13.2. Global Symbols
|
|
|
|
The linker handles only symbols which have been
|
|
declared as global to the assembler. From the C source
|
|
level, this means all names which have storage class exter-
|
|
nal and which are not declared as static. These symbols may
|
|
be referred to by modules other than the one in which they
|
|
are defined. It is the linker's job to match up the defini-
|
|
tion of a global symbol with the references to it.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 71
|
|
|
|
13.3. Operation
|
|
|
|
A command to the linker takes the following form:
|
|
|
|
LINK options files ...
|
|
|
|
|
|
Options is zero or more linker options, each of which
|
|
modifies the behaviour of the linker in some way. Files is
|
|
one or more object files, and zero or more library names.
|
|
The options recognized by the linker are as follows: they
|
|
will be recognized in upper or lower case.
|
|
|
|
-R Leave the output relocatable.
|
|
|
|
-L Retain absolute relocation info. -LM will retain only
|
|
segement relocation information.
|
|
|
|
-I Ignore undefined symbols.
|
|
|
|
-N Sort symbols by address.
|
|
|
|
-Caddr
|
|
Produce a binary output file offset by addr.
|
|
|
|
-S Strip symbol information from the output file.
|
|
|
|
-X Suppress local symbols in the output file.
|
|
|
|
-Z Suppress trivial (compiler-generated) symbols in the
|
|
output file.
|
|
|
|
-Oname
|
|
Call the output file name.
|
|
|
|
-Pspec
|
|
Spec is a psect location specification.
|
|
|
|
-Mname
|
|
Write a link map to the file name.
|
|
|
|
-Usymbol
|
|
Make symbol initially undefined.
|
|
|
|
-Dfile
|
|
Write a symbol file.
|
|
|
|
-Wwidth
|
|
Specify map width.
|
|
|
|
Taking each of these in turn:
|
|
|
|
The -R option will instruct the linker to leave the
|
|
output file (as named by a -O option, or l.obj by default)
|
|
relocatable. This is normally because there are further
|
|
files to be linked in, and the output of this link will be
|
|
used as input to the linker subsequently. Without this
|
|
option, the linker will make the output file absolute, that
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 72 HI-TECH C USER'S MANUAL
|
|
|
|
is with all relocatable addresses made into absolute refer-
|
|
ences. This option may not be used with the -L or -C
|
|
options.
|
|
|
|
The -L option will cause the linker to output null
|
|
relocation information even though the file will be abso-
|
|
lute. This information allows self-relocating programs to
|
|
know what addresses must be relocated at run time. This
|
|
option is not usable with the -C option. In order to create
|
|
an executable file (i.e. a .COM file) the program objtohex
|
|
must be used. If a -LM option is used, only segment reloca-
|
|
tion information will be retained. This is used in conjuc-
|
|
tion with the large memory model. Objtohex will use the
|
|
relocation information (when invoked with a -L flag) to
|
|
insert segment relocation addresses into the executable
|
|
file.
|
|
|
|
The -I option is used when it is desired to link code
|
|
which contains symbols which are not defined in any module.
|
|
This is normally only used during top-down program develop-
|
|
ment, when routines are referenced in code written before
|
|
the routines themselves have been coded.
|
|
|
|
When obtaining a link map via the -M option, the symbol
|
|
table is by default sorted in order of symbol name. To sort
|
|
in order of address, the -N option may be used.
|
|
|
|
The output of the linker is by default an object file.
|
|
To create an executable program, this must be converted into
|
|
an executable image. For CP/M this is a .COM file, which is
|
|
simply an image of the executable program as it should
|
|
appear in memory, starting at location 100H. The linker will
|
|
produce such a file with the -C100H option. File formats for
|
|
other applications requiring an image binary file may also
|
|
be produced with the -C option. The address following the
|
|
-C may be given in decimal (default), octal (by using o or O
|
|
suffix) or hexadecimal (by using an h or H suffix).
|
|
|
|
Note that because of the complexity of the executable
|
|
file formats for MS-DOS and CP/M-86, LINK will not produce
|
|
these (.EXE and .CMD resp.) formats directly. The compiler
|
|
automatically runs OBJTOHEX with appropriate options to gen-
|
|
erate the correct file format.
|
|
|
|
The -S, -X and -Z options, which are meaningless when
|
|
the -C option is used, will strip respectively all symbols,
|
|
all local symbols or all trivial local symbols from the out-
|
|
put file. Trivial symbols are symbols produced by the com-
|
|
piler, and have the form of one of a set of alphabetic char-
|
|
acters followed by a digit string.
|
|
|
|
The default output file name is _l._o_b_j, or _l._b_i_n when
|
|
the -C option is used. This may be overridden by the -O_n_a_m_e
|
|
option. The output file will be called _n_a_m_e in this
|
|
instance. Note that no suffix is appended to the name; the
|
|
file will be called exactly the argument to the option.
|
|
|
|
For certain specialized applications, e.g. producing
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 73
|
|
|
|
code for an embedded microprocessor, it is necessary to
|
|
specify to the linker at what address the various psects
|
|
should be located. This is accomplished with the -P option.
|
|
It is followed by a specification consisting of a comma-
|
|
separated list of psect names, each with an optional address
|
|
specification. In the absence of an address specification
|
|
for a psect listed, it will be concatenated with the previ-
|
|
ous psect. For example
|
|
|
|
-Ptext=0c000h,data,bss=8000h
|
|
|
|
|
|
This will cause the text psect to be located at 0C000H,
|
|
the data psect to start at the end of the text psect, and
|
|
the bss psect to start at 8000H. This may be for a processor
|
|
with ROM at 0C000H and RAM at 8000H.
|
|
|
|
Where the link address, that is the address at which
|
|
the code will be addressed at execution time, and the load
|
|
address, that is the address offset within the output file,
|
|
are different (e.g for the 8086) it is possible to specify
|
|
the load address separately from the link address. For exam-
|
|
ple:
|
|
|
|
-Ptext=100h/0,data=0C000h/
|
|
|
|
|
|
This specification will cause the text segment to be
|
|
linked for execution at 100h, but loaded in the output file
|
|
at 0, while the data segment will be linked for 0C000h, but
|
|
loaded contiguously with the text psect in the file. Note
|
|
that if the slash (`/') is omitted, the load address is the
|
|
same as the link address, while if the slash is supplied,
|
|
but not followed by an address, the psect will be loaded
|
|
after the previous psect.
|
|
|
|
In order to specify link and load addresses for local
|
|
psects, the group name to which the psects belong may be
|
|
used in place of a global psect name. The local psects will
|
|
then have a link address as specified in the -P option, and
|
|
load addresses incrementing upwards from the specified load
|
|
address.
|
|
|
|
The -Mname option requests a link map, containing sym-
|
|
bol table and module load address information to be written
|
|
onto the file name. If name is omitted, the map will be
|
|
written to standard output. -W may be used to specify the
|
|
desired width of the map.
|
|
|
|
The -U option allows the specification to the linker of
|
|
a symbol which is to be initially entered into the symbol
|
|
table as undefined. This is useful when loading entirely
|
|
from libraries. More than one -U flag may be used.
|
|
|
|
If it is desired to use the debugger on the program
|
|
being linked, it is useful to produce a symbol file. The
|
|
-D_f_i_l_e option will write such a symbol file onto the named
|
|
_f_i_l_e, or _l._s_y_m if no file is given. The symbol file consists
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 74 HI-TECH C USER'S MANUAL
|
|
|
|
of a list of addresses and symbols, one per line.
|
|
|
|
13.4. Examples
|
|
|
|
Here are some examples of using the linker. Note how-
|
|
ever that in the normal case it is not necessary to invoke
|
|
the linker explicitly, since it is invoked automatically by
|
|
the C command.
|
|
|
|
LINK -MMAP -C100H START.OBJ MAIN.OBJ A:LIBC.LIB
|
|
|
|
|
|
This command links the files start.obj and main.obj
|
|
with the library a:libc.lib. Only those modules that are
|
|
required from the library will be in fact linked in. The
|
|
output is to be in .COM format, placed in the default file
|
|
l.bin. A map is to be written to the file of the name map.
|
|
Note that the file start.obj should contain startup code,
|
|
and in fact the lowest address code in that file will be
|
|
executed when the program is run, since it will be at 100H.
|
|
|
|
LINK -X -R -OX.OBJ FILE1.OBJ FILE2.OBJ A:LIBC.LIB
|
|
|
|
|
|
The files file1.obj and file2.obj will be linked with
|
|
any necessary routines from a:libc.lib and left in the file
|
|
x.obj. This file will remain relocatable. Undefined symbols
|
|
will not cause an error. The file x.obj will probably later
|
|
be the object of another link invocation. All local symbols
|
|
will be stripped from the output file, thus saving space.
|
|
|
|
13.5. Invoking the Linker
|
|
|
|
The linker is called LINK, and normally resides on the
|
|
A: drive, under CP/M, or in the directory A:\HITECH\ under
|
|
MS-DOS. It may be invoked with no arguments, in which case
|
|
it will prompt for input from standard input. If the stan-
|
|
dard input is a file, no prompts will be printed. The input
|
|
supplied in this manner may contain lower case, whereas CP/M
|
|
converts the entire command line to upper case by default.
|
|
This is useful with the -U and -P options. This manner of
|
|
invocation is generally useful if the number of arguments to
|
|
LINK is large. Even if the list of files is too long to fit
|
|
on one line, continuation lines may be included by leaving a
|
|
backslash ('\') at the end of the preceding line. In this
|
|
fashion, LINK commands of almost unlimited length may be
|
|
issued.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 75
|
|
|
|
|
|
14. Librarian
|
|
|
|
|
|
The librarian program, LIBR, has the function of com-
|
|
bining several object files into a single file known as a
|
|
library. The purposes of combining several such object
|
|
modules are several.
|
|
|
|
a. fewer files to link
|
|
b. faster access
|
|
c. uses less disk space
|
|
|
|
|
|
In order to make the library concept useful, it is
|
|
necessary for the linker to treat modules in a library dif-
|
|
ferently from object files. If an object file is specified
|
|
to the linker, it will be linked into the final linked
|
|
module. A module in a library, however, will only be linked
|
|
in if it defines one or more symbols previously known, but
|
|
not defined, to the linker. Thus modules in a library will
|
|
be linked only if required. Since the choice of modules to
|
|
link is made on the first pass of the linker, and the
|
|
library is searched in a linear fashion, it is possible to
|
|
order the modules in a library to produce special effects
|
|
when linking. More will be said about this later.
|
|
|
|
14.1. The Library Format
|
|
|
|
The modules in a library are basically just con-
|
|
catenated, but at the beginning of a library is maintained a
|
|
directory of the modules and symbols in the library. Since
|
|
this directory is smaller than the sum of the modules, the
|
|
linker is speeded up when searching a library since it need
|
|
read only the directory and not all the modules on the first
|
|
pass. On the second pass it need read only those modules
|
|
which are required, seeking over the others. This all minim-
|
|
izes disk i/o when linking.
|
|
|
|
It should be noted that the library format is geared
|
|
exclusively toward object modules, and is not a general pur-
|
|
pose archiving mechanism as is used by some other compiler
|
|
systems. This has the advantage that the format may be
|
|
optimized toward speeding up the linkage process.
|
|
|
|
14.2. Using
|
|
|
|
The librarian program is called LIBR, and the format of
|
|
commands to it is as follows:
|
|
|
|
LIBR k file.lib file.obj ...
|
|
|
|
|
|
Interpreting this, LIBR is the name of the program, k
|
|
is a key letter denoting the function requested of the
|
|
librarian (replacing, extracting or deleting modules, list-
|
|
ing modules or symbols), file.lib is the name of the library
|
|
file to be operated on, and file.obj is zero or more object
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 76 HI-TECH C USER'S MANUAL
|
|
|
|
file names.
|
|
|
|
The key letters are:
|
|
|
|
r replace modules
|
|
d delete modules
|
|
x extract modules
|
|
m list module names
|
|
s list modules with symbols
|
|
|
|
|
|
When replacing or extracting modules, the file.obj
|
|
arguments are the names of the modules to be replaced or
|
|
extracted. If no such arguments are supplied, all the
|
|
modules in the library will be replaced or extracted respec-
|
|
tively. Adding a file to a library is performed by request-
|
|
ing the librarian to replace it in the library. Since it is
|
|
not present, the module will be appended to the library. If
|
|
the r key is used and the library does not exist, it will be
|
|
created.
|
|
|
|
Under the d keyletter, the named object files will be
|
|
deleted from the library. In this instance, it is an error
|
|
not to give any object file names.
|
|
|
|
The m and s keyletters will list the named modules and,
|
|
in the case of the s keyletter, the symbols defined or
|
|
referenced within (global symbols only are handled by the
|
|
librarian). As with the r and x keyletters, an empty list of
|
|
modules means all the modules in the library.
|
|
|
|
14.3. Examples
|
|
|
|
Here are some examples of usage of the librarian.
|
|
|
|
LIBR m file.lib
|
|
List all modules in the library file.lib.
|
|
|
|
LIBR s file.lib a.obj b.obj c.obj
|
|
List the global symbols in the modules a.obj, b.obj and
|
|
c.obj
|
|
|
|
LIBR r file.lib 1.obj 2.obj
|
|
Replace the module 1.obj in the file file.lib with the
|
|
contents of the object file 1.obj, and repeat for
|
|
2.obj. If the object module is not already present in
|
|
the library, append it to the end.
|
|
|
|
LIBR x file.lib
|
|
Extract, without deletion, all the modules in file.lib
|
|
and write them as object files on disk.
|
|
|
|
LIBR d file.lib a.obj b.obj 2.obj
|
|
Delete the object modules a.obj, b.obj and 2.obj from
|
|
the library file.lib.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 77
|
|
|
|
14.4. Supplying Arguments
|
|
|
|
Since it is often necessary to supply many object file
|
|
arguments to LIBR, and command lines are restricted to 127
|
|
characters by CP/M and MS-DOS, LIBR will accept commands
|
|
from standard input if no command line arguments are given.
|
|
If the standard input is attached to the console, LIBR will
|
|
prompt. Multiple line input may be given by using a
|
|
backslash as a continuation character on the end of a line.
|
|
If standard input is redirected from a file, LIBR will take
|
|
input from the file, without prompting. For example:
|
|
|
|
LIBR
|
|
libr> r file.lib 1.obj 2.obj 3.obj \
|
|
libr> 4.obj 5.obj 6.obj
|
|
|
|
will perform much the same as if the .obj files had been
|
|
typed on the command line. The libr> prompts were printed by
|
|
LIBR itself, the remainder of the text was typed as input.
|
|
|
|
LIBR <lib.cmd
|
|
|
|
|
|
Libr will read input from lib.cmd, and execute the com-
|
|
mand found therein. This allows a virtually unlimited length
|
|
command to be given to LIBR.
|
|
|
|
14.5. Listing Format
|
|
|
|
A request to LIBR to list module names will simply pro-
|
|
duce a list of names, one per line, on standard output. The
|
|
s keyletter will produce the same, with a list of symbols
|
|
after each module name. Each symbol will be preceded by the
|
|
letter D or U, representing a definition or reference to the
|
|
symbol respectively. The -W option may be used to determine
|
|
the width of the paper for this operation. For example LIBR
|
|
-w80 s file.lib will list all modules in file.lib with their
|
|
global symbols, with the output formatted for an 80 column
|
|
printer or display.
|
|
|
|
14.6. Ordering of Libraries
|
|
|
|
The librarian creates libraries with the modules in the
|
|
order in which they were given on the command line. When
|
|
updating a library the order of the modules is preserved.
|
|
Any new modules added to a library after it has been created
|
|
will be appended to the end.
|
|
|
|
The ordering of the modules in a library is significant
|
|
to the linker. If a library contains a module which refer-
|
|
ences a symbol defined in another module in the same
|
|
library, the module defining the symbol should come after
|
|
the module referencing the symbol.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 78 HI-TECH C USER'S MANUAL
|
|
|
|
14.7. Error Messages
|
|
|
|
Libr issues various error messages, most of which
|
|
represent a fatal error, while some represent a harmless
|
|
occurence which will nonetheless be reported unless the -w
|
|
option was used. In this case all warning messages will be
|
|
suppressed.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 79
|
|
|
|
|
|
15. Objtohex
|
|
|
|
|
|
The HI-TECH linker is capable of producing simple
|
|
binary files, or object files as output. Any other format
|
|
required must be produced by running the utility program
|
|
OBJTOHEX. This allows conversion of object files as pro-
|
|
duced by the linker into a variety of different formats,
|
|
including various hex formats. The program is invoked thus:
|
|
|
|
OBJTOHEX options inputfile outputfile
|
|
|
|
|
|
All of the arguments are optional. If outputfile is
|
|
ommitted it defaults to l.hex or l.bin depending on whether
|
|
the -b option is used. The inputfile defaults to l.obj.
|
|
|
|
The options are:
|
|
|
|
-B_a_d_d_r
|
|
Produce a binary image output. This is similar to the
|
|
-C option of the linker. If addr is supplied, the
|
|
start of the image file will be offset by addr. If addr
|
|
is omitted, the first byte in the file will be the
|
|
lowest byte initialized. Addr may be given in decimal,
|
|
octal or hexadecimal. The default radix is decimal, and
|
|
suffix letters of o or O indicate octal, and h or H
|
|
indicate hex. Thus -B100H will produce a file in .COM
|
|
format.
|
|
|
|
-I Include symbol records in the Intel format hex output.
|
|
Each symbol record has a form similar to an object
|
|
record, but with a different record type. The data
|
|
bytes in the record are the symbol name, and the
|
|
address is the value of the symbol. This is useful for
|
|
downloading to ROM debuggers.
|
|
|
|
-C Read a checksum specification from the standard input.
|
|
The checksum specification is described below. Typi-
|
|
cally the specification will be in a file.
|
|
|
|
-E_s_t_a_c_k
|
|
This option produces an MS-DOS .EXE format file. The
|
|
optional stack argument will determine the maximum
|
|
stack size the program will be allocated on execution.
|
|
By default the program will be allocated the maximum
|
|
stack available, up to the limit of 64K data. If a
|
|
stack argument is supplied, the stack size will not
|
|
exceed the argument. This is useful to limit the amount
|
|
of memory a program will use. The stack argument takes
|
|
the same form as the argument to -B above.
|
|
|
|
-8_s_t_a_c_k
|
|
This option will produce a CP/M-86 .CMD file. The stack
|
|
argument is the same as for the -E option.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 80 HI-TECH C USER'S MANUAL
|
|
|
|
-A_s_t_a_c_k
|
|
This is used when producing a.out format files for unix
|
|
systems (specifically Venix-86). If the stack argument
|
|
is zero, the size of the data segment will be 64k, oth-
|
|
erwise the stack will be placed below the data segment,
|
|
and its size set to stack. This must be co-ordinated
|
|
with appropriate arguments to the -p option of the
|
|
linker.
|
|
|
|
-M This flag will instruct objtohex to produce Motorola
|
|
'S' format hex output.
|
|
|
|
-L This option is used when producing large model pro-
|
|
grams; the linker will have been used with the -LM
|
|
option to retain segment relocation information in the
|
|
object file. Use of the -L option to objtohex will
|
|
cause it to convert that segment relocation information
|
|
into appropriate data in the executable file for use
|
|
when the program is loaded. Either the operating system
|
|
or the run-time startup code will use the relocation
|
|
data to adjust segment references based on where in
|
|
memory the program is actually loaded. If the -L
|
|
option is followed by a symbol name, then the reloca-
|
|
tion information will be stored at the address
|
|
represented by that symbol in the output file, e.g.
|
|
-L___B_b_s_s will cause it to be stored at the base of the
|
|
bss psect (___B_b_s_s is defined by the linker to be the
|
|
load address of the bss psect). If the special symbol
|
|
_D_o_s__h_d_r is used then the relocation information will be
|
|
stored in the .EXE file header. This is only valid in
|
|
conjunction with the -E option.
|
|
|
|
-S The -S option instructs objtohex to write a symbol
|
|
file. The symbol file name is given after the -S, e.g.
|
|
-S_x_x._s_y_m.
|
|
|
|
Unless another format is specifically requested,
|
|
objtohex will produce a file in Intel hex format. This is
|
|
suitable for down-line loading, PROM programming etc. The
|
|
HP format is useful for transferring code to an HP64000 for
|
|
emulation or PROM programming.
|
|
|
|
The checksum specification allows automated checksum
|
|
calculation. The checksum specification takes the form of
|
|
several lines, each line describing one checksum. The syntax
|
|
of a checksum line is:
|
|
|
|
addr1-addr2 where1-where2 +offset
|
|
|
|
|
|
All of addr1, addr2, where1, where2 and offset are hex
|
|
numbers, without the usual H suffix. Such a specification
|
|
says that the bytes at addr1 through to addr2 inclusive
|
|
should be summed and the sum placed in the locations where1
|
|
through where2 inclusive. For an 8 bit checksum these two
|
|
addresses should be the same. For a checksum stored low byte
|
|
first, where1 should be less than where2, and vice versa.
|
|
The +offset is optional, but if supplied, the value offset
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 81
|
|
|
|
will be used to initialize the checksum. Otherwise it is
|
|
initialized to zero. For example:
|
|
|
|
0005-1FFF 3-4 +1FFF
|
|
|
|
|
|
This will sum the bytes in 5 through 1FFFH inclusive,
|
|
then add 1FFFH to the sum. The 16 bit checksum will be
|
|
placed in locations 3 and 4, low byte in 3. The checksum is
|
|
initialized with 1FFFH to provide protection against an all
|
|
zero rom, or a rom misplaced in memory. A run time check of
|
|
this checksum would add the last address of the rom being
|
|
checksummed into the checksum. For the rom in question, this
|
|
should be 1FFFH. The initialization value may, however, be
|
|
used in any desired fashion.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 82 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
|
|
|
|
Use this page for notes
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 83
|
|
|
|
|
|
16. Cref
|
|
|
|
|
|
The cross reference list utility CREF is used to format
|
|
raw cross-reference information produced by the compiler or
|
|
the assembler into a sorted listing. A raw cross-reference
|
|
file is produced with the -CR option to the compiler. The
|
|
assembler will generate a raw cross-reference file with a -C
|
|
option (Z80 or 8086 assemblers) or by using an OPT CRE
|
|
directive (6800 series assemblers) or a REF control line
|
|
(8096 assembler).. The general form of the CREF command is:
|
|
|
|
CREF options files
|
|
|
|
where _o_p_t_i_o_n_s is zero or more options as described below and
|
|
_f_i_l_e_s is one or more raw cross-reference files. CREF takes
|
|
the following options:
|
|
|
|
-O_o_u_t_f_i_l_e
|
|
Allows specification of the output file name. By
|
|
default the listing will be written to the standard
|
|
output and may be redirected in the usual manner.
|
|
Alternatively using the -O option an output file name
|
|
may be specified, e.g. -O_x_x_x._l_s_t.
|
|
|
|
-P_w_i_d_t_h
|
|
This option allows the specification of the width to
|
|
which the listing is to be formatted, e.g. -P_1_3_2 will
|
|
format the listing for a 132 column printer. The
|
|
default is 80 columns.
|
|
|
|
-L_l_e_n_g_t_h
|
|
Specify the length of the paper on which the listing is
|
|
to be produced, e.g. if the listing is to be printed
|
|
on 55 line paper you would use a -L_5_5 option. The
|
|
default is 66 lines.
|
|
|
|
-X_p_r_e_f_i_x
|
|
The -X option allows the exclusion of symbols from the
|
|
listing, based on a prefix given as argument to -X. For
|
|
example if it was desired to exclude all symbols start-
|
|
ing with the character sequence _x_y_z then the option
|
|
-X_x_y_z would be used. If a digit appears in the charac-
|
|
ter sequence then this will match any digit in the sym-
|
|
bol, e.g. -XX0 would exclude any symbols starting with
|
|
the letter _X followed by a digit.
|
|
|
|
-F -F will exclude from the listing any references from
|
|
files with a full path name. A full path name means
|
|
either: a file name starting with a slash ('/') or
|
|
backslash ('\') or a file name starting with a CP/M
|
|
user number/drive letter prefix, e.g. 0:A:. This is
|
|
intended to force omission from the listing of any sym-
|
|
bol references derived from standard header files, e.g.
|
|
using -F would omit any references from the header file
|
|
STDIO.H.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 84 HI-TECH C USER'S MANUAL
|
|
|
|
-H_s_t_r_i_n_g
|
|
The -H option takes a string as an argument which will
|
|
be used as a header in the listing. The default heading
|
|
is the name of the first raw cross-ref information file
|
|
specified.
|
|
|
|
-S_s_t_o_p_l_i_s_t
|
|
The -S option should have as its argument the name of a
|
|
file containing a list of symbols not to be listed in
|
|
the cross-reference. Multiple stoplists may be supplied
|
|
with multiple -S options.
|
|
|
|
Cref will accept wild card filenames and I/O redirec-
|
|
tion. Long command lines may be supplied by invoking CREF
|
|
with no arguments and typing the command line in response to
|
|
the _c_r_e_f> prompt. A backslash at the end of the line will be
|
|
interpreted to mean that more command lines follow.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 85
|
|
|
|
APPENDIX 1
|
|
|
|
Error Messages
|
|
|
|
|
|
|
|
Error Messages produced by the compiler are listed
|
|
below. Each message is followed by the name of the program
|
|
which produces it, and some further description of what
|
|
causes the message or what to do about it.
|
|
|
|
|
|
|
|
'.' expected after '..' P1
|
|
The ellipsis symbol must have three dots
|
|
|
|
actuals too long CPP
|
|
Reduce length of macro arguments
|
|
|
|
argument list conflicts with prototype P1
|
|
The argument list in a function definition must agree
|
|
with a prototype if one exists
|
|
|
|
argument redeclared P1
|
|
This argument has been declared twice
|
|
|
|
arithmetic overflow in constant expression CGEN
|
|
Evaluation of this constant expression produced an
|
|
arithmetic overflow. This may or may not represent a
|
|
true error.
|
|
|
|
array index out of bounds P1
|
|
An array index expression evaluates to a constant which
|
|
is less than zero or greater than or equal to the
|
|
dimension of the array
|
|
|
|
Assertion CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
attempt to modify const object P1
|
|
An attempt has been made to assign to or otherwise
|
|
modify an object designated as 'const'
|
|
|
|
bad bitfield type P1
|
|
Bitfields must be of type 'int'
|
|
|
|
Bad conval CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
Bad dimensions CGEN
|
|
An array has bad dimensions - probably zero
|
|
|
|
Bad element count expr CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
bad formal CPP
|
|
Check macro defintion syntax
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 86 HI-TECH C USER'S MANUAL
|
|
|
|
bad include syntax CPP
|
|
Use only "" and <> for include files
|
|
|
|
Bad int. code CGEN
|
|
The intermediate code file has been corrupted - can be
|
|
caused by running out of disk space
|
|
|
|
Bad -M option CGEN
|
|
A -M option passed to the code generator is unknown
|
|
|
|
Bad mod '+' for how = c CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
bad object code format LINK
|
|
This file is either corrupted or not a valid object
|
|
file
|
|
|
|
Bad op d to swaplog CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
Bad op n to revlog CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
bad origin format in spec LINK
|
|
An address in a -p option is invalid
|
|
|
|
bad '-p' format LINK
|
|
The -p option provided is invalid
|
|
|
|
Bad pragma c CGEN
|
|
The code generator has been passed a pragma it does not
|
|
know about
|
|
|
|
Bad putwsize CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
bad storage class P1, CGEN
|
|
The speficied storage class is illegal
|
|
|
|
Bad U usage CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
Bit field too large (n bits) CGEN
|
|
A bit field may not be larger than an int
|
|
|
|
Cannot get memory LINK
|
|
The linker has run out of dynamic memory
|
|
|
|
Can't be both far and near P1
|
|
The 'far' and 'near' keywords cannot appear in the same
|
|
type specifier
|
|
|
|
can't be long P1
|
|
Chars and shorts cannot be long
|
|
|
|
can't be register P1
|
|
An extern or static variable may not be register
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 87
|
|
|
|
can't be short P1
|
|
Float and char cannot be short
|
|
|
|
can't be unsigned P1
|
|
Float cannot be unsigned
|
|
|
|
can't call an interrupt function P1
|
|
A function qualified 'interrupt' can only be called by
|
|
hardware, not by an ordinary function call
|
|
|
|
Can't create filename CGEN
|
|
The file specified could not be created
|
|
|
|
Can't create xref file P1
|
|
The cross reference file specified could not be created
|
|
|
|
Can't create CPP
|
|
Output file could not be created
|
|
|
|
Can't create LINK
|
|
The linker cannot create a file
|
|
|
|
Can't find include file CPP
|
|
Check and correct the include file name - spaces are
|
|
not allowed in file names
|
|
|
|
Can't find register for bits CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
Can't generate code for this expression CGEN
|
|
The code generator is unable to generate code for this
|
|
expression - simplifying the expression (e.g. computing
|
|
values into temporary variables) will usually correct
|
|
it, otherwise contact HI-TECH
|
|
|
|
can't have array of functions P1
|
|
You cannot have an array of functions - you can have an
|
|
array of pointers to functions
|
|
|
|
Can't have 'port' variable CGEN
|
|
You cannot declare a variable to be qualified 'port' -
|
|
you can only use port to qualify pointers or typecast
|
|
constant values
|
|
|
|
can't have storage class P1
|
|
A storage class may not appear in a prototype argument
|
|
|
|
can't initialise auto aggregates P1
|
|
You cannot initialise a structure or array inside a
|
|
function unless it is static
|
|
|
|
can't initialize arg P1
|
|
An argument cannot have an initializer
|
|
|
|
can't mix proto and non-proto args P1
|
|
You cannot mix prototype and non-prototype arguments
|
|
even in a function definition
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 88 HI-TECH C USER'S MANUAL
|
|
|
|
Can't open filename CGEN
|
|
The file specified could not be opened for reading
|
|
|
|
Can't open LINK
|
|
The linker cannot open a file
|
|
|
|
Can't seek LINK
|
|
The linker could not seek in file
|
|
|
|
can't take address of register variable P1
|
|
You can't take the address of a variable in a register
|
|
|
|
can't take sizeof func CGEN
|
|
You can't take the size of a function. You can take the
|
|
size of a function call
|
|
|
|
can't take this address P1
|
|
The expression does not have an address
|
|
|
|
'case' not in switch P1
|
|
A 'case' label is permitted only inside a switch
|
|
|
|
char const too long P1
|
|
A character constant may have only one character in it
|
|
|
|
close error (disk space?) P1
|
|
Probably out of disk space
|
|
|
|
common symbol psect conflict LINK
|
|
A common symbol is defined to be in more than one psect
|
|
|
|
constant conditional branch CGEN
|
|
You have a program structure testing a constant expres-
|
|
sion, e.g. while(1). You should substitute for this the
|
|
more efficient for(;;)
|
|
|
|
constant expression required P1
|
|
A constant expression is required in e.g. an array
|
|
dimension
|
|
|
|
constant operand to || or && CGEN
|
|
A logical operator has a constant operand which has
|
|
been optimized out
|
|
|
|
declarator too complex P1
|
|
This declaration is too complex for the compiler to
|
|
handle
|
|
|
|
default case redefined P1
|
|
Only one default case is permitted in a switch
|
|
|
|
'default' not in switch P1
|
|
A 'default' label is permitted only inside a switch
|
|
|
|
digit out of range P1
|
|
An octal constant may not contain 7 or 8, and a decimal
|
|
constant may not contain A-F
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 89
|
|
|
|
dimension required P1
|
|
A dimension is required for all except the most signi-
|
|
ficant in an array declaration
|
|
|
|
Division by zero CGEN
|
|
Attempt to divide by zero in this expression
|
|
|
|
Duplicate case label n CGEN
|
|
There are two case labels in this switch that have the
|
|
same value
|
|
|
|
Duplicate -d flag LINK
|
|
Only one -d flag is allowed to the linker
|
|
|
|
duplicate label P1
|
|
This label is defined twice
|
|
|
|
Duplicate -m flag LINK
|
|
Only one -m flag is allowed to the linker
|
|
|
|
duplicate qualifier P1
|
|
The same qualifier appears more than once in this type
|
|
specifier
|
|
|
|
entry point multiply defined LINK
|
|
A program can only have one entry point (start address)
|
|
|
|
EOF in #asm P1
|
|
End of file was encounterd after #asm and before a
|
|
#endasm was seen
|
|
|
|
Error closing output file CGEN,CPP
|
|
Probably means you have run out of disk space
|
|
|
|
excessive -I file ignored CPP
|
|
Use fewer -I options
|
|
|
|
expand - bad how CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
expand - bad which CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
exponent expected P1
|
|
An exponent is expected after the 'e' or 'E' in a
|
|
floating point constant. The exponent must contain only
|
|
+, - and digits 0-9
|
|
|
|
Expression error CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
expression generates no code CGEN
|
|
This expression has no side effects and thus generates
|
|
no code. It has been optimized out
|
|
|
|
expression syntax P1
|
|
The expression is badly formed
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 90 HI-TECH C USER'S MANUAL
|
|
|
|
expression too complex P1
|
|
The expression has too many nested parantheses or other
|
|
nested constructs
|
|
|
|
Fixup overflow referencing LINK
|
|
The linker has relocated a reference to a psect or sym-
|
|
bol and the relocated address is too big to fit into
|
|
the space, e.g. a relocated one byte address exceeds
|
|
256 or a relocated 16 bit address exceeds 65536
|
|
|
|
float param coerced to double P1
|
|
This float parameter has been converted to double - a
|
|
prototype will override this coercion
|
|
|
|
function() declared implicit int P1
|
|
This function has been called without an explicit
|
|
declaration. It is wise to explicitly declare all func-
|
|
tions, preferably with a prototype. This will avoid
|
|
many potential errors where your program comprises more
|
|
than one source file
|
|
|
|
function does not take arguments P1
|
|
The prototype for this function indicates it takes no
|
|
arguments
|
|
|
|
function or function pointer required P1
|
|
A function identifier or pointer to function is
|
|
required for a function call.
|
|
|
|
functions can't return arrays P1
|
|
A function cannot return an array - it can return a
|
|
pointer
|
|
|
|
functions can't return functions P1
|
|
A function cannot return a function - it can return a
|
|
pointer to function
|
|
|
|
hex digit expected P1
|
|
A hex digit is expected after '0x'
|
|
|
|
identifier is a structure tag P1
|
|
A structure tag has been used in a context where
|
|
another kind of tag is expected, e.g. saying struct
|
|
fred where fred has previously been declared as union
|
|
fred.
|
|
|
|
identifier is a union tag P1
|
|
Similar to the above error
|
|
|
|
identifier is an enum tag P1
|
|
Similar to the above error
|
|
|
|
identifier: large offset CGEN
|
|
Z80 only: This identifier has a large offset from the
|
|
stack frame and thus access to it is inefficient. In a
|
|
function any arrays should be declared after any simple
|
|
variables
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 91
|
|
|
|
identifier redeclared P1
|
|
The identifier has been redeclared with different
|
|
attributes
|
|
|
|
identifier redefined P1
|
|
An identifier has been defined twice
|
|
|
|
If-less else CPP
|
|
Check #if usage
|
|
|
|
If-less endif CPP
|
|
Check #if usage
|
|
|
|
illegal '#' directive P1
|
|
A # directive passed through to the first pass is unk-
|
|
nown. If this occurs with a #include it may be caused
|
|
by a previous include file not having a <CR><LF> or
|
|
newline on the last line.
|
|
|
|
Illegal character in preprocessor if CPP
|
|
Check for strange character
|
|
|
|
illegal character P1
|
|
A character unknown to the compiler has been encoun-
|
|
tered. The value given is the octal value of the char-
|
|
acter
|
|
|
|
illegal conversion between pointer types P1
|
|
The expression causes one pointer type to be converted
|
|
to another incompatible type
|
|
|
|
illegal conversion of integer to pointer P1
|
|
An integer is used where a pointer is expected
|
|
|
|
illegal conversion of pointer to integer P1
|
|
A pointer is used where an integer is expected
|
|
|
|
illegal conversion P1
|
|
The type conversion here is illegal
|
|
|
|
Illegal flag LINK
|
|
This option is illegal
|
|
|
|
illegal function qualifier(s) P1
|
|
A function cannot have 'const' qualification
|
|
|
|
illegal initialisation P1
|
|
The initialisation of this variable is illegal
|
|
|
|
Illegal number CPP
|
|
Check number syntax
|
|
|
|
illegal type for array dimension P1
|
|
An array dimension must be an integral quantity
|
|
|
|
illegal type for index expression P1
|
|
An array index must be a simple integral expression
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 92 HI-TECH C USER'S MANUAL
|
|
|
|
illegal type for switch expression P1
|
|
The expression in a 'switch' must be integral
|
|
|
|
illegal use of void expression P1
|
|
Void expressions may not be used in any way
|
|
|
|
implicit conversion of float to integer P1
|
|
A floating point value has been converted to integer -
|
|
truncation may occur
|
|
|
|
implicit return at end of non-void function P1
|
|
A function with a non-void type has returned without a
|
|
return statement
|
|
|
|
implict signed to unsigned conversion P1
|
|
Unwanted sign extension may occur here. Add an explicit
|
|
typecast to force exactly the conversion you want
|
|
|
|
inappropriate break/continue P1
|
|
|
|
inappropriate 'else' P1
|
|
An 'else' has appeared without a matching 'if'
|
|
|
|
inconsistent storage class P1
|
|
Only one storage class may be specified in a declara-
|
|
tion
|
|
|
|
inconsistent type P1
|
|
Only one basic type may be specified in a declaration
|
|
|
|
initialisation illegal in arg list P1
|
|
You cannot initialise a function parameter
|
|
|
|
initialisation syntax P1
|
|
The syntax of this initialisation is illegal
|
|
|
|
initializer in 'extern' declaration P1
|
|
A declaration with the 'extern' keyword has an initial-
|
|
izer; this is not permitted as the extern declaration
|
|
reserves no storage
|
|
|
|
integer constant expected P1
|
|
An integer constant was expected here
|
|
|
|
integer expression required P1
|
|
An integral expression is required here
|
|
|
|
integral type required P1
|
|
An integral type is required here
|
|
|
|
large offset CGEN
|
|
Z80 only: This identifier has a large offset from the
|
|
stack frame and thus access to it is inefficient. In a
|
|
function any arrays should be declared after any simple
|
|
variables
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 93
|
|
|
|
Line too long P1
|
|
The source line is too long, or does not have a
|
|
<CR><LF> or newline at the end
|
|
|
|
local psect conflicts with global psect of same name
|
|
LINK
|
|
A local psect cannot have the same name as a global
|
|
psect
|
|
|
|
logical type required P1
|
|
A logical type (i.e. an integral type) is required as
|
|
the subject of a conditional expression
|
|
|
|
lvalue required P1
|
|
An lvalue, i.e. something which can be assigned to, is
|
|
required after an '&' or on the left hand of an assign-
|
|
ment
|
|
|
|
macro recursion CPP
|
|
A preprocessor macro has attempted to expand itself.
|
|
This would create infinite recursion
|
|
|
|
member is not a member of the struct/union P1
|
|
This member is not in the structure or union with which
|
|
it is used
|
|
|
|
members cannot be functions P1
|
|
A member cannot be a function - it can be a pointer to
|
|
function
|
|
|
|
Missing arg to -u LINK
|
|
-u requires an argument
|
|
|
|
Missing arg to -w LINK
|
|
-w requires an argument
|
|
|
|
missing ) CPP
|
|
Put correct ) in expression
|
|
|
|
Missing number after % in -p option LINK
|
|
After % in a -p option there must be a number
|
|
|
|
Missing number after pragma 'pack' P1
|
|
The correct syntax is #pragma pack(n) where n is 1, 2
|
|
or 4.
|
|
|
|
module has code below file base LINK
|
|
A -C option was specified but the program has code
|
|
below the address specified as the base of the binary
|
|
file
|
|
|
|
multiply defined symbol LINK
|
|
A symbol is defined more than once
|
|
|
|
name is a union, struct or enum P1
|
|
A union, struct or enum tag has been re-used in a dif-
|
|
ferent context
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 94 HI-TECH C USER'S MANUAL
|
|
|
|
No case labels CGEN
|
|
This switch has no case labels
|
|
|
|
no identifier in declaration P1
|
|
This declaration should have an identifier in it
|
|
|
|
No room CGEN
|
|
The code generator has run out of dynamic memory. You
|
|
will need to reduce the number of symbols and/or the
|
|
complexity of expressions
|
|
|
|
No source file CPP
|
|
Source file could not be found - check spelling, direc-
|
|
tory paths etc.
|
|
|
|
no space CPP
|
|
Reduce number/size of macro definitions
|
|
|
|
no start record: entry point defaults to zero LINK
|
|
No start address has been specified for the program;
|
|
the linker has set the start address to 0
|
|
|
|
Non-constant case label CGEN
|
|
This case label does not evaluate to an integral con-
|
|
stant
|
|
|
|
non-void function returns no value P1
|
|
A function which should return a value has a 'return'
|
|
statement with no value
|
|
|
|
not a variable identifier P1
|
|
The identifier is not a variable - it may be e.g. a
|
|
label or structure tag
|
|
|
|
not an argument P1
|
|
This identifier is not in the argument list for this
|
|
function
|
|
|
|
only functions may be qualified interrupt P1
|
|
The type qualifier 'interrupt' may be applied only to
|
|
functions, not variables.
|
|
|
|
only functions may be void P1
|
|
Only functions, not variables, may be declared void
|
|
|
|
only lvalues may be assigned to or modified P1
|
|
You have attempted to modify an expression which does
|
|
not identify a storage location
|
|
|
|
only register storage class allowed P1
|
|
A parameter may only be auto or register
|
|
|
|
operands of operator not same pointer type P1
|
|
The operands to the named operator in the expression
|
|
are both pointers but are not the same pointer type
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 95
|
|
|
|
operands of operator not same type P1
|
|
The operands to the named operator in the expression
|
|
are incompatible types
|
|
|
|
pointer required P1
|
|
A pointer is required after a '*' (indirection) opera-
|
|
tor
|
|
|
|
popreg - bad reg CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
portion of expression has no effect CGEN
|
|
A portion of this expression has no effect on its value
|
|
and no side effects
|
|
|
|
probable missing '}' in previous block P1
|
|
A declaration has been encountered where an expression
|
|
was expected. The likely cause of this is that you have
|
|
omitted a closing '}' in the function above this point.
|
|
|
|
psect cannot be in classes a and b LINK
|
|
A psect can only be in one class
|
|
|
|
psect exceeds max size LINK
|
|
This psect is larger than a specified maximum size
|
|
|
|
psect is absolute LINK
|
|
This psect is absolute and cannot have a link address
|
|
specified in a -p option
|
|
|
|
Psect not loaded on 0xhexnum boundary LINK
|
|
This psect must be loaded on a specific boundary
|
|
|
|
Psect not relocated on 0xhexnum boundary LINK
|
|
This psect must be linked on a specific boundary
|
|
|
|
psect origin multiply defined LINK
|
|
This psect has its link address defined more than once
|
|
|
|
pushreg - bad reg CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
redundant & applied to array P1
|
|
An array type has an '&' operator applied to it. It has
|
|
been ignored since use of an array implicitly gives its
|
|
address
|
|
|
|
regused - bad arg to G CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
signatures do not matchLINK
|
|
An extern function has been declared with an incorrect
|
|
prototype. For example if an argument is declared as a
|
|
long in an extern declaration, but is really an int, a
|
|
signature mismatch will occur.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 96 HI-TECH C USER'S MANUAL
|
|
|
|
signed bitfields not supported P1
|
|
Only unsigned bitfields are supported
|
|
|
|
simple type required P1
|
|
An array or structure type cannot be used here
|
|
|
|
Sizeof yields 0 CGEN
|
|
The size of an object has evaluated to zero in a con-
|
|
text where this is illegal, e.g. incrementing a pointer
|
|
to a zero length object.
|
|
|
|
storage class illegal P1
|
|
A storage class may not be specified here
|
|
|
|
struct/union member expected P1
|
|
A structure or union member is required after a '. or
|
|
'->'
|
|
|
|
struct/union redefined P1
|
|
This structure or union has been defined twice
|
|
|
|
struct/union required P1
|
|
A structure or union identifier is required before a
|
|
'.'
|
|
|
|
Switch on long! CGEN
|
|
Switching on a long expression is not supported
|
|
|
|
symbol cannot be global LINK
|
|
Stack, filename or line number symbols cannot be global
|
|
|
|
Syntax error in checksum list LINK
|
|
The checksum list provided is invalid
|
|
|
|
token too long CPP
|
|
Shorten token (e.g. identifier)
|
|
|
|
too few arguments P1
|
|
The protype for this function lists more arguments than
|
|
have been supplied
|
|
|
|
too many arguments P1
|
|
More arguments have been supplied than listed in the
|
|
prototype for this function
|
|
|
|
Too many cases in switch CGEN,P1
|
|
There are too many cases in this switch
|
|
|
|
too many -D options CPP
|
|
Use fewer -D options
|
|
|
|
too many defines CPP
|
|
Reduce number of macro definitions
|
|
|
|
Too many errors CGEN
|
|
CGEN has given up because there were too many errors.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 97
|
|
|
|
too many formals CPP
|
|
Reduce number of parameters to this macro definition
|
|
|
|
Too many initializers CGEN
|
|
There are too many initializers for this object
|
|
|
|
Too many psects LINK
|
|
There are too many psects for the symbol table
|
|
|
|
Too many symbols LINK
|
|
There are too many symbols for the linker symbol table
|
|
|
|
too many -U options CPP
|
|
Use fewer -U options
|
|
|
|
too much defining CPP
|
|
Reduce number/size of macros
|
|
|
|
too much indirection P1
|
|
Too many '*'s in this declaration
|
|
|
|
too much pushback CPP
|
|
Simplify macro usage
|
|
|
|
type conflict P1
|
|
There is a conflict of types in this expression, e.g.
|
|
attempting to assign a structure to a simple type
|
|
|
|
type specifier reqd. for proto arg P1
|
|
A prototype argument must have a basic type
|
|
|
|
undefined control CPP
|
|
Check use of #
|
|
|
|
undefined enum tag P1
|
|
This enumerated type tag has not been defined
|
|
|
|
undefined identifier P1
|
|
This identifier has not been defined before use
|
|
|
|
undefined struct/union P1
|
|
The structure or union used has not been defined
|
|
|
|
undefined symbol LINK
|
|
A list of undefined symbols follows. If some of the
|
|
symbols should be in a library which was linked, it may
|
|
be caused by a library ordering problem. In this case
|
|
rebuild the library with the correct ordering or
|
|
specify the library more than once in the link command
|
|
|
|
unexpected EOF P1
|
|
End of file was encountered in the middle of a C con-
|
|
struct. This is commonly caused by omission of a clos-
|
|
ing '}' earlier in the program.
|
|
|
|
Unknown predicate CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 98 HI-TECH C USER'S MANUAL
|
|
|
|
unknown psect LINK
|
|
The psect specifed in a -p option is not present in the
|
|
program. Check the spelling and check the case - upper
|
|
case does not match lower case
|
|
|
|
unreachable code P1
|
|
This section of code can never be executed as there is
|
|
no possible path to reach it
|
|
|
|
Unreasonable include nesting CPP
|
|
Reduce number of include files
|
|
|
|
Unreasonable matching depth CGEN
|
|
Internal error - contact HI-TECH
|
|
|
|
unterminated macro call CPP
|
|
Probably missing )
|
|
|
|
void function cannot return value P1
|
|
A function declared void cannot return a value
|
|
|
|
Write error (out of disk space?) LINK
|
|
Probably means the disk is full
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 99
|
|
|
|
APPENDIX 2
|
|
|
|
Standard Library Functions
|
|
|
|
|
|
|
|
The functions accessible to user programs in the stan-
|
|
dard library libc.lib are listed below, by category with a
|
|
short comment, then alphabetically with a longer descrip-
|
|
tion. In the detailed description of each function, the
|
|
SYNOPSIS section describes the function in roughly the
|
|
manner in which the function would be declared in the source
|
|
file defining it. Where an include file is shown, this
|
|
implies that that include file must be included in any
|
|
source file using that function.
|
|
|
|
Where an include file is not provided, it will normally
|
|
be necessary for an extern declaration of the function to be
|
|
included in any source module using it, to ensure that the
|
|
type of the function is correct. For example, if the func-
|
|
tion _l_s_e_e_k() was to be used, a declaration of the form
|
|
|
|
extern long lseek();
|
|
|
|
should be in either the source file itself or an include
|
|
file included in the source file. This ensures that the com-
|
|
piler knows that _l_s_e_e_k() returns a long value and not the
|
|
default int.
|
|
|
|
Where reference is made to STDIO, this means the group
|
|
of functions under the heading STANDARD I/O below. These all
|
|
have one thing in common; they operate on pointers to a
|
|
defined data type called FILE. Such a pointer is often
|
|
referred to as a _s_t_r_e_a_m pointer. The concept of a stream is
|
|
central to these routines. Essentially a stream is a source
|
|
or sink of data bytes. To the operating system and library
|
|
routines this stream is featureless, i.e. no record struc-
|
|
ture is implied or assumed. Some routines do however recog-
|
|
nize end of line characters.
|
|
|
|
|
|
|
|
STANDARD I/O
|
|
|
|
fopen(name, mode) Open file for I/O
|
|
freopen(name, mode, stream) Re-open existing stream
|
|
fdopen(fd, mode) Associate a stream with a file
|
|
descriptor
|
|
fclose(stream) Close open file
|
|
fflush(stream) Flush buffered data
|
|
getc(stream) Read byte from stream
|
|
fgetc(stream) Same as getc
|
|
ungetc(c, stream) Push char back onto stream
|
|
putc(c, stream) Write byte to stream
|
|
fputc(c, stream) Same as putc()
|
|
getchar() Read byte from standard input
|
|
putchar(c) Write byte to standard output
|
|
getw(stream) Read word from stream
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 100 HI-TECH C USER'S MANUAL
|
|
|
|
putw(w, stream) Write word to stream
|
|
gets(s) Read line from standard input
|
|
fgets(s, n, stream) Read string from stream
|
|
puts(s) Write string to standard output
|
|
fputs(s, stream) Write string to stream
|
|
fread(buf, size, cnt, stream) Binary read from stream
|
|
fwrite(buf, size, cnt, stream) Binary write to stream
|
|
fseek(stream, offs, wh) Random access positioning
|
|
ftell(stream) Current file read/write position
|
|
rewind(stream) Reposition file pointer to start
|
|
setvbuf(stream, buf, mode, size) Enable/disable buffering of stream
|
|
fprintf(stream, fmt, args) Formatted output on stream
|
|
printf(fmt, args) Formatted standard output
|
|
sprintf(buf, fmt, args) Formatted output to a string
|
|
vfprintf(stream, fmt, va_ptr) Formatted output on stream
|
|
vprintf(fmt, va_ptr) Formatted standard output
|
|
vsprintf(buf, fmt, va_ptr) Formatted output to a string
|
|
fscanf(stream, fmt, args) Formatted input from stream
|
|
scanf(fmt, args) Formatted standard input
|
|
sscanf(buf, fmt, va_ptr) Formatted input from a string
|
|
vfscanf(stream, fmt, va_ptr) Formatted input from stream
|
|
vscanf(fmt, args) Formatted standard input
|
|
vsscanf(buf, fmt, va_ptr) Formatted input from a string
|
|
feof(stream) True if stream at EOF
|
|
ferror(stream) True if error on stream
|
|
clrerr(stream) Reset error status on stream
|
|
fileno(stream) Return fd from stream
|
|
remove(name) Remove (delete) file
|
|
|
|
|
|
|
|
STRING HANDLING
|
|
|
|
atoi(s) Convert ASCII decimal to integer
|
|
atol(s) Convert ASCII decimal to long integer
|
|
atof(s) Convert ASCII decimal to float
|
|
xtoi(s) Convert ASCII hexadecimal to integer
|
|
memchr(s, c, n) Find char in memory block
|
|
memcmp(s1, s2, n) Compare n bytes of memory
|
|
memcpy(s1, s2, n) Copy n bytes from s2 to s1
|
|
memmove(s1, s2, n) Copy n bytes from s2 to s1
|
|
memset(s, c, n) Set n bytes at s to c
|
|
strcat(s1, s2) Append string 2 to string 1
|
|
strncat(s1, s2, n) Append at most n chars to string 1
|
|
strcmp(s1, s2) Compare strings
|
|
strncmp(s1, s2, n) Compare n bytes of strings
|
|
strcpy(s1, s2) Copy s2 to s1
|
|
strncpy(s1, s2, n) Copy at most n bytes of s2
|
|
strerror(errnum) Map errnum to an error message string
|
|
strlen(s) Length of string
|
|
strchr(s, c) Find char in string
|
|
strrchr(s, c) Find rightmost char in string
|
|
strspn(s1, s2) Length of s1 composed of chars from s2
|
|
strcspn(s1, s2) Length of s2 composed of chars not from s2
|
|
strstr(s1, s2) Locate the first occurence of s2 in s1
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 101
|
|
|
|
LOW LEVEL I/O
|
|
|
|
open(name, mode) Open a file
|
|
close(fd) Close a file
|
|
creat(name) Create a file
|
|
dup(fd) Duplicate file descriptor
|
|
lseek(fd, offs, wh) Random access positioning
|
|
read(fd, buf, cnt) Read from file
|
|
rename(name1, name2) Rename file
|
|
unlink(name) Remove file from directory
|
|
write(fd, buf, cnt) Write to file
|
|
isatty(fd) True if fd refers to tty-like device
|
|
stat(name, buf) Get information about a file
|
|
chmod(name, mode) Set file attributes
|
|
|
|
|
|
|
|
CHARACTER TESTING
|
|
|
|
isalpha(c) True if c is a letter
|
|
isupper(c) Upper case letter
|
|
islower(c) Lower case letter
|
|
isdigit(c) Digit
|
|
isalnum(c) Alphnumeric character
|
|
isspace(c) Space, tab, newline, return or formfeed
|
|
ispunct(c) Punctuation character
|
|
isprint(c) Printable character
|
|
isgraph(c) Printable non-space character
|
|
iscntrl(c) Control character
|
|
isascii(c) Ascii character (0-127)
|
|
|
|
|
|
|
|
FLOATING POINT
|
|
|
|
cos(f) Cosine function
|
|
sin(f) Sine function
|
|
tan(f) Tangent function
|
|
acos(f) Arc cosine function
|
|
asin(f) Arc sine function
|
|
atan(f) Arc tangent function
|
|
exp(f) Exponential of f
|
|
log(f) Natural log of f
|
|
log10(f) Base 10 log of f
|
|
pow(x,y) X to the y'th power
|
|
sqrt(f) Square root
|
|
fabs(f) Floating absolute value
|
|
ceil(f) Smallest integral value >= f
|
|
floor(f) Largest integral value <= f
|
|
sinh(f) Hyperbolic sine
|
|
cosh(f) Hyperbolic cosine
|
|
tanh(f) Hyperbolic tangent
|
|
frexp(y, p) Split into mantissa and exponent
|
|
ldexp(y, i) Load new exponent
|
|
|
|
|
|
|
|
CONSOLE I/O
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 102 HI-TECH C USER'S MANUAL
|
|
|
|
|
|
getch() Get single character
|
|
getche() Get single character with echo
|
|
putch(c) Put single character
|
|
ungetch(c) Push character back
|
|
kbhit() Test for key pressed
|
|
cgets(s) Get line from console
|
|
cputs(s) Put string to console
|
|
|
|
|
|
|
|
|
|
DATE AND TIME FUNCTIONS
|
|
|
|
time(p) Get current date/time
|
|
gmtime(p) Get broken down Universal time
|
|
localtime(p) Get broken down local time
|
|
asctime(t) Convert broken down time to ascii
|
|
ctime(p) Convert time to ascii
|
|
|
|
|
|
|
|
MISCELLANEOUS
|
|
|
|
execl(name, args) Execute another program
|
|
execv(name, argp) Execute another program
|
|
spawnl(name, arg, ...) Execute a subprogram
|
|
spawnv(name, argp) Execute a subprogram
|
|
system(s) Execute system command
|
|
atexit(func) Install func to be executed on termination
|
|
exit(status) Terminate execution
|
|
_exit(status) Terminate execution immediately
|
|
getuid() Get user id (CP/M)
|
|
setuid(uid) Set user id (CP/M)
|
|
chdir(s) Change directory (MS-DOS)
|
|
mkdir(s) Create directory (MS-DOS)
|
|
rmdir(s) Remove directory (MS-DOS)
|
|
getcwd(drive) Get current working directory (MS-DOS)
|
|
signal(sig, func) Set trap for interrupt condition
|
|
brk(addr) Set memory allocation
|
|
sbrk(incr) Adjust memory allocation
|
|
malloc(cnt) Dynamic memory allocation
|
|
free(ptr) Dynamic memory release
|
|
realloc(ptr, cnt) Dynamic memory reallocation
|
|
calloc(cnt, size) Dynamic memory allocation zeroed
|
|
perror(s) Print error message
|
|
qsort(base, nel, width, func) Quick sort
|
|
srand(seed) Initialize random number generator
|
|
rand() Get next random number
|
|
setjmp(buf) Setup for non-local goto
|
|
longjmp(buf, val) Non-local goto
|
|
_getargs(buf, name) Wild card expansion and i/o redirection
|
|
inp(port) Read port
|
|
outp(port, data) Write data to port
|
|
bdos(func, val) Perform bdos call (CP/M)
|
|
msdos(func, val, val, ...) Perform msdos call
|
|
msdoscx(func, val, val, ...) Alternate msdos call
|
|
intdos(ip, op) Execute DOS interrupt
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 103
|
|
|
|
intdosx(ip, op, sp) Execute DOS interrupt
|
|
segread(sp) Get segment register values
|
|
int86(int, ip, op) Execute software interrupt
|
|
int86x(int, ip, op, sp) Execute software interrupt
|
|
bios(n, c) Call bios entry (CP/M)
|
|
ei() Enable interrupts
|
|
di() Disable interrupts
|
|
set_vector(vec, func) Set an interrupt vector
|
|
assert(e) Run time assertion
|
|
getenv(s) Get environment string (MS-DOS)
|
|
|
|
|
|
|
|
|
|
|
|
ACOS, ASIN, ATAN, ATAN2
|
|
SYNOPSIS
|
|
|
|
#include <math.h>
|
|
|
|
double acos(double f)
|
|
double asin(double f)
|
|
double atan(double f)
|
|
|
|
double atan2(double x, double y)
|
|
|
|
|
|
DESCRIPTION
|
|
These functions are the converse of the trignometric
|
|
functions cos, sin and tan. Acos and asin are undefined
|
|
for arguments whose absolute value is greater than 1.0.
|
|
The returned value is in radians, and always in the
|
|
range -pi/2 to +pi/2, except for _c_o_s(), which returns a
|
|
value in the range 0 to pi. _A_t_a_n_2() returns the
|
|
inverse tan of x/y but uses the signs of its arguments
|
|
to return a value in the range -pi to +pi.
|
|
|
|
SEE ALSO
|
|
|
|
sin, cos, tan
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 104 HI-TECH C USER'S MANUAL
|
|
|
|
ATEXIT
|
|
SYNOPSIS
|
|
|
|
#include <stdlib.h>
|
|
|
|
int atexit(void (*func)(void));
|
|
|
|
|
|
DESCRIPTION
|
|
The _a_t_e_x_i_t() function registers the function pointed to
|
|
by func, to be called without arguments at normal pro-
|
|
gram termination. _A_t_e_i_x_t() returns zero if the regis-
|
|
tration succeeds, nonzero if it fails. On program ter-
|
|
mination, all functions registered by _a_t_e_x_i_t() are
|
|
called, in the reverse order of their registration.
|
|
|
|
SEE ALSO
|
|
|
|
exit
|
|
|
|
|
|
|
|
|
|
|
|
ASCTIME
|
|
SYNOPSIS
|
|
|
|
#include <time.h>
|
|
|
|
char * asctime(time_t t)
|
|
|
|
|
|
DESCRIPTION
|
|
_A_s_c_t_i_m_e() takes the broken down time pointed to by its
|
|
argument, and returns a 26 character string describing
|
|
the current date and time in the format
|
|
|
|
Sun Sep 16 01:03:52 1973\n\0
|
|
|
|
Note the newline at the end of the string. The width of
|
|
each field in the string is fixed.
|
|
|
|
SEE ALSO
|
|
|
|
ctime, time, gmtime, localtime
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 105
|
|
|
|
ASSERT
|
|
SYNOPSIS
|
|
|
|
#include <assert.h>
|
|
|
|
void assert(int e)
|
|
|
|
|
|
DESCRIPTION
|
|
This macro is used for debugging purposes; the basic
|
|
method of usage is to place assertions liberally
|
|
throughout your code at points where correct operation
|
|
of the code depends upon certain conditions being true
|
|
initially. An _a_s_s_e_r_t() may be used to ensure at run
|
|
time that that assumption holds. For example, the fol-
|
|
lowing statement asserts that the pointer tp is non-
|
|
null:
|
|
|
|
assert(tp);
|
|
|
|
If at run time the expression evaluates to false, the
|
|
program will abort with a message identifying the
|
|
source file and line number of the assertion, and the
|
|
expression used as an argument to it. A fuller discus-
|
|
sion of the uses of assert is impossible in limited
|
|
space, but it is closely linked to methods of proving
|
|
program correctness.
|
|
|
|
|
|
|
|
|
|
ATOF, ATOI, ATOL
|
|
SYNOPSIS
|
|
|
|
#include <math.h>
|
|
|
|
double atof(char * s)
|
|
int atoi(char * s)
|
|
|
|
#include <stdlib.h>
|
|
|
|
long atol(char * s)
|
|
|
|
|
|
DESCRIPTION
|
|
These routines convert a decimal number in the argument
|
|
string s into a double float, integer or long integer
|
|
respectively. Leading blanks are skipped over. In the
|
|
case of _a_t_o_f(), the number may be in scientific nota-
|
|
tion.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 106 HI-TECH C USER'S MANUAL
|
|
|
|
BDOS (CP/M only)
|
|
SYNOPSIS
|
|
|
|
#include <cpm.h>
|
|
|
|
char bdos(int func, int arg)
|
|
|
|
short bdoshl(int func, int arg)(CP/M-80 only)
|
|
|
|
|
|
DESCRIPTION
|
|
_B_d_o_s() calls the CP/M BDOS with func in register C (CL
|
|
for CP/M-86) and arg in register DE (DX). The return
|
|
value is the byte returned by the BDOS in register A
|
|
(AX). _B_d_o_s_h_l() is the same, except that the return
|
|
value is the value returned by the BDOS in HL. Con-
|
|
stant values for the various BDOS function values are
|
|
defined in cpm.h.
|
|
|
|
These functions should be avoided except in programs
|
|
which are not intended to be used on an operating sys-
|
|
tem other than CP/M. The standard I/O routines are to
|
|
be preferred, since they are portable.
|
|
|
|
SEE ALSO
|
|
|
|
bios, msdos
|
|
|
|
|
|
|
|
|
|
|
|
BIOS (CP/M only)
|
|
SYNOPSIS
|
|
|
|
#includ <cpm.h>
|
|
|
|
char bios(int n, int a1, int a2)
|
|
|
|
|
|
DESCRIPTION
|
|
This function will call the n'th bios entry point (cold
|
|
boot = 0, warm boot = 1, etc.) with register BC (CX)
|
|
set to the argument a1 and DE (DX) set to the argument
|
|
a2. The return value is the contents of register A (AX)
|
|
after the bios call. On CP/M-86, bdos function 50 is
|
|
used to perform the bios call. This function should
|
|
not be used unless unavoidable, since it is highly
|
|
non-portable. There is even no guarantee of portability
|
|
of bios calls between differing CP/M systems.
|
|
|
|
SEE ALSO
|
|
|
|
bdos
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 107
|
|
|
|
CALLOC
|
|
SYNOPSIS
|
|
|
|
#include <stdlib.h>
|
|
|
|
char * calloc(size_t cnt, size_t size)
|
|
|
|
|
|
DESCRIPTION
|
|
_C_a_l_l_o_c() attempts to obtain a contiguous block of
|
|
dynamic memory which will hold cnt objects, each of
|
|
length size. The block is filled with zeroes. A
|
|
pointer to the block is returned, or 0 if the memory
|
|
could not be allocated.
|
|
|
|
SEE ALSO
|
|
|
|
brk, sbrk, malloc, free
|
|
|
|
|
|
|
|
|
|
|
|
CGETS, CPUTS
|
|
SYNOPSIS
|
|
|
|
#include <conio.h>
|
|
|
|
char * cgets(char * s)
|
|
|
|
void cputs(char * s)
|
|
|
|
|
|
DESCRIPTION
|
|
_C_p_u_t_s() will read one line of input from the console
|
|
into the buffer passed as an argument. It does so by
|
|
repeated calls to _g_e_t_c_h_e(). _C_p_u_t_s() writes its argu-
|
|
ment string to the console, outputting carriage returns
|
|
before each newline in the string. It calls _p_u_t_c_h()
|
|
repeatedly.
|
|
|
|
SEE ALSO
|
|
|
|
getch, getche, putch
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 108 HI-TECH C USER'S MANUAL
|
|
|
|
CHDIR
|
|
SYNOPSIS
|
|
|
|
#include <sys.h>
|
|
|
|
int chdir(char * s)
|
|
|
|
|
|
DESCRIPTION
|
|
This function is availble only under MS-DOS. It changes
|
|
the current working directory to the path name supplied
|
|
as argument. This path name be be absolute, as in
|
|
A:\FRED, or relative, as in ..\SOURCES. A return value
|
|
of -1 indicates that the requested change could not be
|
|
performed.
|
|
|
|
SEE ALSO
|
|
|
|
mkdir, rmdir, getcwd
|
|
|
|
|
|
|
|
|
|
|
|
CHMOD
|
|
SYNOPSIS
|
|
|
|
#include <stat.h>
|
|
|
|
int chmod(char * name, int )
|
|
char * name;
|
|
int mode;
|
|
|
|
|
|
DESCRIPTION
|
|
This function changes the file attributes (or modes) of
|
|
the named file. The argument name may be any valid
|
|
file name. The mode argument may include all bits
|
|
defined in _s_t_a_t._h except those relating to the type of
|
|
the file, e.g. S_IFDIR. Note however that not all bits
|
|
may be changed under all operating systems, e.g. nei-
|
|
ther DOS nor CP/M permit a file to be made unreadable,
|
|
thus even if mode does not include S_IREAD the file
|
|
will still be readable (and _s_t_a_t() will still return
|
|
S_IREAD in flags).
|
|
|
|
SEE ALSO
|
|
|
|
stat, creat
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 109
|
|
|
|
CLOSE
|
|
SYNOPSIS
|
|
|
|
#include <unixio.h>
|
|
|
|
int close(int fd)
|
|
|
|
|
|
DESCRIPTION
|
|
This routine closes the file associated with the file
|
|
descriptor fd, which will have been previously obtained
|
|
from a call to _o_p_e_n(). _C_l_o_s_e() returns 0 for a success-
|
|
ful close, or -1 otherwise.
|
|
|
|
SEE ALSO
|
|
|
|
open, read, write, seek
|
|
|
|
|
|
|
|
|
|
|
|
CLRERR, CLREOF
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
void clrerr(FILE * stream)
|
|
void clreof(FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
These are macros, defined in stdio.h, which reset the
|
|
error and end of file flags respectively for the speci-
|
|
fied stream. They should be used with care; the major
|
|
valid use is for clearing an EOF status on input from a
|
|
terminal-like device, where it may be valid to continue
|
|
to read after having seen an end-of-file indication.
|
|
|
|
SEE ALSO
|
|
|
|
fopen, fclose
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 110 HI-TECH C USER'S MANUAL
|
|
|
|
COS
|
|
SYNOPSIS
|
|
|
|
#include <math.h>
|
|
|
|
double cos(double f)
|
|
|
|
|
|
DESCRIPTION
|
|
This function yields the cosine of its argument.
|
|
|
|
SEE ALSO
|
|
|
|
sin, tan, asin, acos, atan
|
|
|
|
|
|
|
|
|
|
|
|
COSH, SINH, TANH
|
|
SYNOPSIS
|
|
|
|
#include <math.h>
|
|
|
|
double cosh(double f)
|
|
double sinh(double f)
|
|
double tanh(double f)
|
|
|
|
|
|
DESCRIPTION
|
|
These functions implement the hyperbolic trig func-
|
|
tions.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 111
|
|
|
|
CREAT
|
|
SYNOPSIS
|
|
|
|
#include <stat.h>
|
|
|
|
int creat(char * name, int mode)
|
|
|
|
|
|
DESCRIPTION
|
|
This routine attempts to create the file named by name.
|
|
If the file exists and is writeable, it will be removed
|
|
and re-created. The return value is -1 if the create
|
|
failed, or a small non-negative number if it succeeded.
|
|
This number is a valuable token which must be used to
|
|
write to or close the file subsequently. Mode is used
|
|
to initialize the attributes of the created file. The
|
|
allowable bits are the same as for _c_h_m_o_d(), but for
|
|
Unix compatibility it is recommended that a mode of
|
|
0666 or 0600 be used. Under CP/M the mode is ignored -
|
|
the only way to set a files attributes is via the
|
|
_c_h_m_o_d() function.
|
|
|
|
SEE ALSO
|
|
|
|
open, close, read, write, seek, stat, chmod
|
|
|
|
|
|
|
|
|
|
|
|
CTIME
|
|
SYNOPSIS
|
|
|
|
#include <time.h>
|
|
|
|
char * ctime(time_t t)
|
|
|
|
|
|
DESCRIPTION
|
|
_C_t_i_m_e() converts the time in seconds pointed to by its
|
|
argument to a string of the same form as described for
|
|
asctime. Thus the following program prints the current
|
|
time and date:
|
|
|
|
|
|
#include <time.h>
|
|
|
|
main()
|
|
{
|
|
time_t t;
|
|
|
|
time(&t);
|
|
printf("%s", ctime(&t));
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 112 HI-TECH C USER'S MANUAL
|
|
|
|
SEE ALSO
|
|
|
|
gmtime, localtime, asctime, time
|
|
|
|
|
|
|
|
|
|
|
|
DIV, LDIV
|
|
SYNOPSIS
|
|
|
|
#include <stdlib.h>
|
|
|
|
div_t div(int numer, int denom)
|
|
ldiv_t ldiv(long numer, long denom)
|
|
|
|
|
|
DESCRIPTION
|
|
The _d_i_v() function computes the quotient and remainder
|
|
of the divison of numer by denom. The _d_i_v() function
|
|
returns a structure of type div_t, containing both the
|
|
quotient and remainder. _l_d_i_v() is similar to _d_i_v()
|
|
except it takes arguments of type long and returns a
|
|
structure of type ldiv_t. The types div_t and ldiv_t
|
|
are defined in <stdlib.h> as follows:
|
|
|
|
typedef struct {
|
|
intquot, rem;
|
|
} div_t;
|
|
|
|
typedef struct {
|
|
longquot, rem;
|
|
} ldiv_t;
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 113
|
|
|
|
DI, EI
|
|
SYNOPSIS
|
|
|
|
void ei(void);
|
|
void di(void);
|
|
|
|
|
|
DESCRIPTION
|
|
_E_i() and _d_i() enable and disable interrupts respec-
|
|
tivly.
|
|
|
|
|
|
|
|
|
|
DUP
|
|
SYNOPSIS
|
|
|
|
#include <unixio.h>
|
|
|
|
int dup(int fd)
|
|
|
|
|
|
DESCRIPTION
|
|
Given a file descriptor, such as returned by _o_p_e_n(),
|
|
this routine will return another file descriptor which
|
|
will refer to the same open file. -1 is returned if
|
|
the fd argument is a bad descriptor or does not refer
|
|
to an open file.
|
|
|
|
SEE ALSO
|
|
|
|
open, close, creat, read, write
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 114 HI-TECH C USER'S MANUAL
|
|
|
|
EXECL, EXECV
|
|
SYNOPSIS
|
|
|
|
#include <sys.h>
|
|
|
|
int execl(char * name, pname, ...)
|
|
int execv(char * name, ppname)
|
|
|
|
|
|
DESCRIPTION
|
|
_E_x_e_c_l() and _e_x_e_c_v() load and execute the program speci-
|
|
fied by the string name. _E_x_e_c_l() takes the arguments
|
|
for the program from the zero-terminated list of string
|
|
arguments. _E_x_e_c_v() is passed a pointer to an array of
|
|
strings. The array must be zero-terminated. If the
|
|
named program is found and can be read, the call does
|
|
not return. Thus any return from these routines may be
|
|
treated as an error.
|
|
|
|
SEE ALSO
|
|
|
|
spawnl, spawnv, system
|
|
|
|
|
|
|
|
|
|
|
|
EXIT
|
|
SYNOPSIS
|
|
|
|
#include <stdlib.h>
|
|
|
|
void exit(int status)
|
|
|
|
|
|
DESCRIPTION
|
|
This call will close all open files and exit from the
|
|
program. On CP/M, this means a return to CCP level.
|
|
Status will be stored in a known place for examination
|
|
by other programs. This is only useful if the program
|
|
executing was actually invoked by another program which
|
|
is trapping warm boots. The status value will be stored
|
|
on CP/M at 80H. This call will never return.
|
|
|
|
SEE ALSO
|
|
|
|
atexit
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 115
|
|
|
|
_EXIT
|
|
SYNOPSIS
|
|
|
|
#include <stdlib.h>
|
|
void _exit(int status)
|
|
|
|
|
|
DESCRIPTION
|
|
This function will cause an immediate exit from the
|
|
program, without the normal flushing of stdio buffers
|
|
that is performed by _e_x_i_t().
|
|
|
|
SEE ALSO
|
|
|
|
exit
|
|
|
|
|
|
|
|
|
|
|
|
EXP, LOG, LOG10, POW
|
|
SYNOPSIS
|
|
|
|
#include <math.h>
|
|
|
|
double exp(double f)
|
|
double log(double f)
|
|
double log10(double f)
|
|
double pow(double x, y)
|
|
|
|
|
|
DESCRIPTION
|
|
_E_x_p() returns the exponential function of its argument,
|
|
_l_o_g() the natural logarithm of f, and _l_o_g_1_0() the loga-
|
|
rithm to base 10. _P_o_w() returns the value of x raised
|
|
to the y'th power.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 116 HI-TECH C USER'S MANUAL
|
|
|
|
FABS, CEIL, FLOOR
|
|
SYNOPSIS
|
|
|
|
#include <math.h>
|
|
|
|
double fabs(double f)
|
|
double ceil(double f)
|
|
double floor(double f)
|
|
|
|
|
|
DESCRIPTION
|
|
These routines return respectively the absolute value
|
|
of f, the smallest integral value not less than f, and
|
|
the largest integral value not greater than f.
|
|
|
|
|
|
|
|
|
|
FCLOSE
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int fclose(FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
This routine closes the specified i/o stream. Stream
|
|
should be a token returned by a previous call to
|
|
_f_o_p_e_n(). NULL is returned on a successful close, EOF
|
|
otherwise.
|
|
|
|
SEE ALSO
|
|
|
|
fopen, fread, fwrite
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 117
|
|
|
|
FEOF, FERROR
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
feof(FILE * stream)
|
|
ferror(FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
These macros test the status of the EOF and ERROR bits
|
|
respectively for the specified stream. Each will be
|
|
true if the corresponding flag is set. The macros are
|
|
defined in stdio.h. Stream must be a token returned by
|
|
a previous _f_o_p_e_n() call.
|
|
|
|
SEE ALSO
|
|
|
|
fopen, fclose
|
|
|
|
|
|
|
|
|
|
|
|
FFLUSH
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int fflush(FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
_F_f_l_u_s_h() will output to the disk file or other device
|
|
currently open on the specified stream the contents of
|
|
the associated buffer. This is typically used for
|
|
flushing buffered standard output in interactive appli-
|
|
cations.
|
|
|
|
SEE ALSO
|
|
|
|
fopen, fclose
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 118 HI-TECH C USER'S MANUAL
|
|
|
|
FGETC
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int fgetc(FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
_F_g_e_t_c() returns the next character from the input
|
|
stream. If end-of-file is encountered EOF will be
|
|
returned instead. It is for this reason that the func-
|
|
tion is declared as int. The integer EOF is not a valid
|
|
byte, thus end-of-file is distinguishable from reading
|
|
a byte of all 1 bits from the file. _F_g_e_t_c() is the
|
|
non-macro version of _g_e_t_c().
|
|
|
|
SEE ALSO
|
|
|
|
fopen, fclose, fputc, getc, putc
|
|
|
|
|
|
|
|
|
|
|
|
FGETS
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
char * fgets(char * s, size_t n, char * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
_F_g_e_t_s() places in the buffer s up to n-1 characters
|
|
from the input stream. If a newline is seen in the
|
|
input before the correct number of characters is read,
|
|
then _f_g_e_t_s() will return immediately. The newline will
|
|
be left in the buffer. The buffer will be null ter-
|
|
minated in any case. A successful _f_g_e_t_s() will return
|
|
its first argument; NULL is returned on end-of-file or
|
|
error.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 119
|
|
|
|
FILENO
|
|
SYNOPSIS
|
|
|
|
fileno(FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
_F_i_l_e_n_o() is a macro from stdio.h which yields the file
|
|
descriptor associated with stream. It is mainly used
|
|
when it is desired to perform some low-level operation
|
|
on a file opened as a stdio stream.
|
|
|
|
SEE ALSO
|
|
|
|
fopen, fclose, open, close
|
|
|
|
|
|
|
|
|
|
|
|
FOPEN
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
FILE * fopen(char * name, char * mode);
|
|
|
|
|
|
DESCRIPTION
|
|
|
|
|
|
DESCRIPTION
|
|
_F_o_p_e_n() attempts to open file for reading or writing
|
|
(or both) according to the mode string supplied. The
|
|
mode string is interpreted as follows:
|
|
|
|
r The file is opend for reading if it exists. If the file
|
|
does not exist the call fails.
|
|
|
|
r+ If the file exists it is opened for reading and writ-
|
|
ing. If the file does not already exist the call fails.
|
|
|
|
w The file is created if it does not exist, or truncated
|
|
if it does. It is then opened for writing.
|
|
|
|
w+ The file is created if it does not already exist, or
|
|
truncated if it does. The file is opened for reading
|
|
and writing.
|
|
|
|
a The file is created if it does not already exist, and
|
|
opened for writing. All writes will be dynamically
|
|
forced to the end of file, thus this mode is known as
|
|
_a_p_p_e_n_d mode.
|
|
|
|
a+ The file is created if it does not already exist, and
|
|
opened for reading and writing. All writes to the file
|
|
will be dynamically forced to the end of the file, i.e.
|
|
while any portion of the file may be read, all writes
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 120 HI-TECH C USER'S MANUAL
|
|
|
|
will take place at the end of the file and will not
|
|
overwrite any existing data. Calling _f_s_e_e_k() in an
|
|
attempt to write at any other place in the file will
|
|
not be effective.
|
|
|
|
The "b" modifier may be appended to any of the above
|
|
modes, e.g. "r+b" or "rb+" are equivalent. Adding the "b"
|
|
modifier will cause the file to be opened in binary rather
|
|
than ASCII mode. Opening in ASCII mode ensures that text
|
|
files are read in a manner compatible with the Unix-derived
|
|
conventions for C programs, i.e. that text files contain
|
|
lines delimited by newline characters. The special treat-
|
|
ment of read or written characters varies with the operating
|
|
system, but includes some or all of the following:
|
|
|
|
NEWLINE (LINE FEED)
|
|
Converted to carriage return, line feed on output.
|
|
|
|
RETURN
|
|
Ignored on input, inserted before NEWLINE on output.
|
|
|
|
CTRL-Z
|
|
Signals EOF on input, appended on fclose on output if
|
|
necessary on CP/M.
|
|
|
|
Opening a file in binary mode will allow each character
|
|
to be read just as written, but because the exact size
|
|
of a file is not known to CP/M, the file may contain
|
|
more bytes than were written to it. See _o_p_e_n() for a
|
|
description of what constitutes a file name.
|
|
|
|
When using one of the read/write modes (with a '+'
|
|
character in the string), although they permits reading and
|
|
writing on the same stream, it is not possible to arbi-
|
|
trarily mix input and output calls to the same stream. At
|
|
any given time a stream opened with a "+" mode will be in
|
|
either an input or output state. The state may only be
|
|
changed when the associated buffer is empty, which is only
|
|
guaranteed immediately after a call to _f_f_l_u_s_h() or one of
|
|
the file positioning functions _f_s_e_e_k() or _r_e_w_i_n_d(). The
|
|
buffer will also be empty after encountering EOF while read-
|
|
ing a binary stream, but it is recommended that an explicit
|
|
call to _f_f_l_u_s_h() be used to ensure this situation. Thus
|
|
after reading from a stream you should call _f_f_l_u_s_h() or
|
|
_f_s_e_e_k() before attempting to write on that stream, and vice
|
|
versa.
|
|
|
|
SEE ALSO
|
|
|
|
fclose, fgetc, fputc, freopen
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 121
|
|
|
|
FPRINTF
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
fprintf(FILE * stream, char * fmt, ...);
|
|
vfprintf(FILE * stream, va_list va_arg);
|
|
|
|
|
|
DESCRIPTION
|
|
_F_p_r_i_n_t_f() performs formatted printing on the specified
|
|
stream. Refer to _p_r_i_n_t_f() for the details of the avail-
|
|
able formats. _V_f_p_r_i_n_t_f() is similar to _f_p_r_i_n_t_f() but
|
|
takes a variable argument list pointer rather than a
|
|
list of arguments. See the description of _v_a__s_t_a_r_t()
|
|
for more information on variable argument lists.
|
|
|
|
SEE ALSO
|
|
|
|
printf, fscanf, sscanf
|
|
|
|
|
|
|
|
|
|
|
|
FPUTC
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int fputc(int c, FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
The character c is written to the supplied stream. This
|
|
is the non-macro version of _p_u_t_c(). The character is
|
|
returned if it was successfully written, EOF is
|
|
returned otherwise. Note that "written to the stream"
|
|
may mean only placing the character in the buffer asso-
|
|
ciated with the stream.
|
|
|
|
SEE ALSO
|
|
|
|
putc, fgetc, fopen, fflush
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 122 HI-TECH C USER'S MANUAL
|
|
|
|
FPUTS
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int fputs(char * s, FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
The null-terminated string s is written to the stream.
|
|
No newline is appended (cf. _p_u_t_s() ). The error return
|
|
is EOF.
|
|
|
|
SEE ALSO
|
|
|
|
puts, fgets, fopen, fclose
|
|
|
|
|
|
|
|
|
|
|
|
FREAD
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int fread(void * buf, size_t size, size_t cnt,
|
|
FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
Up to cnt objects, each of length size, are read into
|
|
memory at buf from the stream. The return value is the
|
|
number of objects read. If none is read, 0 will be
|
|
returned. Note that a return value less than cnt, but
|
|
greater than 0, may not represent an error (cf.
|
|
_f_w_r_i_t_e() ). No word alignment in the stream is assumed
|
|
or necessary. The read is done via successive _g_e_t_c()'s.
|
|
|
|
SEE ALSO
|
|
|
|
fwrite, fopen, fclose, getc
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 123
|
|
|
|
FREE
|
|
SYNOPSIS
|
|
|
|
#include <stdlib.h>
|
|
|
|
void free(void * ptr)
|
|
|
|
|
|
DESCRIPTION
|
|
_F_r_e_e() deallocates the block of memory at ptr, which
|
|
must have been obtained from a call to _m_a_l_l_o_c() or _c_a_l_-
|
|
_l_o_c().
|
|
|
|
SEE ALSO
|
|
|
|
malloc, calloc
|
|
|
|
|
|
|
|
|
|
|
|
FREOPEN
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
FILE * freopen(char * name, char * mode, FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
_F_r_e_o_p_e_n() closes the given stream (if open) then re-
|
|
opens the stream attached to the file described by
|
|
name. The mode of opening is given by mode. It either
|
|
returns the stream argument, if successful, or NULL if
|
|
not. See _f_o_p_e_n() for more information.
|
|
|
|
SEE ALSO
|
|
|
|
fopen, fclose
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 124 HI-TECH C USER'S MANUAL
|
|
|
|
FREXP, LDEXP
|
|
SYNOPSIS
|
|
|
|
#include <math.h>
|
|
|
|
double frexp(double f, int * p)
|
|
|
|
double ldexp(double f, int i)
|
|
|
|
|
|
DESCRIPTION
|
|
_F_r_e_x_p() breaks a floating point number into a normal-
|
|
ized fraction and an integral power of 2. The integer
|
|
is stored into the int object pointed to by p. Its
|
|
return value x is in the interval [0.5, 1.0) or zero,
|
|
and f equals x times 2 raised to the power stored in
|
|
*p. If f is zero, both parts of the result are zero.
|
|
_L_d_e_x_p() performs the reverse operation; the integer i
|
|
is added to the exponent of the floating point f and
|
|
the resultant value returned.
|
|
|
|
|
|
|
|
|
|
FSCANF
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int fscanf(FILE * stream, char * fmt, ...)
|
|
|
|
|
|
DESCRIPTION
|
|
This routine performs formatted input from the speci-
|
|
fied stream. See _s_c_a_n_f() for a full description of the
|
|
behaviour of the routine. _V_f_s_c_a_n_f() is similar to
|
|
_f_s_c_a_n_f() but takes a variable argument list pointer
|
|
rather than a list of arguments. See the description of
|
|
_v_a__s_t_a_r_t() for more information on variable argument
|
|
lists.
|
|
|
|
SEE ALSO
|
|
|
|
scanf, sscanf, fopen, fclose
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 125
|
|
|
|
FSEEK
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int fseek(FILE * stream, long offs, int wh)
|
|
|
|
|
|
DESCRIPTION
|
|
_F_s_e_e_k() positions the "file pointer" (i.e. a pointer to
|
|
the next character to be read or written) of the speci-
|
|
fied stream as follows:
|
|
|
|
_____________________________
|
|
|_w_h__|____r_e_s_u_l_t_a_n_t__l_o_c_a_t_i_o_n____|
|
|
| 0 | offs |
|
|
| 1 | offs+previous location|
|
|
| 2 | offs+length of file |
|
|
|____|_________________________|
|
|
|
|
|
|
It should be noted that offs is a signed value. Thus
|
|
the 3 allowed modes give postioning relative to the
|
|
beginning of the file, the current file pointer and the
|
|
end of the file respectively. EOF is returned if the
|
|
positioning request could not be satisfied. Note how-
|
|
ever that positioning beyond the end of the file is
|
|
legal, but will result in an EOF indication if an
|
|
attempt is made to read data there. It is quite in
|
|
order to write data beyond the previous end of file.
|
|
_F_s_e_e_k() correctly accounts for any buffered data.
|
|
|
|
SEE ALSO
|
|
|
|
lseek, fopen, fclose
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 126 HI-TECH C USER'S MANUAL
|
|
|
|
FTELL
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
long ftell(FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
This function returns the current position of the con-
|
|
ceptual read/write pointer associated with stream.
|
|
This is the position relative to the beginning of the
|
|
file of the next byte to be read from or written to the
|
|
file.
|
|
|
|
SEE ALSO
|
|
|
|
fseek
|
|
|
|
|
|
|
|
|
|
|
|
FWRITE
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int fwrite(void * buf, size_t size, size_t cnt,
|
|
FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
Cnt objects of length size bytes will be written from
|
|
memory at buf, to the specified stream. The number of
|
|
whole objects written will be returned, or 0 if none
|
|
could be written. Any return value not equal to cnt
|
|
should be treated as an error (cf. _f_r_e_a_d() ).
|
|
|
|
SEE ALSO
|
|
|
|
fread, fopen, fclose
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 127
|
|
|
|
_GETARGS
|
|
SYNOPSIS
|
|
|
|
#include <sys.h>
|
|
|
|
char ** _getargs(char * buf, char * name)
|
|
extern int _argc_;
|
|
|
|
|
|
DESCRIPTION
|
|
This routine performs I/O redirection (CP/M only) and
|
|
wild card expansion. Under MS-DOS I/O redirection is
|
|
performed by the operating system. It is called from
|
|
startup code to operate on the command line if the -R
|
|
option is used to the C command, but may also be called
|
|
by user-written code. If the buf argument is null, it
|
|
will read lines of text from standard input. If the
|
|
standard input is a terminal (usually the console) the
|
|
name argument will be written to the standard error
|
|
stream as a prompt. If the buf argument is not null, it
|
|
will be used as the source of the string to be pro-
|
|
cessed. The returned value is a pointer to an array of
|
|
strings, exactly as would be pointed to by the argv
|
|
argument to the main() function. The number of strings
|
|
in the array may be obtained from the global _argc_.
|
|
For example, a typical use of this function would be:
|
|
|
|
#include <sys.h>
|
|
|
|
main(argc, argv)
|
|
char ** argv;
|
|
{
|
|
extern char ** _getargs();
|
|
extern int _argc_;
|
|
|
|
if(argc == 1) {/* no arguments */
|
|
argv = _getargs(0, "myname");
|
|
argc = _argc_;
|
|
}
|
|
.
|
|
.
|
|
.
|
|
}
|
|
|
|
There will be one string in the array for each word in
|
|
the buffer processed. Quotes, either single (') or
|
|
double (") may be used to include white space in
|
|
"words". If any wild card characters (? or *) appear in
|
|
a non-quoted word, it will be expanded into a string of
|
|
words, one for each file matching the word. The usual
|
|
CP/M conventions are followed for this expansion. On
|
|
CP/M any occurence of the redirection characters > and
|
|
< outside quotes will be handled in the following
|
|
manner:
|
|
|
|
> name
|
|
will cause standard output to be redirected to the file
|
|
name.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 128 HI-TECH C USER'S MANUAL
|
|
|
|
< name
|
|
will cause standard input to be redirected from the
|
|
file name.
|
|
|
|
>> name
|
|
will cause standard output to append to file name.
|
|
|
|
White space is optional between the > or < character
|
|
and the file name, however it is an error for a
|
|
redirection character not to be followed by a file
|
|
name. It is also an error if a file cannot be opened
|
|
for input or created for output. An append redirection
|
|
(>>) will create the file if it does not exist. If the
|
|
source of text to be processed is standard input,
|
|
several lines may be supplied by ending each line
|
|
(except the last) with a backslash (\). This serves as
|
|
a continuation character. Note that the newline follow-
|
|
ing the backslash is ignored, and not treated as white
|
|
space.
|
|
|
|
|
|
|
|
|
|
GETC
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int getc(FILE * stream)
|
|
FILE * stream;
|
|
|
|
|
|
DESCRIPTION
|
|
One character is read from the specified stream and
|
|
returned. EOF will be returned on end-of-file or error.
|
|
This is the macro version of _f_g_e_t_c(), and is defined in
|
|
stdio.h.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 129
|
|
|
|
GETCH, GETCHE, UNGETCH, PUTCH
|
|
SYNOPSIS
|
|
|
|
#include <conio.h>
|
|
|
|
char getch(void)
|
|
char getche(void)
|
|
void putch(int c)
|
|
|
|
|
|
DESCRIPTION
|
|
_G_e_t_c_h() reads a single character from the console key-
|
|
board and returns it without echoing. _G_e_t_c_h_e() is
|
|
similar but does echo the character typed. _U_n_g_e_t_c_h()
|
|
will push back one character such that the next call to
|
|
_g_e_t_c_h() or _g_e_t_c_h_e() will return that character.
|
|
_P_u_t_c_h() outputs the character c to the console screen,
|
|
prepending a carriage return if the character is a new-
|
|
line.
|
|
|
|
SEE ALSO
|
|
|
|
cgets, cputs
|
|
|
|
|
|
|
|
|
|
|
|
GETCHAR
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int getchar(void)
|
|
|
|
|
|
DESCRIPTION
|
|
_G_e_t_c_h_a_r() is a _g_e_t_c(_s_t_d_i_n) operation. It is a macro
|
|
defined in stdio.h. Note that under normal cir-
|
|
cumstances getchar() will NOT return unless a carriage
|
|
return has been typed on the console. To get a single
|
|
character immediately from the console, use the routine
|
|
_g_e_t_c_h().
|
|
|
|
SEE ALSO
|
|
|
|
getc, fgetc, freopen, fclose
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 130 HI-TECH C USER'S MANUAL
|
|
|
|
GETCWD (MS-DOS only)
|
|
SYNOPSIS
|
|
|
|
#include <sys.h>
|
|
|
|
char * getcwd(int drive)
|
|
|
|
|
|
DESCRIPTION
|
|
_G_e_t_c_w_d() returns the path name of the current working
|
|
directory on the specified drive, where drive == 0
|
|
represents the current drive, drive == 1 represents A:,
|
|
drive == 2 represents B: etc. The return value is a
|
|
pointer to a static area of memory which will be
|
|
overwritten on the next call to _g_e_t_c_w_d().
|
|
|
|
SEE ALSO
|
|
|
|
chdir
|
|
|
|
|
|
|
|
|
|
|
|
GETENV
|
|
SYNOPSIS
|
|
|
|
#include <stdlib.h>
|
|
|
|
char * getenv(char * s)
|
|
extern char ** environ;
|
|
|
|
|
|
DESCRIPTION
|
|
_G_e_t_e_n_v() will search the vector of environment strings
|
|
for one matching the argument supplied, and return the
|
|
value part of that environment string. For example, if
|
|
the environment contains the string
|
|
|
|
COMSPEC=A:\COMMAND.COM
|
|
|
|
then _g_e_t_e_n_v("_C_O_M_S_P_E_C") will return A:\COMMAND.COM. The
|
|
global variable environ is a pointer to an array of
|
|
pointers to environment strings, terminated by a null
|
|
pointer. This array is initialized at startup time
|
|
under MS-DOS from the environment pointer supplied when
|
|
the program was executed. Under CP/M no such environ-
|
|
ment is supplied, so the first call to _g_e_t_e_n_v() will
|
|
attempt to open a file in the current user number on
|
|
the current drive called ENVIRON. This file should con-
|
|
tain definitions for any environment variables desired
|
|
to be accessible to the program, e.g.
|
|
|
|
HITECH=0:C:
|
|
|
|
Each variable definition should be on a separate line,
|
|
consisting of the variable name (conventionally all in
|
|
upper case) followed without intervening white space by
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 131
|
|
|
|
an equal sign ('=') then the value to be assigned to
|
|
that variable.
|
|
|
|
|
|
|
|
|
|
GETS
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
char * gets(char * s)
|
|
|
|
|
|
DESCRIPTION
|
|
_G_e_t_s() reads a line from standard input into the buffer
|
|
at s, deleting the newline (cf. _f_g_e_t_s() ). The buffer
|
|
is null terminated. It returns its argument, or NULL on
|
|
end-of-file.
|
|
|
|
SEE ALSO
|
|
|
|
fgets, freopen
|
|
|
|
|
|
|
|
|
|
|
|
GETUID (CP/M only)
|
|
SYNOPSIS
|
|
|
|
#include <sys.h>
|
|
|
|
int getuid(void)
|
|
|
|
|
|
DESCRIPTION
|
|
_G_e_t_u_i_d() returns the current user number. On CP/M, the
|
|
current user number determines the user number associ-
|
|
ated with an opened or created file, unless overridden
|
|
by an explicit user number prefix in the file name.
|
|
|
|
SEE ALSO
|
|
|
|
setuid, open
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 132 HI-TECH C USER'S MANUAL
|
|
|
|
GETW
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int getw(FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
_G_e_t_w() returns one word (16 bits for the Z80 and 8086)
|
|
from the nominated stream. EOF is returned on end-of-
|
|
file, but since this is a perfectly good word, the
|
|
_f_e_o_f() macro should be used for testing for end-of-
|
|
file. When reading the word, no special alignment in
|
|
the file is necessary, as the read is done by two con-
|
|
secutive _g_e_t_c()'s. The byte ordering is however unde-
|
|
fined. The word read should in general have been writ-
|
|
ten by _p_u_t_w().
|
|
|
|
SEE ALSO
|
|
|
|
putw, getc, fopen, fclose
|
|
|
|
|
|
|
|
|
|
|
|
GMTIME, LOCALTIME
|
|
SYNOPSIS
|
|
|
|
#include <time.h>
|
|
|
|
struct tm * gmtime(time_t * t)
|
|
struct tm * localtime(time_t * t)
|
|
|
|
|
|
DESCRIPTION
|
|
These functions convert the time pointed to by t which
|
|
is in seconds since 00:00:00 on Jan 1, 1970, into a
|
|
broken down time stored in a structure as defined in
|
|
_t_i_m_e._h. _G_m_t_i_m_e() performs a straight conversion, while
|
|
_l_o_c_a_l_t_i_m_e() takes into account the contents of the glo-
|
|
bal integer time_zone. This should contain the number
|
|
of minutes that the local time zone is WESTWARD of
|
|
Greenwich. Since there is no way under MS-DOS of actu-
|
|
ally pre-determining this value, by default _l_o_c_a_l_t_i_m_e()
|
|
will return the same result as _g_m_t_i_m_e().
|
|
|
|
SEE ALSO
|
|
|
|
ctime, asctime, time
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 133
|
|
|
|
INP, OUTP
|
|
SYNOPSIS
|
|
|
|
char inp(unsigned port)
|
|
|
|
void outp(unsigned, unsigned data)
|
|
|
|
|
|
DESCRIPTION
|
|
These routines read and write bytes to and from I/O
|
|
ports. _I_n_p() returns the data byte read from the
|
|
specified port, and _o_u_t_p() outputs the data byte to the
|
|
specified port.
|
|
|
|
|
|
|
|
|
|
INT86, INT86X, INTDOS, INTDOSX
|
|
SYNOPSIS
|
|
|
|
#include <dos.h>
|
|
|
|
int int86(int intno, union REGS * inregs,
|
|
union REGS * outregs)
|
|
int int86x(int intno, union REGS inregs,
|
|
union REGS outregs, struct SREGS * segregs)
|
|
int intdos(union REGS * inregs, union REGS * outregs)
|
|
int intdosx(union REGS * inregs, union REGS * outregs,
|
|
struct SREGS * segregs)
|
|
|
|
|
|
DESCRIPTION
|
|
These functions allow calling of software interrupts
|
|
from C programs. _I_n_t_8_6() and _i_n_t_8_6_x() execute the
|
|
software interrupt specified by _i_n_t_n_o while _i_n_t_d_o_s()
|
|
and _i_n_t_d_o_s_x() execute interrupt 21(hex), which is the
|
|
MS-DOS system call interrupt. The inregs pointer
|
|
should point to a union containing values for each of
|
|
the general purpose registers to be set when executing
|
|
the interrupt, and the values of the registers on
|
|
return are copied into the union pointed to by outregs.
|
|
The _x versions of the calls also take a pointer to a
|
|
union defining the segment register values to be set on
|
|
execution of the interrupt, though only ES and DS are
|
|
actually set from this structure.
|
|
|
|
SEE ALSO
|
|
|
|
segread
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 134 HI-TECH C USER'S MANUAL
|
|
|
|
ISALNUM, ISALPHA, ISDIGIT, ISLOWER et. al.
|
|
SYNOPSIS
|
|
|
|
#include <ctype.h>
|
|
|
|
isalnum(char c)
|
|
isalpha(char c)
|
|
isascii(char c)
|
|
iscntrl(char c)
|
|
isdigit(char c)
|
|
islower(char c)
|
|
isprint(char c)
|
|
isgraph(char c)
|
|
ispunct(char c)
|
|
isspace(char c)
|
|
isupper(char c)
|
|
char c;
|
|
|
|
|
|
DESCRIPTION
|
|
These macros, defined in ctype.h, test the supplied
|
|
character for membership in one of several overlapping
|
|
groups of characters. Note that all except isascii are
|
|
defined for _c iff _i_s_a_s_c_i_i(_c) is true.
|
|
|
|
isalnum(c) c is alphanumeric
|
|
isalpha(c) c is in A-Z or a-z
|
|
isascii(c) c is a 7 bit ascii character
|
|
iscntrl(c) c is a control character
|
|
isdigit(c) c is a decimal digit
|
|
islower(c) c is in a-z
|
|
isprint(c) c is a printing char
|
|
isgraph(c) c is a non-space printable character
|
|
ispunct(c) c is not alphanumeric
|
|
isspace(c) c is a space, tab or newline
|
|
isupper(c) c is in A-Z
|
|
isxdigit(c) c is in 0-9 or a-f or A-F
|
|
|
|
|
|
SEE ALSO
|
|
|
|
toupper, tolower, toascii
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 135
|
|
|
|
ISATTY
|
|
SYNOPSIS
|
|
|
|
#include <unixio.h>
|
|
|
|
int isatty(int fd)
|
|
|
|
|
|
DESCRIPTION
|
|
This tests the type of the file associated with fd. It
|
|
returns true if the file is attached to a tty-like dev-
|
|
ice. This would normally be used for testing if stan-
|
|
dard input is coming from a file or the console. For
|
|
testing STDIO streams, use _i_s_a_t_t_y(_f_i_l_e_n_o(_s_t_r_e_a_m)).
|
|
|
|
|
|
|
|
|
|
KBHIT
|
|
SYNOPSIS
|
|
|
|
#include <conio.h>
|
|
|
|
int kbhit(void)
|
|
|
|
|
|
DESCRIPTION
|
|
This function returns 1 if a character has been pressed
|
|
on the console keyboard, 0 otherwise. Normally the
|
|
character would then be read via _g_e_t_c_h().
|
|
|
|
SEE ALSO
|
|
|
|
getch, getche
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 136 HI-TECH C USER'S MANUAL
|
|
|
|
LONGJMP
|
|
SYNOPSIS
|
|
|
|
#include <setjmp.h>
|
|
|
|
void longjmp(jmp_buf buf, int val)
|
|
|
|
|
|
DESCRIPTION
|
|
_L_o_n_g_j_m_p(), in conjunction with _s_e_t_j_m_p(), provides a
|
|
mechanism for non-local gotos. To use this facility,
|
|
_s_e_t_j_m_p() should be called with a jmp_buf argument in
|
|
some outer level function. The call from _s_e_t_j_m_p() will
|
|
return 0. To return to this level of execution,
|
|
_l_o_n_j_m_p() may be called with the same jmp_buf argument
|
|
from an inner level of execution. Note however that the
|
|
function which called _s_e_t_j_m_p() must still be active
|
|
when _l_o_n_g_j_m_p() is called. Breach of this rule will
|
|
cause disaster, due to the use of a stack containing
|
|
invalid data. The val argument to _l_o_n_g_j_m_p() will be the
|
|
value apparently returned from the _s_e_t_j_m_p(). This
|
|
should normally be non-zero, to distinguish it from the
|
|
genuine _s_e_t_j_m_p() call. For example:
|
|
|
|
#include <setjmp.h>
|
|
|
|
static jmp_buf jb_err;
|
|
|
|
main()
|
|
{
|
|
if(setjmp(jb_err)) {
|
|
printf("An error occured0);
|
|
exit(1);
|
|
}
|
|
a_func();
|
|
}
|
|
|
|
a_func()
|
|
{
|
|
if(do_whatever() != 0)
|
|
longjmp(jb_err, 1);
|
|
if(do_something_else() != 0)
|
|
longjmp(jb_err, 2);
|
|
}
|
|
|
|
|
|
The calls to _l_o_n_g_j_m_p() above will never return; rather
|
|
the call to _s_e_t_j_m_p() will appear to return, but with a
|
|
return value equal to the argument supplied to
|
|
_l_o_n_g_j_m_p().
|
|
|
|
SEE ALSO
|
|
|
|
setjmp
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 137
|
|
|
|
LSEEK
|
|
SYNOPSIS
|
|
|
|
#include <unixio.h>
|
|
|
|
long lseek(int fd, long offs, int wh)
|
|
|
|
|
|
DESCRIPTION
|
|
This function operates in an analogous manner to
|
|
_f_s_e_e_k(), however it does so on unbuffered low-level i/o
|
|
file descriptors, rather than on STDIO streams. It also
|
|
returns the resulting pointer location. Thus _l_s_e_e_k(_f_d,
|
|
_0_L, _1) returns the current pointer location without
|
|
moving it. -1 is returned on error.
|
|
|
|
SEE ALSO
|
|
|
|
open, close, read, write
|
|
|
|
|
|
|
|
|
|
|
|
MALLOC
|
|
SYNOPSIS
|
|
|
|
#include <stdlib.h>
|
|
|
|
void * malloc(size_t cnt)
|
|
|
|
|
|
DESCRIPTION
|
|
_M_a_l_l_o_c() attempts to allocate cnt bytes of memory from
|
|
the "heap", the dynamic memory allocation area. If suc-
|
|
cessful, it returns a pointer to the block, otherwise 0
|
|
is returned. The memory so allocated may be freed with
|
|
_f_r_e_e(), or changed in size via _r_e_a_l_l_o_c(). _M_a_l_l_o_c()
|
|
calls _s_b_r_k() to obtain memory, and is in turn called by
|
|
_c_a_l_l_o_c(). _M_a_l_l_o_c() does not clear the memory it
|
|
obtains.
|
|
|
|
SEE ALSO
|
|
|
|
calloc, free, realloc
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 138 HI-TECH C USER'S MANUAL
|
|
|
|
MEMSET, MEMCPY, MEMCMP, MEMMOVE
|
|
SYNOPSIS
|
|
|
|
#include <string.h>
|
|
|
|
void memset(void s, char c, size_t n)
|
|
void * memcpy(void * d, void * s, size_t n)
|
|
int memcmp(void * s1, void * s2, size_t n)
|
|
void * memmove(void * s1, void * s2, size_t n)
|
|
void * memchr(void * s, int c, size_t n)
|
|
|
|
|
|
DESCRIPTION
|
|
_M_e_m_s_e_t() initializes n bytes of memory starting at the
|
|
location pointed to by s with the character c. _M_e_m_c_p_y()
|
|
copies n bytes of memory starting from the location
|
|
pointed to by s to the block of memory pointed to by d.
|
|
The result of copying overlapping blocks is undefined.
|
|
_M_e_m_c_m_p() compares two blocks of memory, of length n,
|
|
and returns a signed value similar to _s_t_r_n_c_m_p(). Unlike
|
|
_s_t_r_n_c_m_p() the comparision does not stop on a null char-
|
|
acter. The ascii collating sequence is used for the
|
|
comparision, but the effect of including non-ascii
|
|
characters in the memory blocks on the sense of the
|
|
return value is indeterminate. _M_e_m_m_o_v_e() is similar to
|
|
_m_e_m_c_p_y() except copying of overlapping blocks is han-
|
|
dled correctly. The _m_e_m_c_h_r() function locates the first
|
|
occurence of c (converted to unsigned char) in the ini-
|
|
tial n characters of the object pointed to by s.
|
|
|
|
SEE ALSO
|
|
|
|
strncpy, strncmp, strchr
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 139
|
|
|
|
MKDIR, RMDIR
|
|
SYNOPSIS
|
|
|
|
#include <sys.h>
|
|
|
|
int mkdir(char * s)
|
|
int rmdir(char * s)
|
|
|
|
|
|
DESCRIPTION
|
|
These functions allow the creation (_m_k_d_i_r()) and dele-
|
|
tion (_r_m_d_i_r()) of sub-directories under the MS-DOS
|
|
operating system. The argument s may be an arbitrary
|
|
pathname, and the return value will be -1 if the crea-
|
|
tion or removal was unsuccessful.
|
|
|
|
SEE ALSO
|
|
|
|
chdir
|
|
|
|
|
|
|
|
|
|
|
|
MSDOS, MSDOSCX
|
|
SYNOPSIS
|
|
|
|
#include <dos.h>
|
|
|
|
long msdos(int ax, int dx, int cx,
|
|
int bx, int si, int di)
|
|
long msdoscx(int ax, int dx, int cx,
|
|
int bx, int si, int di)
|
|
|
|
|
|
DESCRIPTION
|
|
These functions allow direct access to MS-DOS system
|
|
calls. The arguments will be placed in the registers
|
|
implied by their names, while the return value will be
|
|
the contents of AX and DX (for _m_s_d_o_s()) or the contents
|
|
of DX and CX (for _m_s_d_o_s_c_x()). Only as many arguments
|
|
as necessary need be supplied, e.g. if only AH and DX
|
|
need have specified valued, then only 2 argument would
|
|
be required. The following piece of code outputs a
|
|
form-feed to the printer.
|
|
|
|
msdos(0x500, '\f');
|
|
|
|
Note that the system call number (in this case 5) must
|
|
be multiplied by 0x100 since MS-DOS expects the call
|
|
number in AH, the high byte of AX.
|
|
|
|
SEE ALSO
|
|
|
|
intdos, intdosx, int86, int86x
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 140 HI-TECH C USER'S MANUAL
|
|
|
|
OPEN
|
|
SYNOPSIS
|
|
|
|
#include <unixio.h>
|
|
|
|
int open(char * name, int mode)
|
|
|
|
|
|
DESCRIPTION
|
|
_O_p_e_n() is the fundamental means of opening files for
|
|
reading and writing. The file specified by name is
|
|
sought, and if found is opened for reading, writing or
|
|
both. Mode is encoded as follows:
|
|
|
|
Mode Meaning
|
|
0 Open for reading only
|
|
1 Open for writing only
|
|
2 Open for both reading and writing
|
|
|
|
|
|
The file must already exist - if it does not, _c_r_e_a_t()
|
|
should be used to create it. On a successful open, a
|
|
file descriptor is returned. This is a non-negative
|
|
integer which may be used to refer to the open file
|
|
subsequently. If the open fails, -1 is returned. The
|
|
syntax of a CP/M filename is:
|
|
|
|
[uid:][drive:]name.type
|
|
|
|
|
|
where uid is a decimal number 0 to 15, drive is a
|
|
letter A to P or a to p, name is 1 to 8 characters and
|
|
type is 0 to 3 characters. Though there are few
|
|
inherent restrictions on the characters in the name and
|
|
type, it is recommended that they be restricted to the
|
|
alphanumerics and standard printing characters. Use of
|
|
strange characters may cause problems in accessing
|
|
and/or deleting the file.
|
|
|
|
One or both of uid: and drive: may be omitted; if both
|
|
are supplied, the uid: must come first. Note that the [
|
|
and ] are meta-symbols only. Some examples are:
|
|
|
|
fred.dat
|
|
file.c
|
|
0:xyz.com
|
|
0:a:file1.p
|
|
a:file2.
|
|
|
|
|
|
If the uid: is omitted, the file will be sought with
|
|
uid equal to the current user number, as returned by
|
|
getuid(). If drive: is omitted, the file will be sought
|
|
on the currently selected drive. The following special
|
|
file names are recognized:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 141
|
|
|
|
|
|
lst: Accesses the list device - write only
|
|
pun: Accesses the punch device - write only
|
|
rdr: Accesses the reader device - read only
|
|
con: Accesses the system console - read/write
|
|
|
|
|
|
File names may be in any case - they are converted to
|
|
upper case during processing of the name.
|
|
|
|
MS-DOS filenames may be any valid MS-DOS 2.xx filename,
|
|
e.g.
|
|
|
|
fred.nrk
|
|
A:\HITECH\STDIO.H
|
|
|
|
|
|
The special device names (e.g. CON, LST) are also
|
|
recognized. These do not require (and should not have)
|
|
a trailing colon.
|
|
|
|
SEE ALSO
|
|
|
|
close, fopen, fclose, read, write, creat
|
|
|
|
|
|
|
|
|
|
|
|
PERROR
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
void perror(char * s)
|
|
|
|
|
|
DESCRIPTION
|
|
This routine will print on the stderr stream the argu-
|
|
ment s, followed by a descriptive message detailing the
|
|
last error returned from an open, close read or write
|
|
call. Unfortunately CP/M does not provide definitive
|
|
information relating to the error, except in the case
|
|
of a random read or write. Thus this routine is of lim-
|
|
ited usefulness under CP/M. MS-DOS provides much more
|
|
information however, and use of _p_e_r_r_o_r() after MS-DOS
|
|
file handling calls will certainly give useful diagnos-
|
|
tics.
|
|
|
|
SEE ALSO
|
|
|
|
open, close, read, write
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 142 HI-TECH C USER'S MANUAL
|
|
|
|
PRINTF, VPRINTF
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int printf(char * fmt, ...)
|
|
int vprintf(char * fmt, va_list va_arg)
|
|
|
|
|
|
DESCRIPTION
|
|
_P_r_i_n_t_f() is a formatted output routine, operating on
|
|
stdout. There are corresponding routines operating on a
|
|
given stream (_f_p_r_i_n_t_f()) or into a string buffer
|
|
(_s_p_r_i_n_t_f()). _P_r_i_n_t_f() is passed a format string, fol-
|
|
lowed by a list of zero or more arguments. In the for-
|
|
mat string are conversion specifications, each of which
|
|
is used to print out one of the argument list values.
|
|
Each conversion specification is of the form %m.nc
|
|
where the percent symbol % introduces a conversion,
|
|
followed by an optional width specification m. n is an
|
|
optional precision specification (introduced by the
|
|
dot) and c is a letter specifying the type of the
|
|
conversion. A minus sign ('-') preceding m indicates
|
|
left rather than right adjustment of the converted
|
|
value in the field. Where the field width is larger
|
|
than required for the conversion, blank padding is per-
|
|
formed at the left or right as specified. Where right
|
|
adjustment of a numeric conversion is specified, and
|
|
the first digit of m is 0, then padding will be per-
|
|
formed with zeroes rather than blanks.
|
|
|
|
If the character * is used in place of a decimal con-
|
|
stant, e.g. in the format %*d, then one integer argu-
|
|
ment will be taken from the list to provide that value.
|
|
The types of conversion are:
|
|
|
|
f Floating point - m is the total width and n is the
|
|
number of digits after the decimal point. If n is
|
|
omitted it defaults to 6.
|
|
|
|
e Print the corresponding argument in scientific nota-
|
|
tion. Otherwise similar to f.
|
|
|
|
g Use e or f format, whichever gives maximum precision in
|
|
minimum width.
|
|
|
|
o x X u d
|
|
Integer conversion - in radices 8, 16, 10 and 10
|
|
respectively. The conversion is signed in the case of
|
|
d, unsigned otherwise. The precision value is the total
|
|
number of digits to print, and may be used to force
|
|
leading zeroes. E.g. %8.4x will print at least 4 hex
|
|
digits in an 8 wide field. Preceding the key letter
|
|
with an l indicates that the value argument is a long
|
|
integer or unsigned value. The letter X prints out
|
|
hexadecimal numbers using the upper case letters _A-_F
|
|
rather than _a-_f as would be printed when using x.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 143
|
|
|
|
s Print a string - the value argument is assumed to be a
|
|
character pointer. At most n characters from the string
|
|
will be printed, in a field m characters wide.
|
|
|
|
c The argument is assumed to be a single character and is
|
|
printed literally.
|
|
|
|
Any other characters used as conversion specifications
|
|
will be printed. Thus %% will produce a single percent
|
|
sign. Some examples:
|
|
|
|
printf("Total = %4d%%", 23)
|
|
yields 'Total =23%'
|
|
printf("Size is %lx" , size)
|
|
where size is a long, prints size
|
|
as hexadecimal.
|
|
printf("Name = %.8s", "a1234567890")
|
|
yields 'Name = a1234567'
|
|
printf("xx%*d", 3, 4)
|
|
yields 'xx 4'
|
|
|
|
|
|
Printf returns EOF on error, 0 otherwise. _V_p_r_i_n_t_f() is
|
|
similar to _p_r_i_n_t_f() but takes a variable argument list
|
|
pointer rather than a list of arguments. See the
|
|
description of _v_a__s_t_a_r_t() for more information on vari-
|
|
able argument lists.
|
|
|
|
SEE ALSO
|
|
|
|
fprintf, sprintf
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 144 HI-TECH C USER'S MANUAL
|
|
|
|
PUTC
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int putc(int c, FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
_P_u_t_c() is the macro version of _f_p_u_t_c() and is defined
|
|
in stdio.h. See _f_p_u_t_c() for a description of its
|
|
behaviour.
|
|
|
|
SEE ALSO
|
|
|
|
fputc, getc, fopen, fclose
|
|
|
|
|
|
|
|
|
|
|
|
PUTCHAR
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int putchar(int c)
|
|
|
|
|
|
DESCRIPTION
|
|
_P_u_t_c_h_a_r() is a _p_u_t_c() operation on stdout, defined in
|
|
stdio.h.
|
|
|
|
SEE ALSO
|
|
|
|
putc, getc, freopen, fclose
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 145
|
|
|
|
PUTS
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int puts(char * s)
|
|
|
|
|
|
DESCRIPTION
|
|
_P_u_t_s() writes the string s to the stdout stream,
|
|
appending a newline. The null terminating the string is
|
|
not copied. EOF is returned on error.
|
|
|
|
SEE ALSO
|
|
|
|
fputs, gets, freopen, fclose
|
|
|
|
|
|
|
|
|
|
|
|
PUTW
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int putw(int w, FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
_P_u_t_w() copies the word w to the given stream. It
|
|
returns w, except on error, in which case EOF is
|
|
returned. Since this is a good integer, _f_e_r_r_o_r() should
|
|
be used to check for errors.
|
|
|
|
SEE ALSO
|
|
|
|
getw, fopen, fclose
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 146 HI-TECH C USER'S MANUAL
|
|
|
|
QSORT
|
|
SYNOPSIS
|
|
|
|
#include <stdlib.h>
|
|
|
|
void qsort(void * base, size_t nel,
|
|
size_t width, int (*func)())
|
|
|
|
|
|
DESCRIPTION
|
|
_Q_s_o_r_t() is an implementation of the quicksort algo-
|
|
rithm. It sorts an array of nel items, each of length
|
|
width bytes, located contiguously in memory at base.
|
|
Func is a pointer to a function used by _q_s_o_r_t() to com-
|
|
pare items. It calls func with pointers to two items to
|
|
be compared. If the first item is considered to be
|
|
greater than, equal to or less than the second then
|
|
_f_u_n_c() should return a value greater than zero, equal
|
|
to zero or less than zero respectively.
|
|
|
|
static short array[100];
|
|
|
|
#define SIZE sizeof array/sizeof array[0]
|
|
a_func(p1, p2)
|
|
short * p1, * p2;
|
|
{
|
|
return *p1 - *p2;
|
|
}
|
|
|
|
sort_em()
|
|
{
|
|
qsort(array, SIZE,
|
|
sizeof array[0], a_func);
|
|
}
|
|
|
|
|
|
This will sort the array into ascending values. Note
|
|
the use of sizeof to make the code independent of the
|
|
size of a short, or the number of elements in the
|
|
array.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 147
|
|
|
|
RAND
|
|
SYNOPSIS
|
|
|
|
#include <stdlib.h>
|
|
|
|
int rand(void)
|
|
|
|
|
|
DESCRIPTION
|
|
_R_a_n_d() is a pseudo-random number generator. It returns
|
|
an integer in the range 0 to 32767, which changes in a
|
|
pseudo-random fashion on each call.
|
|
|
|
SEE ALSO
|
|
|
|
srand
|
|
|
|
|
|
|
|
|
|
|
|
READ
|
|
SYNOPSIS
|
|
|
|
#include <unixio.h>
|
|
|
|
int read(int fd, void * buf, size_t cnt)
|
|
|
|
|
|
DESCRIPTION
|
|
_R_e_a_d() will read from the file associated with fd up to
|
|
cnt bytes into a buffer located at buf. It returns the
|
|
number of bytes actually read. A zero return indicates
|
|
end-of-file. A negative return indicates error. Fd
|
|
should have been obtained from a previous call to
|
|
_o_p_e_n(). It is possible for _r_e_a_d() to return less bytes
|
|
than requested, e.g. when reading from the console, in
|
|
which case _r_e_a_d() will read one line of input.
|
|
|
|
SEE ALSO
|
|
|
|
open, close, write
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 148 HI-TECH C USER'S MANUAL
|
|
|
|
REALLOC
|
|
SYNOPSIS
|
|
|
|
void * realloc(void * ptr, size_t cnt)
|
|
|
|
|
|
DESCRIPTION
|
|
_R_e_a_l_l_o_c() frees the block of memory at ptr, which
|
|
should have been obtained by a previous call to _m_a_l_-
|
|
_l_o_c(), _c_a_l_l_o_c() or _r_e_a_l_l_o_c(), then attempts to allocate
|
|
cnt bytes of dynamic memory, and if successful copies
|
|
the contents of the block of memory located at ptr into
|
|
the new block. At most, _r_e_a_l_l_o_c() will copy the number
|
|
of bytes which were in the old block, but if the new
|
|
block is smaller, will only copy cnt bytes. If the
|
|
block could not be allocated, 0 is returned.
|
|
|
|
SEE ALSO
|
|
|
|
malloc, calloc, realloc
|
|
|
|
|
|
|
|
|
|
|
|
REMOVE
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int remove(char * s)
|
|
|
|
|
|
DESCRIPTION
|
|
_R_e_m_o_v_e() will attempt to remove the file named by the
|
|
argument s from the directory. A return value of -1
|
|
indicates that the attempt failed.
|
|
|
|
SEE ALSO
|
|
|
|
unlink
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 149
|
|
|
|
RENAME
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int rename(char * name1, char * name2)
|
|
|
|
|
|
DESCRIPTION
|
|
The file named by name1 will be renamed to name2. -1
|
|
will be returned if the rename was not successful. Note
|
|
that renames across user numbers or drives are not per-
|
|
mitted.
|
|
|
|
SEE ALSO
|
|
|
|
open, close, unlink
|
|
|
|
|
|
|
|
|
|
|
|
REWIND
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int rewind(FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
This function will attempt to re-position the
|
|
read/write pointer of the nominated stream to the
|
|
beginning of the file. A return value of -1 indicates
|
|
that the attempt was not successful, perhaps because
|
|
the stream is associated with a non-random access file
|
|
such as a character device.
|
|
|
|
SEE ALSO
|
|
|
|
fseek, ftell
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 150 HI-TECH C USER'S MANUAL
|
|
|
|
SBRK
|
|
SYNOPSIS
|
|
|
|
char * sbrk(int incr)
|
|
|
|
|
|
DESCRIPTION
|
|
_S_b_r_k() increments the current highest memory location
|
|
allocated to the program by incr bytes. It returns a
|
|
pointer to the previous highest location. Thus _s_b_r_k(_0)
|
|
returns a pointer to the current highest location,
|
|
without altering its value. If there is insufficient
|
|
memory to satisfy the request, -1 is returned.
|
|
|
|
SEE ALSO
|
|
|
|
brk, malloc, calloc, realloc, free
|
|
|
|
|
|
|
|
|
|
|
|
SCANF
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int scanf(char * fmt, ...)
|
|
int vscanf(char *, va_list ap);
|
|
|
|
|
|
DESCRIPTION
|
|
_S_c_a_n_f() performs formatted input ("de-editing") from
|
|
the stdin stream. Similar functions are available for
|
|
streams in general, and for strings. The function
|
|
_v_s_c_a_n_f() is similar, but takes a pointer to an argument
|
|
list rather than a series of additional arguments. This
|
|
pointer should have been initialized with _v_a__s_t_a_r_t().
|
|
The input conversions are performed according to the
|
|
fmt string; in general a character in the format string
|
|
must match a character in the input; however a space
|
|
character in the format string will match zero or more
|
|
"white space" characters in the input, i.e. spaces,
|
|
tabs or newlines. A conversion specification takes the
|
|
form of the character %, optionally followed by an
|
|
assignment suppression character ('*'), optionally fol-
|
|
lowed by a numerical maximum field width, followed by a
|
|
conversion specification character. Each conversion
|
|
specification, unless it incorporates the assignment
|
|
suppression character, will assign a value to the vari-
|
|
able pointed at by the next argument. Thus if there are
|
|
two conversion specifications in the fmt string, there
|
|
should be two additional pointer arguments. The
|
|
conversion characters are as follows:
|
|
|
|
o x d
|
|
Skip white space, then convert a number in base 8, 16
|
|
or 10 radix respectively. If a field width was
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 151
|
|
|
|
supplied, take at most that many characters from the
|
|
input. A leading minus sign will be recognized.
|
|
|
|
f Skip white space, then convert a floating number in
|
|
either conventional or scientific notation. The field
|
|
width applies as above.
|
|
|
|
s Skip white space, then copy a maximal length sequence
|
|
of non-white-space characters. The pointer argument
|
|
must be a pointer to char. The field width will limit
|
|
the number of characters copied. The resultant string
|
|
will be null-terminated.
|
|
|
|
c Copy the next character from the input. The pointer
|
|
argument is assumed to be a pointer to char. If a field
|
|
width is specified, then copy that many characters.
|
|
This differs from the s format in that white space does
|
|
not terminate the character sequence.
|
|
|
|
The conversion characters o, x, u, d and f may be pre-
|
|
ceded by an l to indicate that the corresponding
|
|
pointer argument is a pointer to long or double as
|
|
appropriate. A preceding h will indicate that the
|
|
pointer argument is a pointer to short rather than int.
|
|
|
|
_S_c_a_n_f() returns the number of successful conversions;
|
|
EOF is returned if end-of-file was seen before any
|
|
conversions were performed. Some examples are:
|
|
|
|
scanf("%d %s", &a, &s)
|
|
with input "12s"
|
|
will assign 12 to a, and "s" to s.
|
|
|
|
scanf("%4cd %lf", &c, &f)
|
|
with input " abcd -3.5"
|
|
will assign " abc" to c, and -3.5 to f.
|
|
|
|
|
|
SEE ALSO
|
|
|
|
fscanf, sscanf, printf, va_arg
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 152 HI-TECH C USER'S MANUAL
|
|
|
|
SEGREAD
|
|
SYNOPSIS
|
|
|
|
#include <dos.h>
|
|
int segread(struct SREGS * segregs)
|
|
|
|
|
|
DESCRIPTION
|
|
_S_e_g_r_e_a_d() copies the values of the segment registers
|
|
into the structure pointed to by segregs.
|
|
|
|
SEE ALSO
|
|
|
|
int86, int86x, intdos, intdosx
|
|
|
|
|
|
|
|
|
|
|
|
SETJMP
|
|
SYNOPSIS
|
|
|
|
#include <setjmp.h>
|
|
int setjmp(jmp_buf buf)
|
|
|
|
|
|
DESCRIPTION
|
|
_S_e_t_j_m_p() is used with _l_o_n_g_j_m_p() for non-local gotos.
|
|
See _l_o_n_g_j_m_p() for further information.
|
|
|
|
SEE ALSO
|
|
|
|
longjmp
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 153
|
|
|
|
SETUID (CP/M only)
|
|
SYNOPSIS
|
|
|
|
#include <sys.h>
|
|
|
|
void setuid(int uid)
|
|
|
|
|
|
DESCRIPTION
|
|
_S_e_t_u_i_d() will set the current user number to uid. Uid
|
|
should be a number in the range 0-15.
|
|
|
|
SEE ALSO
|
|
|
|
getuid
|
|
|
|
|
|
|
|
|
|
|
|
SETVBUF, SETBUF
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int setvbuf(FILE * stream, char * buf,
|
|
int mode, size_t size);
|
|
void setbuf(FILE * stream, char * buf)
|
|
|
|
|
|
DESCRIPTION
|
|
The _s_e_t_v_b_u_f() function allows the buffering behaviour
|
|
of a STDIO stream to be altered. It supersedes the
|
|
function _s_e_t_b_u_f() which is retained for backwards com-
|
|
patibility. The arguments to _s_e_t_v_b_u_f() are as follows:
|
|
stream designates the STDIO stream to be affected; buf
|
|
is a pointer to a buffer which will be used for all
|
|
subsequent I/O operations on this stream. If buf is
|
|
null, then the routine will allocate a buffer from the
|
|
heap if necessary, of size BUFSIZ as defined in
|
|
<stdio.h>. mode may take the values _IONBF, to turn
|
|
buffering off completely, _IOFBF, for full buffering,
|
|
or _IOLBF for line buffering. Full buffering means that
|
|
the associated buffer will only be flushed when full,
|
|
while line buffering means that the buffer will be
|
|
flushed at the end of each line or when input is
|
|
requested from another STDIO stream. size is the size
|
|
of the buffer supplied. For example:
|
|
|
|
setvbuf(stdout, my_buf, _IOLBF, sizeof my_buf);
|
|
|
|
If a buffer is supplied by the caller, that buffer will
|
|
remain associated with that stream even over_f_c_l_o_s_e(),
|
|
_f_o_p_e_n() calls until another _s_e_t_v_b_u_f() changes it.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 154 HI-TECH C USER'S MANUAL
|
|
|
|
SEE ALSO
|
|
|
|
fopen, freopen, fclose
|
|
|
|
|
|
|
|
|
|
|
|
SET_VECTOR
|
|
SYNOPSIS
|
|
|
|
#include <intrpt.h>
|
|
typedef interrupt void (*isr)();
|
|
isr set_vector(isr * vector, isr func);
|
|
|
|
|
|
DESCRIPTION
|
|
This routine allows an interrupt vector to be initial-
|
|
ized. The first argument should be the address of the
|
|
interrupt vector (not the vector number but the actual
|
|
address) cast to a pointer to _i_s_r, which is a typedef'd
|
|
pointer to an interrupt function. The second argument
|
|
should be the function which you want the interrupt
|
|
vector to point to. This must be declared using the
|
|
_i_n_t_e_r_r_u_p_t type qualifier. The return value of
|
|
_s_e_t__v_e_c_t_o_r() is the previous contents of the vector.
|
|
|
|
SEE ALSO
|
|
|
|
di(), ei()
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 155
|
|
|
|
SIGNAL
|
|
SYNOPSIS
|
|
|
|
#include <signal.h>
|
|
void (* signal)(int sig, void (*func)());
|
|
|
|
|
|
DESCRIPTION
|
|
_S_i_g_n_a_l() provides a mechanism for catching control-C's
|
|
(ctrl-BREAK for MS-DOS) typed on the console during
|
|
I/O. Under CP/M the console is polled whenever an I/O
|
|
call is performed, while for MS-DOS the polling depends
|
|
on the setting of the BREAK command. If a control-C is
|
|
detected certain action will be performed. The default
|
|
action is to exit summarily; this may be modified with
|
|
_s_i_g_n_a_l(). The sig argument to signal may at the present
|
|
time be only SIGINT, signifying an interrupt condition.
|
|
The func argument may be one of SIG_DFL, representing
|
|
the default action, SIG_IGN, to ignore control-C's com-
|
|
pletely, or the address of a function which will be
|
|
called with one argument, the number of the signal
|
|
caught, when a control-C is seen. As the only signal
|
|
supported is SIGINT, this will always be the value of
|
|
the argument to the called function.
|
|
|
|
SEE ALSO
|
|
|
|
exit
|
|
|
|
|
|
|
|
|
|
|
|
SIN
|
|
SYNOPSIS
|
|
|
|
#include <math.h>
|
|
|
|
double sin(double f);
|
|
|
|
|
|
DESCRIPTION
|
|
This function returns the sine function of its argu-
|
|
ment.
|
|
|
|
SEE ALSO
|
|
|
|
cos, tan, asin, acos, atan
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 156 HI-TECH C USER'S MANUAL
|
|
|
|
SPAWNL, SPAWNV, SPAWNVE
|
|
SYNOPSIS
|
|
|
|
int spawnl(char * n, char * argv0, ...);
|
|
int spawnv(cahr * n, char ** v)
|
|
int spawnve(char * n, char ** v, char ** e)
|
|
|
|
|
|
DESCRIPTION
|
|
These functions will load and execute a sub-program,
|
|
named by the argument n. The calling conventions are
|
|
similar to the functions _e_x_e_c_l() and _e_x_e_c_v(), the
|
|
difference being that the spawn functions return to the
|
|
calling program after termination of the sub-program,
|
|
while the exec functions return only if the program
|
|
could not be executed. _S_p_a_w_n_v_e() takes an environment
|
|
list in the same format as the argument list which will
|
|
be supplied to the executed program as its environment.
|
|
|
|
SEE ALSO
|
|
|
|
execl, execv
|
|
|
|
|
|
|
|
|
|
|
|
SPRINTF
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int sprintf(char * buf, char * fmt, ...);
|
|
int vsprintf(char * buf, char * fmt, va_list ap);
|
|
|
|
|
|
DESCRIPTION
|
|
_S_p_r_i_n_t_f() operates in a similar fashion to _p_r_i_n_t_f(),
|
|
except that instead of placing the converted output on
|
|
the stdout stream, the characters are placed in the
|
|
buffer at buf. The resultant string will be null-
|
|
terminated, and the number of characters in the buffer
|
|
will be returned. _V_s_p_r_i_n_t_f takes an argument pointer
|
|
rather than a list of arguments.
|
|
|
|
SEE ALSO
|
|
|
|
printf, fprintf, sscanf
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 157
|
|
|
|
SQRT
|
|
SYNOPSIS
|
|
|
|
#include <math.h>
|
|
|
|
double sqrt(double f)
|
|
|
|
|
|
DESCRIPTION
|
|
_S_q_r_t() implements a square root function using Newton's
|
|
approximation.
|
|
|
|
SEE ALSO
|
|
|
|
exp
|
|
|
|
|
|
|
|
|
|
|
|
SSCANF
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int sscanf(char * buf, char * fmt, ...);
|
|
int vsscanf(char * buf, char * fmt, va_list ap);
|
|
|
|
|
|
DESCRIPTION
|
|
_S_s_c_a_n_f() operates in a similar manner to _s_c_a_n_f(),
|
|
except that instead of the conversions being taken from
|
|
stdin, they are taken from the string at buf.
|
|
|
|
SEE ALSO
|
|
|
|
scanf, fscanf, sprintf
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 158 HI-TECH C USER'S MANUAL
|
|
|
|
SRAND
|
|
SYNOPSIS
|
|
|
|
#include <stdlib.h>
|
|
|
|
void srand(int seed)
|
|
|
|
|
|
DESCRIPTION
|
|
_S_r_a_n_d() initializes the random number generator
|
|
accessed by _r_a_n_d() with the given seed. This provides a
|
|
mechanism for varying the starting point of the
|
|
pseudo-random sequence yielded by _r_a_n_d(). On the z80, a
|
|
good place to get a truly random seed is from the
|
|
refresh register. Otherwise timing a response from the
|
|
console will do.
|
|
|
|
SEE ALSO
|
|
|
|
rand
|
|
|
|
|
|
|
|
|
|
|
|
STAT
|
|
SYNOPSIS
|
|
|
|
#include <stat.h>
|
|
|
|
int stat(char * name, struct stat * statbuf)
|
|
|
|
|
|
DESCRIPTION
|
|
This routine returns information about the file by
|
|
name. The information returned is operating system
|
|
dependent, but may include file attributes (e.g. read
|
|
only), file size in bytes, and file modification and/or
|
|
access times. The argument name should be the name of
|
|
the file, and may include path names under DOS, user
|
|
numbers under CP/M, etc. The argument statbuf should
|
|
be the address of a structure as defined in _s_t_a_t._h
|
|
which will be filled in with the information about the
|
|
file. The structure of _s_t_r_u_c_t _s_t_a_t is as follows:
|
|
|
|
struct stat
|
|
{
|
|
short st_mode; /* flags */
|
|
long st_atime; /* access time */
|
|
long st_mtime; /* modification time */
|
|
long st_size; /* file size */
|
|
};
|
|
|
|
|
|
The access and modification times (under DOS these
|
|
are both set to the modification time) are in
|
|
seconds since 00:00:00 Jan 1 1970. The function
|
|
_c_t_i_m_e() may be used to convert this to a readable
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 159
|
|
|
|
value. The file size is self explanatory. The
|
|
flag bits are as follows:
|
|
|
|
Flag Meaning
|
|
____________________________________
|
|
S_IFMT mask for file type
|
|
S_IFDIR file is a directory
|
|
S_IFREG file is a regular file
|
|
S_IREAD file is readable
|
|
S_IWRITE file is writeable
|
|
S_IEXEC file is executable
|
|
S_HIDDEN file is hidden
|
|
S_SYSTEM file is marked system
|
|
S_ARCHIVE file has been written to
|
|
|
|
|
|
_S_t_a_t returns 0 on success, -1 on failure, e.g. if
|
|
the file could not be found.
|
|
|
|
SEE ALSO
|
|
|
|
ctime, creat, chmod
|
|
|
|
|
|
|
|
|
|
|
|
STRCAT, STRCMP, STRCPY, STRLEN et. al.
|
|
SYNOPSIS
|
|
|
|
#include <string.h>
|
|
|
|
char * strcat(char * s1, char * s2);
|
|
int strcmp(char * s1, char * s2);
|
|
char * strcpy(char * s1, char * s2);
|
|
int strlen(char * s);
|
|
char * strncat(char * s1, char * s2, size_t n);
|
|
int strncmp(char * s1, char * s2, size_t n);
|
|
char * strncpy(char * s1, char * s2, size_t n);
|
|
|
|
|
|
DESCRIPTION
|
|
These functions provide operations on null-terminated
|
|
strings. _S_t_r_c_a_t() appends the string s2 to the end of
|
|
the string s1. The string at s1 will be null ter-
|
|
minated. Needless to say the buffer at s1 must be big
|
|
enough. _S_t_r_c_m_p() compares the two strings and returns a
|
|
number greater than 0, 0 or a number less than 0
|
|
according to whether s1 is greater than, equal to or
|
|
less than s2. The comparision is via the ascii collat-
|
|
ing order, with the first character the most signifi-
|
|
cant. _S_t_r_c_p_y() copies s2 into the buffer at s1, null
|
|
terminating it. _S_t_r_l_e_n() returns the length of s1, not
|
|
including the terminating null. _S_t_r_n_c_a_t(), _s_t_r_n_c_m_p()
|
|
and _s_t_r_n_c_p_y() will catenate, compare and copy s2 and s1
|
|
in the same manner as their similarly named counter-
|
|
parts above, but involving at most n characters. For
|
|
_s_t_r_n_c_p_y(), the resulting string may not be null ter-
|
|
minated.
|
|
|
|
|
|
|
|
|
|
|
|
Page 160 HI-TECH C USER'S MANUAL
|
|
|
|
STRCHR, STRRCHR
|
|
SYNOPSIS
|
|
|
|
#include <string.h>
|
|
|
|
char * strchr(char * s, int c)
|
|
char * strrchr(char * s, int c)
|
|
|
|
|
|
DESCRIPTION
|
|
These functions locate an instance of the character c
|
|
in the string s. In the case of _s_t_r_c_h_r() a pointer will
|
|
be returned to the first instance of the character
|
|
found be searching from the beginning of the string,
|
|
while _s_t_r_r_c_h_r() searches backwards from the end of the
|
|
string. A null pointer is returned if the character
|
|
does not exist in the string.
|
|
|
|
SEE ALSO
|
|
|
|
|
|
|
|
|
|
|
|
|
|
SYSTEM
|
|
SYNOPSIS
|
|
|
|
#include <sys.h>
|
|
|
|
int system(char * s)
|
|
|
|
|
|
DESCRIPTION
|
|
When executed under MS-DOS _s_y_s_t_e_m() will pass the argu-
|
|
ment string to the command processor, located via the
|
|
environment string COMSPEC, for execution. The exit
|
|
status of the command processor will be returned from
|
|
the call to system(). For example, to set the baud
|
|
rate on the serial port on an MS-DOS machine:
|
|
|
|
system("MODE COM1:96,N,8,1,P");
|
|
|
|
This function will not work on CP/M-86 since it does
|
|
not have an invokable command interpreter. Under Con-
|
|
current CP/M the CLI system call is used.
|
|
|
|
SEE ALSO
|
|
|
|
spawnl, spawnv
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 161
|
|
|
|
TAN
|
|
SYNOPSIS
|
|
|
|
#include <math.h>
|
|
|
|
double tan(double f);
|
|
|
|
|
|
DESCRIPTION
|
|
This is the tangent function.
|
|
|
|
SEE ALSO
|
|
|
|
sin, cos, asin, acos, atan
|
|
|
|
|
|
|
|
|
|
|
|
TIME
|
|
SYNOPSIS
|
|
|
|
#include <time.h>
|
|
|
|
time_t time(time_t * t)
|
|
|
|
|
|
DESCRIPTION
|
|
This function returns the current time in seconds since
|
|
00:00:00 on Jan 1, 1970. If the argument t is non-
|
|
null, the same value is stored into the object pointed
|
|
to by t. The accuracy of this function is naturally
|
|
dependent on the operating system having the correct
|
|
time. This function does not work under CP/M-86 or CP/M
|
|
2.2 but does work under Concurrent-CP/M and CP/M+.
|
|
|
|
SEE ALSO
|
|
|
|
ctime, gmtime, localtime, asctime
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 162 HI-TECH C USER'S MANUAL
|
|
|
|
TOUPPER, TOLOWER, TOASCII
|
|
SYNOPSIS
|
|
|
|
#include <ctype.h>
|
|
char toupper(int c);
|
|
char tolower(int c);
|
|
char toascii(int c);
|
|
char c;
|
|
|
|
|
|
DESCRIPTION
|
|
_T_o_u_p_p_e_r() converts its lower case alphabetic argument
|
|
to upper case, _t_o_l_o_w_e_r() performs the reverse conver-
|
|
sion, and _t_o_a_s_c_i_i() returns a result that is guaranteed
|
|
in the range 0-0177. _T_o_u_p_p_e_r() and _t_o_l_o_w_e_r return their
|
|
arguments if it is not an alphabetic character.
|
|
|
|
SEE ALSO
|
|
|
|
islower, isupper, isascii et. al.
|
|
|
|
|
|
|
|
|
|
|
|
UNGETC
|
|
SYNOPSIS
|
|
|
|
#include <stdio.h>
|
|
|
|
int ungetc(int c, FILE * stream)
|
|
|
|
|
|
DESCRIPTION
|
|
_U_n_g_e_t_c() will attempt to push back the character c onto
|
|
the named stream, such that a subsequent _g_e_t_c() opera-
|
|
tion will return the character. At most one level of
|
|
pushback will be allowed, and if the stream is not buf-
|
|
fered, even this may not be possible. EOF is returned
|
|
if the _u_n_g_e_t_c() could not be performed.
|
|
|
|
SEE ALSO
|
|
|
|
getc
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 163
|
|
|
|
UNLINK
|
|
SYNOPSIS
|
|
|
|
int unlink(char * name)
|
|
|
|
|
|
DESCRIPTION
|
|
_U_n_l_i_n_k() will remove (delete) the named file, that is
|
|
erase the file from its directory. See _o_p_e_n() for a
|
|
description of the file name construction. Zero will
|
|
be returned if successful, -1 if the file did not exist
|
|
or it could not be removed.
|
|
|
|
SEE ALSO
|
|
|
|
open, close, rename, remove
|
|
|
|
|
|
|
|
|
|
|
|
VA_START, VA_ARG, VA_END
|
|
SYNOPSIS
|
|
|
|
#include <stdarg.h>
|
|
|
|
void va_start(va_list ap, _p_a_r_m_N);
|
|
_t_y_p_e va_arg(ap, _t_y_p_e);
|
|
void va_end(va_list ap);
|
|
|
|
|
|
DESCRIPTION
|
|
These macros are provided to give access in a portable
|
|
way to parameters to a function represented in a proto-
|
|
type by the ellipsis symbol (...), where type and
|
|
number of arguments supplied to the function are not
|
|
known at compile time. The rightmost parameter to the
|
|
function (shown as _p_a_r_m_N) plays an important role in
|
|
these macros, as it is the starting point for access to
|
|
further parameters. In a function taking variable
|
|
numbers of arguments, a variable of type va_list should
|
|
be declared, then the macro va_start invoked with that
|
|
variable and the name of _p_a_r_m_N. This will initialize
|
|
the variable to allow subsequent calls of the macro
|
|
va_arg to access successive parameters. Each call to
|
|
va_arg requires two arguments; the variable previously
|
|
defined and a type name which is the type that the next
|
|
parameter is expected to be. Note that any arguments
|
|
thus accessed will have been widened by the default
|
|
conventions to _i_n_t, _u_n_s_i_g_n_e_d _i_n_t or _d_o_u_b_l_e. For exam-
|
|
ple if a character argument has been passed, it should
|
|
be accessed by va_arg(ap, int) since the char will have
|
|
been widened to _i_n_t. An example is given below of a
|
|
function taking one integer parameter, followed by a
|
|
number of other parameters. In this example the func-
|
|
tion expects the subsequent parameters to be pointers
|
|
to char, but note that the compiler is not aware of
|
|
this, and it is the programmers responsibility to
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 164 HI-TECH C USER'S MANUAL
|
|
|
|
ensure that correct arguments are supplied.
|
|
|
|
#include <stdarg.h>
|
|
prf(int n, ...)
|
|
{
|
|
va_list ap;
|
|
|
|
va_start(ap, n);
|
|
while(n--)
|
|
puts(va_arg(ap, char *));
|
|
va_end(ap);
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
WRITE
|
|
SYNOPSIS
|
|
|
|
#include <unixio.h>
|
|
|
|
int write(int fd, void * buf, size_t cnt)
|
|
|
|
|
|
DESCRIPTION
|
|
_W_r_i_t_e() will write from the buffer at buf up to cnt
|
|
bytes to the file associated with the file descriptor
|
|
fd. The number of bytes actually written will be
|
|
returned. EOF or a value less than cnt will be returned
|
|
on error. In any case, any return value not equal to
|
|
cnt should be treated as an error (cf. _r_e_a_d() ).
|
|
|
|
SEE ALSO
|
|
|
|
open, close, read
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 165
|
|
|
|
INDEX
|
|
|
|
|
|
8086 70 CP/M 26,106,131,155
|
|
absolute value 116 CP/M-80 compiler 2
|
|
acos() 103 cputs() 107
|
|
address creat() 111
|
|
link 73 creating a library 76
|
|
load 73 CREF 83
|
|
ANSI Standard 13,17 cross compilers 3
|
|
array cross reference 36,83
|
|
dimension 16 ctime() 111
|
|
index 16 ctrl-Z 26,120
|
|
size 16 date and time 104
|
|
ASCII 26 debugging 10,105
|
|
asctime() 104 device name as file 23
|
|
asin() 103 device
|
|
assembler as file 141
|
|
in C programs 20 di() 113
|
|
assert() 105 directory 108,139
|
|
atan() 103 current 130
|
|
atan2() 103 disk changing on floppy disk
|
|
Atari ST 3 systems 3
|
|
atexit() 104 disk space 33
|
|
atof() 105 div() 112
|
|
atoi() 105 div_t 112
|
|
atol() 105 dup() 113
|
|
bdos() 106 editor 3,33
|
|
binary output file 8 ei() 113
|
|
bios() 106 entering long commands 7
|
|
braces Enumerated Types 16
|
|
omission of 16 environment 130
|
|
byte ordering 21 error message:
|
|
C command 3,7 Can't generate code 33
|
|
C reference books 2 Error closing file 33
|
|
calloc() 107 No room 33
|
|
carriage return 26,120 out of memory 33
|
|
ceil() 116 Undefined symbol 33
|
|
cgets() 107 Write error 33
|
|
change file attributes 108 error messages 23,33
|
|
character testing 134 format of 23
|
|
chdir() 108 LIBR 78
|
|
checksum 79,80 list of 23,85
|
|
chmod() 108 redirection of 23
|
|
class name 70 execl() 114
|
|
close() 109 executing a sub-program 156
|
|
clreof() 109 executing system commands
|
|
clrerr() 109 160
|
|
command line 7,12,77,160 execution profiling 10
|
|
Compatibility 25 execv() 114
|
|
compiler driver 3 exit() 114
|
|
Compiler Structure 5 exp() 115
|
|
console I/O 107,129,135 exponentional functions 115
|
|
control-C handling 155 Extern Declarations 30
|
|
converting ascii to binary fabs() 116
|
|
105 fclose() 116
|
|
cos() 110 feof() 117
|
|
cosh() 110 ferror() 117
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 166 HI-TECH C USER'S MANUAL
|
|
|
|
fflush() 117 getw() 132
|
|
fgetc() 118 global variables 30
|
|
fgets() 118 gmtime() 132
|
|
FILE 99 hex output file 8
|
|
file descriptor 27,111,119 I/O redirection 127
|
|
duplicating 113 I/O
|
|
FILE pointer 27 ASCII 26
|
|
file Binary 26
|
|
access time 158 standard 25,99
|
|
attributes 108,158 in-line assembler 20
|
|
closing a 109,116 Initialization Syntax 16
|
|
creating a 111 initializer 16
|
|
deleting a 148,163 inp() 133
|
|
flushing buffer to a 117 int86() 133
|
|
information about a 158 int86x() 133
|
|
modification time 158 intdos() 133
|
|
opening a 119,123,140 intdosx() 133
|
|
random access to a Intel hex format 79
|
|
125,137 interrupt 133
|
|
reading from a 122,147 interrupt handling 155
|
|
renaming a 149 interrupt vector
|
|
size 158 setting 154
|
|
type of a 135 isalnul() 134
|
|
writing to a 126,164 isalnum() 134
|
|
fileno() 119 isalpha() 134
|
|
floating point isascii() 134
|
|
library 27 isatty() 135
|
|
options required to use iscntrl() 134
|
|
4 isdigit() 134
|
|
floor() 116 isgraph() 134
|
|
fopen() 26,119 islower() 134
|
|
formatted input 124,150 ispunct() 134
|
|
formatted printing 121,142 isspace() 134
|
|
fprintf() 121 isupper() 134
|
|
fputc() 121 kbhit() 135
|
|
fputs() 122 Kernighan and Ritchie 2,16
|
|
fread() 122 large model 70,80
|
|
free() 123 ldexp() 124
|
|
freopen() 123 ldiv() 112
|
|
frexp() 124 LIBR 75
|
|
fscanf() 124 librarian 75
|
|
fseek() 125 libraries 7
|
|
ftell() 126 library manager 75
|
|
function parameter 163 library ordering 77
|
|
function library
|
|
declaration 17 creating 76
|
|
large 33 floating point 33
|
|
parameters 17 ordering 33
|
|
prototype 17,163 line number symbols 10
|
|
fwrite() 126 linker 69
|
|
getc() 128 LINT 16
|
|
getch() 129 localtime 132
|
|
getchar() 25,129 log() 115
|
|
getche() 129 log10() 115
|
|
getcwd() 130 logarithmic functions 115
|
|
getenv() 130 long 30
|
|
gets() 131 longjmp() 136
|
|
getuid() 131 lseek() 137
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 167
|
|
|
|
Machine Dependencies 21 pack pragma 20
|
|
macros parameter
|
|
predefined 21 type 17
|
|
malloc() 137 perror() 141
|
|
Member Names 13,29 portable code 21
|
|
memcmp() 138 pow() 115
|
|
memcpy() 138 pragma 20,21
|
|
memory allocation printf 33
|
|
107,148,150 printf() 142
|
|
releasing 123 program execution 156
|
|
memory model 31 psect
|
|
memory requirements 2 linking 69
|
|
memset() 138 local 70
|
|
mkdir() 139 putc() 144
|
|
Motorola hex format 80 putch() 129
|
|
MS-DOS 108,133,139,155 putchar() 144
|
|
msdos() 139 puts() 145
|
|
msdoscx() 139 putw() 145
|
|
multiple definitions 30 qsort() 146
|
|
newline 26 rand() 147
|
|
Newton's approximation 157 random numbers 147,158
|
|
non-local goto 136,152 read() 147
|
|
objtohex 72,79 realloc() 148
|
|
open() 140 relocation 69
|
|
Operating Details 7 remove() 148
|
|
options 7 rename() 149
|
|
-1 10 return 26,120
|
|
-11 11 rewind() 149
|
|
-2 11 rmdir() 139
|
|
-6301 11 S format hex 80
|
|
-A 8 sbrk() 150
|
|
-B 9 scanf 33
|
|
-C 7 scanf() 150
|
|
-CPM 7 segment registers 152
|
|
-CR 7 segread() 152
|
|
-D 8 self relocation 72
|
|
-E 10 setbuf() 153
|
|
-F 8 setjmp() 152
|
|
-G 10 setuid() 153
|
|
-H 10 setvbuf() 153
|
|
-I 8 set_vector() 154
|
|
-LF 4,27,33 shift
|
|
-M 8 signed 14
|
|
-O 8 unsigned 14
|
|
-Ooutfile 8 short 21,30
|
|
-P 10 signal() 155
|
|
-R 8 sin() 155
|
|
-S 7 sinh() 110
|
|
-U 8 size of data types 21
|
|
-V 3,8 sorting 146
|
|
-W 10 source file naming 3
|
|
-X 8 source level debugging 10
|
|
-Z 10 spawnl() 156
|
|
linker 71 spawnv() 156
|
|
outp() 133 spawnve() 156
|
|
pack 21 Specific Features 13
|
|
sprintf() 156
|
|
sqrt() 157
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 168 HI-TECH C USER'S MANUAL
|
|
|
|
square root function 157 Unsigned Types 14
|
|
srand() 158 user ID 131,153
|
|
sscanf() 157 V3.09 2
|
|
Standard Libraries 25 va_arg 18,163
|
|
Standard Library Functions va_end 163
|
|
99 va_start 163
|
|
stat() 158 void 18
|
|
stdarg.h 18,163 Pointer to 18
|
|
STDIO 25,27,99 warning level 10
|
|
storage allocator 18 warning messages
|
|
strcat() 159 suppressing 10
|
|
strchr() 160 wild card expansion 127
|
|
strcmp() 159 Wordstar 33
|
|
strcpy() 159 write() 164
|
|
stream 27,99 Z180 MMU 68
|
|
string manipulation 159 Bank Base Register 68
|
|
strlen() 159 BBR 68
|
|
strncat() 159 CBAR 68
|
|
strncmp() 159 CBR 68
|
|
strncpy() 159 Common Base Register 68
|
|
strrchr() 160 Common/Bank Area Regis-
|
|
Structure Operations 15 ter 68
|
|
structure packing 20 Z180 Registers 68
|
|
structures ASCI 68
|
|
as function argument 15 Bank Base Register 68
|
|
assignment 15 BBR 68
|
|
functions returning 15 BCR0H 68
|
|
Stylistic Considerations 29 BCR0L 68
|
|
symbol file 10,80 BCR1H 68
|
|
symbols BCR1L 68
|
|
cross reference 83 CBAR 68
|
|
global 70,76 CBR 68
|
|
System Requirements 2 CNTLA0 68
|
|
system() 160 CNTLA1 68
|
|
tan() 161 CNTLB0 68
|
|
tanh() 110 CNTLB1 68
|
|
temporary files 4 CNTR 68
|
|
text editor 3 Common Base Register 68
|
|
time and date 104 Common/Bank Area Regis-
|
|
time() 161 ter 68
|
|
toascii() 162 CSI/0 68
|
|
tolower() 162 DAR0B 68
|
|
toupper() 162 DAR0H 68
|
|
trigonometric functions DAR0L 68
|
|
103,110 DCNTL 68
|
|
hyperbolic 110 DMA 68
|
|
Type Checking 13 DMA Byte Count 68
|
|
type qualifiers 19 DMA Desitination Address
|
|
typecast 13 68
|
|
typecasting 18 DMA Mode Register 68
|
|
ungetc() 162 DMA Source Address 68
|
|
ungetch() 129 DMA Status Register 68
|
|
Unix DMODE 68
|
|
C compiler 16 DSTAT 68
|
|
V7 25 FRC 68
|
|
unlink() 163 Free Running Counter 68
|
|
unsigned 23 IAR1H 68
|
|
unsigned char 21 IAR1L 68
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HI-TECH C USER'S MANUAL Page 169
|
|
|
|
ICR 68 INC 55
|
|
IL 68 IND 55
|
|
Interrupt Vector Regis- INDR 56
|
|
ter 68 INI 56
|
|
ITC 68 INIR 56
|
|
MAR1B 68 JP 56
|
|
MAR1H 68 JR 56
|
|
MAR1L 68 LD 56,57,58,59
|
|
MMU 68 LDD 59
|
|
OMCR 68 LDDR 59
|
|
RCR 68 LDI 59
|
|
Refresh Control Register LDIR 59
|
|
68 MLT 59
|
|
RLDR0H 68 NEG 59
|
|
RLDR0L 68 NOP 59
|
|
RLDR1H 68 OR 59,60
|
|
RLDR1L 68 OTDM 61
|
|
SAR0B 68 OTDMR 60
|
|
SAR0H 68 OTDR 60
|
|
SAR0L 68 OTIM 61
|
|
STAT0 68 OTIMR 60
|
|
STAT1 68 OTIR 60
|
|
TCR 68 OUT 60
|
|
TDR0 68 OUT0 60
|
|
TDR1 68 OUTD 60
|
|
TIMER 0 68 OUTI 61
|
|
TIMER 1 68 POP 61
|
|
TMDR0H 68 PUSH 61
|
|
TMDR0L 68 RES 61,62,63
|
|
TMDR1H 68 RET 63
|
|
TMDR1L 68 RETI 63
|
|
TRDR 68 RETN 63
|
|
TSR0 68 RL 63
|
|
TSR1 68 RLA 63
|
|
Z80 Instructions 50 RLC 63
|
|
ADC 51 RLCA 63
|
|
ADD 51 RLD 63
|
|
AND 51 RR 63,64
|
|
BIT 52,53 RRA 64
|
|
CALL 53 RRC 64
|
|
CCF 53 RRCA 64
|
|
CP 53,54 RRD 64
|
|
CPD 54 RST 64
|
|
CPDR 54 SBC 64
|
|
CPI 54 SCF 64
|
|
CPIR 54 SET 64,65,66
|
|
CPL 54 SLA 66
|
|
DAA 54 SLP 66
|
|
DEC 54 SRA 66
|
|
DI 54 SRL 67
|
|
DJNZ 54 SUB 67
|
|
EI 54 TST 67
|
|
EX 55 TSTIO 67
|
|
EXX 55 XOR 67
|
|
HALT 55 Z80 pseudo ops
|
|
IM 55 IRP 47
|
|
IN 55 IRPC 47
|
|
IN0 55 ZAS directives 48
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Page 170 HI-TECH C USER'S MANUAL
|
|
|
|
title 48 operators 38
|
|
ZAS options program sections 39
|
|
-J 35 PSECT 43
|
|
-L 36 psects 39,43
|
|
-N 35 pseudo ops 40
|
|
-O 36 relocatable object code
|
|
-U 35 39
|
|
-W 36 temporary labels 37
|
|
ZAS psect flags Z180 35
|
|
ABS 43 Zilog 35
|
|
GLOBAL 43 _exit() 115
|
|
LOCAL 43 _getargs() 127
|
|
OVRLD 43
|
|
PURE 43
|
|
ZAS pseudo ops 40
|
|
COND 42
|
|
DB 40
|
|
DEFB 40
|
|
DEFF 41
|
|
DEFL 41
|
|
DEFM 42
|
|
DEFS 41
|
|
DEFW 41
|
|
ELSE 42
|
|
END 42
|
|
ENDC 42
|
|
ENDM 44
|
|
EQU 41
|
|
GLOBAL 43
|
|
IF 42
|
|
LOCAL 45
|
|
MACRO 44
|
|
ORG 44
|
|
PSECT 43
|
|
REPT 46
|
|
ZAS
|
|
64180 35
|
|
arithmetic overflow 35
|
|
binary constants 37
|
|
character constants 38
|
|
condition codes 48
|
|
conditional assembly 42
|
|
constants 37
|
|
directives 48
|
|
extended condition codes
|
|
48
|
|
external symbols 35
|
|
floating point constants
|
|
38
|
|
hexadecimal constants 37
|
|
jump optimization 35
|
|
jumps 35
|
|
labels 36
|
|
listing 36
|
|
macros 44
|
|
mnemonics 35
|
|
octal constants 37
|
|
opcode constants 38
|
|
|
|
|
|
|
|
|
|
|