CP/M

home *** CD-ROM | disk | FTP | other *** search

/ CP/M / CPM_CDROM.iso / simtel / hitech-c / z80doc.exe / lha / z80doc.txt

Wrap

Text File | 1993-06-08 | 284.7 KB | 11,353 lines

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