MSX C manual

Preface
Better C than never.
Freddy Vulto

Introduction

MSX-C offers a complete package to let you develop C programs using MSX-DOS. Unlike Small C, Hisoft C or BDS C, MSX-C comes with pre-made MSX libraries. Using MSX-C, you’re able to fully combine machine code speed with the ease of a high level programming language on a MSX. Please take my advice: “Get yourself some trunks and jump into C!”
Thanks to standardisation and the excellent work of the ASCII Corporation it is possible to learn C with almost any C manual. For a full survey however, I would recommend “The C programming language” of Brian W. Kernighan and Dennis M.Ritchie. These two are the founders of C, so – believe me – they know what they’re talking about.
Books offering “C++” on the other hand, you’d better not buy, cause this extension of C hasn’t been implemented on the MSX.
The MSX-C package consists of 2 parts:

1. MSX-C Compiler Disk
2. MSX-C Library System Disk

The Compiler Disk contains the necessary programs to compile a standard C program. The Library System Disk contains functions which make use of specific MSX functionality.
Before you can use MSX-C, you have to make a so called MSX-C Library System Disk. This disk will contain all files you need to compile a C program. You can either create the MSX-C Library System Disk yourself by COPY ing, or you can use the batch file MKSYS.BAT . Copy MKSYS to the destination disk, change to this disk and command:

MKSYS <drive>

The batch file now will take care of copying files from ‘drive’ to the destination disk, asking you questions on the fly.
A C source file can be written using an arbitrary text editor (for example TED), as long as you give the file a ‘.C’ extension. Next, the source file can be turned into a fully executable machine code program, using a number of compilation steps. These steps are the heart of MSX-C as shown in the underneath figure:
Table 1: MSX-C Compile Steps

                        |.C ......C source file
                        |
                  Parser (CF.COM)
                        |
                        |.TCO ....T-code file
                        |
(Function Parameter Checker (FPC.COM))
                        |
         Code Generator (CG.COM)
                        |
                        |.MAC ....Assembler file
                        |
          Macro Assembler (M80.COM)
                        |
                        |.REL ....Relocatable machinecode file
                        |
                Linker (L80.COM)
                        |
                        |.COM ....Command file

The commands to execute these subsequent steps are coded in a batch file C.BAT , so compiling a C source file – e.g. TEST.C – can be as easy as typing:

C TEST

If one wants to use specific MSX functions besides standard C functions, TEST.C must be compiled using the batch file MSXC.BAT:

MSXC TEST [CF options] [CG options]

As the fairly huge compilation process uses quite some time, it is best to use a 7 MHz MSX with considerable memory (512K), so the whole process can run on a RAMdisk. Only if you’re going to use MSX-C v1.20, you’ll need MSX-DOS 2.20.
The MSX-C Compiler Disk contains the ASCII MSX-C Compiler. The compiler is made out of CF.COM , CG.COM , FPC.COM and MX.COM (for descriptions, see below). Furthermore, there is a standard library, fully equiped with source and batchfiles to let you modify this library. M80.COM , L80.COM and LIB80.COM are not on the disk and will have to be taken from a MSX-DOS(2) Tools Disk.
MSX-C uses the next ‘library’ files:

  • CK.REL: Standard ‘ultra main’ program
  • CLIB.REL: MSX-C library
  • CRUN.REL: MSX-C library
  • CEND.REL: Standard ‘end’ program

The files CK.REL and CEND.REL will always be included in the resulting executable, CK.REL at the head and CEND.REL at the tail, so they’re not really library files. The source of both these relocatables can be found in CK.MAC and CEND.MAC respectively
CLIB.REL and CRUN.REL on the other hand, are made out of functions which are included in the resulting executable only if these functions are actually called in your program.
CLIB.REL is the actual library. All the functions defined within this relocatable file, can be found also within the available library source files. MSX-C version 1.10 however, makes use of other source files than MSX-C version 1.20.
CRUN.REL contains routines to load and save ‘automatic’ variables. Also there are a number of 8 and 16 bits arithmetic functions, such as multiply, divide, shift and compare. These functions are supposed to be used internal only. Sources of these functions can be found in CRUN.MAC .
As compilation involves many steps, you’re better off using the supplied batch files:

  • C.BAT : To compile a standaad C program
  • GENLIB.BAT : Generate a library

With help of C.BAT the C source file can be compiled to .COM file. The C function calls can be checked using FPC.COM , which uses LIB.TCO . GENLIB.BAT will trigger a complete batch-cyclus, recompiling the entire standard library.
The remaining files on the MSX-C Compiler Disk are useful examples of what you’re able to do with the C programming language. The program Q.COM can be generated using MKQ.BAT . This file is made out of Q.C , RND.MAC , LINE.MAC , COLOR.MAC and CALBIO.MAC .
There are different versions of the MSX-C compiler. The list below shows these versions, along with their main characteristics:

  • version 1.00, Oct-83: CP/M, usage of 8088 (the predecessor of the Z80) op-code.
  • version 1.10, Jun-87: MSX, usage of Z80 op-code.
  • version 1.20, Aug-88: Suites MSX-DOS 2.20. Compared to v1.10 the library- and headerfunctions has been rearranged.

Version 1.20 is totally based upon MSX-DOS 2.20. A program which is compiled using MSX-C v1.20 will automatically generate an error message if MSX-DOS 2.20 isn’t available. So if you want to write a program which only needs MSX-DOS 1, you’ll have to use MSX-C v1.10.
Compiler Disk v1.10
Table 2: Contents Compiler Disk v1.10

-------------------------------------------------------------------
                 PRIMARY FILES      SUPPORT FILES      SOURCE FILES
-------------------------------------------------------------------
SYSTEM:          cf.com
                 cg.com
                 fpc.com. . . . . . lib.tco
                 mx.com . . . . . . arel.bat
                                    crel.bat
LIBRARY FILES:   ck.rel . . . . . . . . . . . . . . . .ck.mac
                 clib.rel . . . . . . . . . . . . . . .lib0.mac
                                                       lib1.c
                                                       lib2.c
                                                       lib3.c
                                                       libk.c
                 crun.rel . . . . . . . . . . . . . . .crun.mac
                 cend.rel . . . . . . . . . . . . . . .cend.mac
HEADER FILES:    stdio.h
                 bdosfunc.h
BATCH FILES:     c.bat
                 mksys.bat
                 forremk.bat
                 genlib.bat . . . . genlib01.bat
                 genlib02.bat
                 genlib03.bat
                 genlib04.bat
                 genlib05.bat
                 genlib06.bat
SAMPLE FILES:    q.c. . . . . . . . mkq.bat . . . . . .rnd.mac
                                                       line.mac
                                                       color.mac
                                                       calbio.mac
-------------------------------------------------------------------

System
The MSX-C Compiler Disk v1.10 contains almost the same files as the MSX-C Compiler Disk v1.20. See the next chapter: Compiler Disk v1.20 for a full description of the system files and the functions.

Standard Library

The table below gives an overview of all the functions which are available through the standard library of MSX-C v1.10. At the end of every function you can see in which sourcefile and which header file the function definition can be found.

Table 3: Functions in Standard Library v1.10

Name Declaration SourceFile HeaderFile
abs int abs(n) lib1.c stdio.h
alloc char *alloc(nbytes) lib1.c stdio.h
atoi int atoi(s) lib1.c stdio.h
bios char bios(bios_code, c) lib0.mac bdosfunc.h
bdos char bdos(c, de, hl) lib0.mac bdosfunc.h
bdosh int bdosh(c, de, hl) lib0.mac bdosfunc.h
call int call(addr, a, hl, bc, de) lib0.mac stdio.h
calla char calla(addr, a, hl, bc, de) lib0.mac stdio.h
close STATUS close(fd) lib2.c stdio.h
creat FD creat(filename) lib2.c stdio.h
execl VOID execl(nargs, progname, args) libk.c stdio.h
execv VOID execv(progname, argv) libk.c stdio.h
exit VOID exit(code) libk.c stdio.h
expargs int expargs(argc, argv, maxargc, xargv) lib2.c stdio.h
fclose STATUS fclose(fp) lib2.c stdio.h
fgets char *fgets(s, n, fp) lib2.c stdio.h
fopen FILE *fopen(nargs, xfn, xmode, xbsiz) lib2.c stdio.h
fprintf STATUS fprintf(nargs, iobuf, format) lib3.c stdio.h
fputs STATUS fputs(s, fp) lib2.c stdio.h
free void free(ap) lib1.c stdio.h
fscanf int fscanf(nargs, iobuf, format) lib3.c stdio.h
fsettext STATUS fsettext(fp) lib2.c stdio.h
fsetbin STATUS fsetbin(fp) lib2.c stdio.h
getc int getc(fp) lib2.c stdio.h
getch char getch() lib2.c stdio.h
getchar int getchar() lib2.c stdio.h
getche char getche() lib2.c stdio.h
gets char *gets(s, n) lib2.c stdio.h
inp char inp(port) lib0.mac stdio.h
isalpha int isalpha(c) stdio.h stdio.h
iscntrl int iscntrl(c) stdio.h stdio.h
isdigit int isdigit(c) stdio.h stdio.h
islower int islower(c) stdio.h stdio.h
isspace int isspace(c) stdio.h stdio.h
isupper int isupper(c) stdio.h stdio.h
kbhit BOOL kbhit() lib2.c stdio.h
longjmp void longjmp(env, val) lib0.mac stdio.h
max int max(x, y) lib1.c stdio.h
memcpy void memcpy(dest, source, count) lib0.mac stdio.h
memset void memset(dest, byte, count) lib0.mac stdio.h
min int min(x, y) lib1.c stdio.h
movmem void movmem(source, dest, count) lib0.mac stdio.h
open STATUS open(filename, mode) lib2.c stdio.h
outp void outp(port, val) lib0.mac stdio.h
printf STATUS printf(nargs, format) lib3.c stdio.h
putc STATUS putc(c, fp) lib2.c stdio.h
putchar STATUS putchar(c) lib2.c stdio.h
puts STATUS puts(s) lib2.c stdio.h
qsort void qsort(base, n, width, compar) lib1.c stdio.h
read int read(fd, buf, n) lib2.c stdio.h
rename STATUS rename(oldname, newname) lib2.c stdio.h
rsvstk void rsvstk(n) lib1.c stdio.h
sbrk char *sbrk(n) lib1.c stdio.h
scanf int scanf(nargs, format) lib3.c stdio.h
sensebrk VOID sensebrk() lib2.c stdio.h
setjmp VOID setjmp(env) lib0.mac stdio.h
setmem VOID setmem(dest, byte, count) lib0.mac stdio.h
sprintf VOID sprintf(nargs, buffer, format) lib3.c stdio.h
sscanf int sscanf(nargs, line, format) lib3.c stdio.h
strcat char *strcat(d, s) lib1.c stdio.h
strcmp int strcmp(s, t) lib1.c stdio.h
strcpy char *strcpy(d, s) lib1.c stdio.h
strlen size_t strlen(s) lib1.c stdio.h
tolower char tolower(c) lib1.c stdio.h
toupper char toupper(c) lib1.c stdio.h
ungetc STATUS ungetc(c, fp) lib2.c stdio.h
ungetch VOID ungetch(c) lib2.c stdio.h
unlink STATUS unlink(filename) lib2.c stdio.h
write int write(fd, buf, n) lib2.c stdio.h

Compiler Disk v1.20
Table 4: Contents Compiler Disk v1.20

-------------------------------------------------------------------
                 PRIMARY FILES      SUPPORT FILES      SOURCE FILES
                 --------------------------------------------------
SYSTEM:          cf.com
                 cg.com
                 fpc.com. . . . . . lib.tco
                 mx.com . . . . . . arel.bat
                                    crel.bat

LIBRARY FILES: ck.rel . . . . . . . . . . . . . . . .ck.mac
clib.rel . . . . . . . . . . . . . . .clibc.c
clibmac.mac
direct.c
io.c
malloc.c
process.c
stdio.c
stdlib.c
string.c
crun.rel . . . . . . . . . . . . . . .crun.mac
cend.rel . . . . . . . . . . . . . . .cend.mac

HEADER FILES: stdio.h
bdosfunc.h
conio.h
ctype.h
direct.h
io.h
malloc.h
memory.h
process.h
setjmp.h
stdlib.h
string.h
type.h

BATCH FILES: c.bat
mksys.bat
forremk.bat
genlib.bat . . . . genliba.bat
genlibc.bat
genrel.bat
gentco.bat

SAMPLE FILES: q.c. . . . . . . . mkq.bat . . . . . .rnd.mac
line.mac
color.mac
calbio.mac
search.c . . . . . search.bat. . . . .bk.mac
wc.c
head.c
rom1.c . . . . . . . . . . . . . . . .rom0.mac
——————————————————————-

System
CF.COM
CF is the parser. CF will convert a C file to a so-called T-code (temporary code) file with extension ‘.TCO’. This TCO file contains the C file code, encoded in ASCII tokens. Comments are removed. The T-code file serves as input for the next compilation step using ‘CG.COM’. Also, the T-code file is used by FPC to check if function calls are valid. Giving the ‘CF’ command from the DOS-prompt gives:

    MSX-C ver 1.20p   (parser)
    Copyright (C) 1989 by ASCII Corporation
    Usage: cf [options] filename
    options available:
            -c             disables comment nesting
            -e[filename]   makes diagnostic file
            -f             enables implicit function and parameter declaration
            -t             enables implicit pointer convertion
            -j             enables kanji code literal
            -m             displays memory usage statistics
            -o[filename]   makes T-code file
            -rP:S:H        allocate tables in ratio P:S:H (Pool:Symbol table:Hash)
            -s             continues submit even if errors are detected

CF supposes the ‘filename’ to have the ‘.C’ extension, so this extension shouldn’t be given by the user. For example to let CF handle the file FRED.C:

CF FRED

The inner workings of CF can be affected by the following switches:
-c : ‘disable comment nesting’
Using this switch, it isn’t allowed to nest comments. For example the next comment won’t be allowed:

/* /* Commentaar…commentaar…
…commentaar */ */

The original definition of C doesn’t allow comment nesting. Still, this nesting can come in handy if you temporarily want to disable large portions of code by putting a ‘/*’ at the begin and a ‘*/’ at the end of code.
-e[X] : ‘makes diagnostic file on drive X’
Allows the user to create a diagnostic file with extension ‘.DIA’ on drive ‘X’. This causes the output of CG to be directed to the DIA file instead of the screen. This option may be useful to collect error messages.
-f : ‘enables implicit function and parameter declaration’
This switch allows for functions which do not have to be declared explicit. Common practice however, is to declare functions explicit always. So it would be better if you do not use this switch.
-t : ‘enables implicit pointer conversion’
This switch allows for pointer conversions to take place automatically contrary to ‘type casting’. Again, common practice is to use explicit conversion.
-j : ‘enables kanji code literal’
Something with kanji (?). This option isn’t available at MSX-C v1.10.
-m : ‘displays memory usage statistics’
Displays information about the memory usage of the 3 internal tables of CF. The size of each table can be influenced using the ‘-r’ switch.
-o[filename] : ‘makes T-code file’
Creates a specific T-code file. At MSX-C v1.10 it is only possible to define another drive.
-rP:S:H : ‘allocates tables in ratio Pool/Symbol_table/Hash’
Allows the user to change the ratio of the 3 internal tables of CF. For example: ‘-r3:1:2’. See also ‘-m’.
-s : ‘continues submit even if errors are detected’
Allows CF to continue even though there have been detected errors.
Most of the switches are allowed to concatenate to one string, preceded by a single ‘-‘. This doesn’t work for all switches however: you’ll have to try for yourself.
E.g.: Treat the file FRED.C by CF, creating the files FRED.TCO and FRED.DIA on drive B:, do not enable nested comments and display memory statistics:

CF -coBm -eB FRED

CG.COM
CG is the Code Generator. CG converts the T-code file to a file with extension ‘.MAC’. This MAC file contains the compiled C code as plain readable ASCII mnemonics! Via the Macro Assembler M80 this file can be compiled. Typing ‘CG’ from the DOS-prompt gives:

MSX-C ver 1.20p (code generator)
Copyright (C) 1989 by ASCII Corporation
Usage: cg [-rNkulo<filename>] filename

CF assumes the ‘filename’ to have the ‘.TCO’ extension, so this extension shouldn’t be given by the user. During compilation, CG will prompt each function being compiled. The progress of the compilation is being indicated after the function name by successively a dot for each compiled jump or loop, a colon for each declared variable and a semicolon at the end. The following switches can be used:
-rN:
Changes the default size of the symbol table by specifying a number N. If CG ends preliminary because of the symbol table being too small, CG will advice the new size for the symbol table.
-k:
Kills the TCO files which served as input, after the compilation process has completed.
-u:
Doesn’t show the progress indicators (…::;).
-l:
(??) The only difference I’ve seen using this switch, is the placement of a ‘@’ after the ‘printf’ label in the MAC file.
-o<filename>:
Sends the output (MAC) file to the specified file.
Example: Process the file FRED.TCO by CG, putting FRED.MAC on drive B, changing the size of the symbol table to 2000 and delete the file FRED.TCO afterwards:

CG -oBr2000k FRED

FPC.COM
FPC is short for Function Parameter Checker. FPC checks the validity of the function calls of your C program; it checks whether the parameters of your function call are of the right type (int, char) and if the number of parameters equals the function definition. This check may save you a lot of time.
To do all this, FPC uses a special form of the T-code file in which only the function headers are incorporated; I name them ‘header T-code files’. These files can be created by FPC itself. MSX-C delivers two of these files ‘of the shelve’:

LIB.TCO : LIB0, LIB1, LIB2, LIB3, LIBK
MLIB.TCO : CURSES, GLIB, MSXBIOS, MATH

Typing ‘FPC’ from the DOS-prompt gives:

MSX-C function parameter checker ver 1.20p
Usage: fpc [-istu] [-c outputfile] [-d func[,func…]] inputfile(s)

With switch ‘ -c outputfile ‘ it is possible to generate a ‘header T-code file’. The use of the other switches aren’t clear to me. Some examples:

FPC fred mlib lib

This command will check all function calls which are made in FRED.C. To perform this check, we tell FPC to make use of MLIB.TCO and LIB.TCO.

FPC -c lib lib0 lib1 lib2 lib3 libk

This command will create a ‘header T-code file’ named LIB.TCO. This file will contain header information of all functions of the LIB0, LIB1, LIB2, LIB3 and LIBK libraries. FPC will use the T-code files of these libraries.
MX.COM
MX is short for the Module Extracting Utility. With use of MX it is possible to generate a library which consists of relocatable modules. MX splits the argument file into separate modules. These modules have to be compiled to separate REL-files (using M80.COM), whereafter LIB80.COM has to link the REL-files to the eventual library. To simplify this process, MX offers the ability to generate batch file commands in which the compile and link commands are incorporated. Typing ‘MX’ after the DOS-prompt shows:

   MSX-C module extracting utility ver 1.20p
   Usage: mx [options] filename [module list]
       options:
          -l          generates batch to make library file
          -o[path\]   makes output files on directory
          -uX         replaces every underscore(_) character to X

The argument ‘filename’ may have either the .MAC or .TCO extension. MX will check for both extensions and attach the appropriate extension to the filename. If both <filename.MAC> and <filename.TCO> are present, the .MAC file will take precedence. The extracted modules will be placed on disk with their modulename as filename and the same extension as the source file (TCO or MAC). Existing files will be overwritten, so take care! It is also possible to define a ‘module list’ which consists of modulenames separated by spaces. If specified, only these modules will be extracted. If not specified, all modules will be extracted.
-l : ‘generates batch to make library file’
Generates output with batch commands in order to compile and link all extracted modules. To use this output, it has to be redirected using the ‘>’ command to redirect the output to a batch file. MX uses two batchfiles to generate the batch commands: AREL.BAT for MAC files and CREL.BAT for T-code files. Sloppy however are the first and last line of the batch file which are not understood by DOS thus generating two error messages.
-o[path\] : ‘makes output files on directory’
Sends the output files to the specified directory. At MSX-C v1.10 only the drive can be specified.
-uX : ‘replaces every underscore(_) character to X’
Replaces every occurrence of the underscore character ‘_’ in a modulename with the specified character ‘X’. For example:

MX -loB crun > temp.bat

This command will extract all modules from the file CRUN.MAC and save each modulename as modulename.MAC on drive B:. The output of MX will be redirected to the file TEMP.BAT, so if you would command:

TEMP

all the extracted modules would be compiled and linked to the library CRUN.LIB. If you finally would like to use library with L80, the library should be renamed manually to CRUN.REL. Another example:

MX -loB crun lauhl laut1 > temp.bat

This command will extract only modules ‘lauhl’ and ‘laut1’ as compared to all modules in the previous example.
Also a warning: take care your source-file does not contain a module with the same name as your source-file, otherwise the extracted module will overwrite you source-file!
M80.COM
The macro-assembler M80 which comes with MSX-C v1.20 has been modified to be able to deal with subdirectories. This version of M80 is known as:

MSX.M-80 2.00

This version of M80 will also put todays date in the header of each page, whereas M80 v1.00 would put its release-date (01-Apr-85) at the top. Fortunately, M80 has some very descent documentation of its own 🙂
L80.COM
The linker L80 which comes with MSX-C v1.20 also has been modified to be able to deal with subdirectories. This version is knows as:

MSX.L-80 2.00 03-Apr-89 Copyright (c) 1989 Microsoft

This linker also has its own documentation, so I will pass here.
Standard Library
Version 1.20 of the standard library makes full use of MSX-DOS 2. A program created using the Standard Library v1.20, will not execute with MSX-DOS 1; the MSX-C program will automatically check the MSX-DOS version number and generate an error message if the version number is below 2.xx.
The Standard Library consists of the following parts:

   CK.MAC        MSX-C Ultra Main Program (Ver 1.2)
   CLIBMAC.MAC   MSX-C Standard Library Assembler Part (Ver 1.2)
   CRUN.MAC      MSX-C Run Time Library (Ver 1.2)
   CEND.MAC      MSX-C Standard Trailer File (Ver 1.2)
   DIRECT.C      Directory Manipulate Functions
   IO.C          Low Level Input/Ouput Functions
   MALLOC.C      Storage Management Functions
   PROCESS.C     Process Control Functions
   STDIO.C       Buffered Input/Output Functions
   STDLIB.C      Standard Library
   STRING.C      String Manipulate Functions

All source files (except CK.MAC, CRUN.MAC and CEND.MAC) are compiled and linked into the relocatable library file CLIB.REL. The following header files are present:

   BDOSFUNC.H   MSX-DOS Function Call Support
   CONIO.H      Console and I/O Port Functions
   CTYPE.H      Character Type Header
   DIRECT.H     Directory Manipulation Functions
   IO.H         Low Level File Input/Output Functions
   MALLOC.H     Storage Management Functions
   MEMORY.H     Memory Manipulate Functions
   PROCESS.H    Process Control Functions
   SETJMP.H     Longjmp Support
   STDIO.H      Buffered Input/Output Functions
   STDLIB.H     Standard Library
   STRING.H     String Manipulate Functions
   TYPE.H       Common Types and Constants

The header file STDIO.H will be included automatically to these header files.
The table below gives an overview of all the functions which are available in the Standard Library of MSX-C v1.20. At the end of every function you can see the original declaration, in which sourcefile and which header file the function definition can be found, and a short description. Functies which start with an underscore ‘_’ are supposed to be used only internally by MSX-C. On debugging the library, however, the descriptions may come in handy.
Table 5: Functions in Standard Library v1.20

Name Declaration SourceFile Description
_attr TINY _attr(path)
char *path;		 direct.c Get attribute of directory entry.
_bc TINY _bc(c, b)
char c;
TINY b;		 stdio.c
_chai VOID _chai(limit, fd)
char *limit;
FD fd;		 clibmac.mac
_chkversion VOID _chkversion() clibmac.mac
_cmp int _cmp(p, q)
char **p, **q;		 direct.c
_cutpath char *_cutpath(mode, p)
TINY mode;
char *p;		 stdlib.c Cut out path.
_deffcb char *_deffcb(fn, fcb)
char *fn;
char *fcb;		 process.c Set up default FCB area for the program to be exec’ed.
_exec VOID _exec(progname, nargs, param, checkp)
int nargs;
char *progname, **param;
BOOL checkp; /* look at PATH */		 Prepare to call _execgo.
_execgo char _execgo(progname, lflag)
char *progname;
char lflag;		 process.c Execute!
_exit VOID _exit(code)
int code;		 clibmac.mac Jumps to the “Terminate with error code (62h)” BDOS-routine.
_ffirst STATUS _ffirst(fn, fib, flag)
char *fn;
FIB *fib;
TINY flag;		 clibmac.mac
_fillbuf STATUS _fillbuf(fp)
FILE *fp;		 stdio.c
_flshserial VOID _flshserial() stdio.c
_fnext STATUS _fnext(fib)
FIB *fib;		 clibmac.mac
_getc int _getc(fp)
FILE *fp;		 stdio.c
_gv2 unsigned _gv2(p)
char **p;		 stdio.c
_igs int _igs(func, ___)
int (*func)();
char *___; /* pointer to FILE or (char *) */		 stdio.c Allows various aspects of file handles to be examined and altered. In particular it can be used to determine whether a file handle refers to a disk file or a device. _ioctl uses the “I/O Control for devices (4Bh)” BDOS-routine. Consult your DOS Reference Manual for more details.
_ioctl unsigned _ioctl(fd, subfunc, stat)
FD fd;
TINY subfunc;
unsigned stat;		 io.c
_main VOID _main() process.c Called by xmain in ck.rel.
_noraw TINY _noraw(fd)
FD fd;		 io.c
_p_path char *_p_path(fn, last_item, flag)
char *fn;
char **last_item;
TINY *flag;		 clibmac.mac
_parsefn char *_parsefn(fn, fcb, flag)
char *fn;
char *fcb;
TINY *flag;		 clibmac.mac
_putc STATUS _putc(c, fp)
char c;
FILE *fp;		 stdio.c
_raw TINY _raw(fd)
FD fd;		 io.c
_rawmode TINY _rawmod(fd, mode)
FD fd;
TINY mode; /* 0: cooked mode, 1: raw mode */		 io.c
_scn int _scn(param, infunc, ___, ugfunc)
int **param;
int (*infunc)();
char *___; /* to FILE or (char *) */
int (*ugfunc)();		 stdio.c
_seek STATUS _seek(fd, offset, mode)
FD fd;
int offset;
TINY mode;		 clibmac.mac
_setarg VOID _setarg(s)
char *s;		 process.c Set an argument string to command line (for exec).
_setprog STATUS _setprog(prog, whole, checkp)
char *prog;
char whole[]; /* 67 byte space */
BOOL checkp; /* look at PATH */		 process.c Search prog and set fullpath name in whole (for exec)
_skipsp char *_skipsp(s)
char *s;		 process.c Skip leading blanks.
_spr STATUS _spr(param, outfunc, ___)
int *param;
STATUS (*outfunc)();
char *___; /* p for any type */		 stdio.c
_sscn int _sscn(ptr)
char **ptr;		 stdio.c
_sspr STATUS _sspr(c, ptr)
char c, **ptr;		 stdio.c
_stdenv VOID _stdenv(fp)
FILE *fp;		 process.c
_suget VOID _suget(c, ptr)
char c;
char **ptr;		 stdio.c
_swp VOID _swp(width, x, y)
size_t width;
char *x, *y;		 stdlib.c
_unquote VOID _unquote(s)
char *s;		 process.c
_uspr recursive TINY _uspr(str, n, radix)
char **str;
unsigned n;
TINY radix;		 stdio.c
_whlpath STATUS _whlpath(whole, prog)
char whole[], *prog;		 direct.c
abs int abs(n)
int n;		 stdlib.c Returns the absolute value of its int argument.
alloc char *alloc(nbytes)
size_t nbytes;		 malloc.c Returns a pointer to space for nbytes, or NULL if the request cannot be satisfied. The space is unitialized.
atoi int atoi(s)
char *s;		 stdlib.c Converts s to int.
bdos char bdos(c)
char c;		 clibmac.mac Calls BDOS-routine and returns a character (register A).
bdosh int bdosh(c)
char c;		 clibmac.mac Calls BDOS-routine and returns an integer (register HL).
bios char bios(code)
char code;		 clibmac.mac Calls CP/M BIOS routine. Valid values for code include:
0 xx00h – JMP WBOOT ;Warm boot
1 xx03h – JMP WBOOT ;Warm boot
2 xx06h – JMP CONST ;Console status
3 xx09h – JMP CONIN ;Console input
4 xx0Ch – JMP CONOUT ;Console output
5 xx0Fh – JMP LIST ;List output
6 xx12h – JMP PUNCH ;Punch (auxiliary) output
7 xx15h – JMP READER ;Reader (auxiliary) input
8 xx18h – JMP RETURN ;Home in CP/M
9 xx1Bh – JMP RETURN ;Select disk in CP/M
10 xx1Eh – JMP RETURN ;Set track in CP/M
11 xx21h – JMP RETURN ;Set sector in CP/M
12 xx24h – JMP RETURN ;Set DMA address in CP/M
13 xx27h – JMP RETURN ;Read sector in CP/M
14 xx2Ah – JMP RETURN ;Write sector in CP/M
15 xx2Dh – JMP LSTST ;List status
16 xx30h – JMP RETURN ;Sector translate in CP/M
call int call(addr, a, hl, bc, de)
int *addr, a, hl, bc, de;		 clibmac.mac Calls routine starting at address pointed to by adrr. Before calling, register a, hl, bc and de will be filled with the specified values. Returns with integer (register HL).
calla char calla(addr, a, hl, bc, de)
int *addr, a, hl, bc, de;		 clibmac.mac Calls routine starting at address pointed to by addr. Before calling, register a, hl, bc and de will be filled with the specified values. Returns with character (register A).
callxx VOID callxx(adrs, reg)
unsigned adrs;
XREG *reg;		 clibmac.mac Calls routine starting at address pointed to by adrs. Before calling, register af, ix, iy, bc, de and hl will be filled according to reg (structure XREG is specified in BDOSFUNC.H). On returning, reg will be updated with the new register values.
chdir STATUS chdir(path)
char *path;		 direct.c Change current work directory to path.
clearerr VOID clearerr(fp)
FILE *fp;		 stdio.c Clears all error settings from file fp.
close STATUS close(fd)
FD fd;		 clibmac.mac Releases the specified file handle for re-use by directly calling the operating system using the “Close file handle (45h)” BDOS-routine. Any buffered data will be flushed to disk. Returns ERROR if an error occured.
creat FD creat(filename)
char *filename;		 clibmac.mac Creates a file or sub-directory by directly calling the operating system using the “Create file handle (44h)” BDOS-routine. Open mode is set to “no read” and no special attributes. Returns file handle or ERROR if an error occured.
eof TINY eof(fd)
FD fd;		 io.c Returns zero if end of file occured.
execl VOID execl(nargs, progname, args)
int nargs;
char *progname, *args;		 process.c Execute program progname with argument string args. No path check will be done.
execlp VOID execlp(nargs, progname, args)
int nargs;
char *progname, *args;		 process.c Execute program progname with argument string args. A path check will be done.
execv VOID execv(progname, argv)
char *progname, **argv;		 process.c Execute program progname with argument array argv. No path check will be done.
execvp VOID execvp(progname, argv)
char *progname, **argv;		 process.c Execute program progname with argument array argv. A path check will be done.
exit VOID exit(code)
int code;		 process.c Causes normal program termination. Open files are flushed, open streams are closed, and control plus code is returned to whatever loaded the transient program. This will almost always be the command interpreter, but in some cases it may be another transient program.
expargs int expargs(argc, argv, maxargc, xargv)
int argc, maxargc;
char *argv[], *xargv[];		 direct.c ??
fclose STATUS fclose(fp)
FILE *fp;		 stdio.c Flushes any unwritten data for fp, discards any unread buffered input, frees any automatically allocated buffer, then closes the stream. It returns EOF if any errors occured, and zero otherwise.
fcloseall TINY fcloseall() stdio.c Closes all open streams using fclose. Returns number of closed streams or ERROR if an error occured.
feof int feof(fp)
FILE *fp;		 stdio.h Returns non-zero if the end of file indicator for fp is set.
ferror int ferror(fp)
FILE *fp;		 stdio.h Returns non-zero if the error indicator for fp is set.
fflush STATUS fflush(fp)
FILE *fp;		 stdio.c On an output stream, fflush causes any buffered but unwritten data to be written; on an input stream, the effect is undefined. It returns EOF for a write error, and zero otherwise. fflush(NULL) flushes all output streams.
fgets char *fgets(s, n, fp)
char *s;
int n;
FILE *fp;		 stdio.c Fgets reads at most the next n-1 characters into the array s, stopping if a newline is encountered; the newline is included in the array, which is terminated by ‘\0’. fgets returns s, or NULL if end of file or error occurs.
fileno int fileno(fp)
FILE *fp;		 stdio.h Returns the file handle of file fp. File handles are used by the system calls like open, write, create and unlink.
flushall TINY flushall() stdio.c Flushes all streams using fflush. Returns number of flushed streams.
fopen FILE *fopen(nargs, xfn, xmode, xbsiz)
unsigned nargs;
char *xfn, *xmode;
size_t xbsiz;		 Opens the file pointed to by xfn, and returns a stream, or NULL if the attempt fails. Legal values for xmode include:
“r” open text file for reading
“w” create text file for writing; discard previous contents if any
“a” append; open or create text file for writing at end of file
If xmode is omitted, the file will be openen for reading. If xmode includes b after the initial letter, as in “rb”, that indicates a binary file. If specified, xbsiz changes the buffer size.
fprintf STATUS fprintf(nargs, iobuf, format)
int nargs;
FILE *iobuf;
char *format;		 Converts and writes output to iobuf under the control of format. The return value is non-zero if an error occured. The format string contains two types of objects: ordinary characters, which are copied to the output stream, and conversion specifications, each of which causes conversion and printing of the next successive argument to fprintf. Each conversion specification begins with the character % and ends with a conversion character. Between the % and conversion character there may be, in order:
– Flags (in any order), which modify the specification:
-: which specifies left adjustment of the converted argument in its field
+: which specifies that the number will always be printed with a sign
space: if the first character is not a sign, a space will be prefixed.
0: for numeric conversions, specified padding to the field width with leading zeros.
#: which specifies an alternate output form. For o, the first digit will be zero. For x or X, 0x or 0X will be prefixed to a non-zero result. For e, E, f, g, and G, the output will always have a decimal point; for g and G, trailing zeros will not be removed.
– A number specifying a minimum field width. The converted argument will be printed in a field at least this wide, and wider if necessary. If the converted argument has fewer characters than the field width it will be padded on the left (or right, if left adjustment has been requested) to make up the field width. the padding character is normally space, but is 0 if the zero padding flag is present.
– A period, which separates the field width from the precision.
– A number, the precision, that specifies the maximum number of characters to be printed from a string, or the minimum number of digits to be printed for an integer (leading 0s will be added to make up the necessary width).
– A length modifier. “h” indicates that the corresponding argument is to be printed as a short or unsigned short.
The conversion characters and their meanings are shown beneath. If the character after the % is not a conversion character, the behavior is undefined:
d int; signed decimal notation.
o int; unsigned octal notation (without a leading zero).
x,X int; unsigned hexadecimal notation (without a leading 0x or 0X), using abcdef for 0x or ABCDEF for 0X.
u int; unsigned decimal notation.
c int; single character, after conversion to unsigned char.
s char *; characters from the string are printed until a ‘\0’ is reached or until the number of characters indicated by the precision have been printed.
% no argument is converted; print a %.
fputs STATUS fputs(s, fp)
char *s;
FILE *fp;		 stdio.c Fputs writes the string s (which need not contain ‘\n’) on fp; it returns non-negative, or EOF for an error.
fread int fread(buf, size, count, fp)
char *buf;
int size, count;
FILE *fp;		 stdio.c Fread reads from fp into the array buf at most count objects of size size. Fread returns the number of objects read; this may be less than the number requested. Feof and ferror must be used to determine status.
free void free(ap)
char *ap;		 malloc.c Deallocates the space pointed to by ap; it does nothing if ap is NULL. ap must be a pointer to space previously allocated by alloc.
fscanf int fscanf(nargs, iobuf, format)
int nargs;
FILE *iobuf;
char *format;		 Reads from iobuf under control of format, and assigns converted values through subsequent arguments, each of which must be a pointer! It returns when format is exhausted. fscanf returns EOF if end of file or an error occurs before any conversion; otherwise it returns the number of input items converted and assigned.
The format string usually contains conversion specifications, which are used to direct interpretation of input. The format string may contain:
– Blanks or tabs, which are ignored.
– Ordinary characters (not %), which are expected to match the next non-white space character of the input stream.
– Conversion specifications, consisting of a %, an optional assignment suppression character *, an optional number specifying a maximum field width, an optional h, l, or L indicating the width of the target, and a conversion character.
A conversion specification determines the conversion of the next input field. The result is placed in the variable pointed to by the corresponding argument. An input field is defined as a string of non-white space characters; it extends either to the next white space character or until the field width, if specified, is exhausted. this implies that scanf will read across line boundaries to find its input, since newlines are white space (white space characters are blank, tab, newline, carriage return, vertical tab, and formfeed).
The conversion character indicates the interpretation of the input field. The corresponding argument must be a pointer. The legal conversion characters are:
d decimal integer; int *.
o octal integer (with or without leading zero); int *.
u unsigned decimal integer; unsigned int *.
x hexadecimal integer (with or without leading 0x or 0X); int *.
c characters; char *. The next input characters are placed in the indicated array, up to the number given by the iwdth field; the default is 1. No ‘\0’ is added. The normal skip over white space characters is suppressed in this case; to read the next non-white space character, use %1s.
s string of non-white space characters (not quoted); char *, pointing to an array of characters large enough to hold the string and a terminating ‘\0’ that will be added.
% literal %; no assignment is made.
fsetbin STATUS fsetbin(fp)
FILE *fp;		 stdio.c Set file mode to binary mode.
fsettext STATUS fsettext(fp)
FILE *fp;		 stdio.c Set file mode to text mode.
fwrite int fwrite(buf, size, count, fp)
char *buf;
int size, count;
FILE *fp;		 stdio.c Fwrite writes, from the array buf, count objects of size size on fp. It returns the number of objects written, which is less than count on error.
getc int getc(fp)
FILE *fp;		 stdio.c Getc returns the next character of fp as an unsigned char (converted to an int), or EOF if end of file or error occurs.
getch char getch() io.c Getch reads a character from the standard input. If no character is ready it will wait for one. No echo or control characters checks will be done.
getchar int getchar() stdio.c Getchar is equivalent to getc(stdin).
getche char getche() io.c Getche reads a character from the standard input and echos it to the standard output. If no character is ready it will wait for one. Various control characters will be trapped by this function for various control purposes. If one of these characters is detected then it will be processed and this function will wait for another character. Thus these characters will never be returned by this function.
getcwd char *getcwd(cwd, n)
char *cwd;
int n;		 direct.c Get current work directory.
getenv char *getenv(var)
char *var;		 stdlib.c Returns the environment string associated with var. Returns NULL if the enviroment name var is invalid or if no memory can be nallocated for the temporary buffer.
gets char *gets(s, n)
char *s;
int n;		 stdio.c Gets reads the next input line into the array s; it replaces the terminating newline with ‘\0’. It return s, or NULL if end of file or error occurs.
inp char inp(port)
unsigned port;		 clibmac.mac Input character from port port.
isalnum int isalnum(c)
char c;		 ctype.h Return non-zero if isalpha(c) or isdigit(c), 0 if not.
isalpha int isalpha(c)
char c;		 ctype.h Return non-zero if c is alpabetic, 0 if not.
isatty BOOL isatty(fd)
FD fd;		 io.c Returns zero if the file handle fd refers to a disk file, or non-zero if fd refers to a device.
iscntrl int iscntrl(c)
char c;		 ctype.h Return non-zero if c is control character, 0 if not.
isdigit int isdigit(c)
char c;		 ctype.h Return non-zero if c is digit, 0 if not.
iskanji int iskanji(c)
char c;		 ctype.h Return non-zero if c is kanji first byte, 0 if not.
iskanji2 int iskanji2(c)
char c;		 ctype.h Return non-zero if c is kanji second byte, 0 if not.
islower int islower(c)
char c;		 ctype.h Return non-zero if c is lower case, 0 if not.
isspace int isspace(c)
char c;		 ctype.h Return non-zero if c is blank, tab, newline, return, formfeed or vertical tab.
isupper int isupper(c)
char c;		 ctype.h Return non-zero if c is upper case, 0 if not.
isxdigit int isxdigit(c)
char c;		 ctype.h Return non-zero if c is hexadecimal digit, 0 if not.
kbhit BOOL kbhit() io.c Returns non-zero when a character is ready (that is, a key was pressed) for input from the keyboard. kbhit directly calls the operating system using the “Console status (0Bh)” BDOS-routine.
longjmp void longjmp(env, val)
jmp_buf env;
int val;		 clibmac.mac Restores the state sved by the most recent call to setjmp, using information saved in ev, and execution resumes as if the setjmp function had just executed and returned the non-zero value val. The function containing the setjmp must not have terminated. Accessible objects have the values they had when longjmp was called, except that non-volatile automatic variables in the function calling setjmp become undefined if they were changed after the setjmp call.
max int max(x, y)
int x, y;		 stdlib.c Returns the integer which represents the highest value.
memcpy void memcpy(dest, source, count)
char *dest, *source;
size_t length;		 clibmac.mac Copy lenght characters from source to dest.
memset void memset(dest, byte, count)
char *dest, byte;
size_t length;		 clibmac.mac Place character byte into first length characters of dest.
min int min(x, y)
int x, y;		 stdlib.c Returns the integer which represents the lowest value.
mkdir STATUS mkdir(path)
char *path;		 direct.c Make directory path.
movmem void movmem(source, dest, count)
char *dest, *source;
size_t length;		 clibmac.mac Same as memcpy except that it works even if the objects overlap.
open FD open(filename, mode)
char *filename;
int mode;		 clibmac.mac Opens the file pointed to by filename. open is rather like the fopen function, except that instead of returning a file pointer, it returns a file descriptor, or NULL if the attempt fails. open directly calls the operating system using the “Open file handle (43h)” BDOS-routine, whilst fopen subserves the standard library. Legal values for mode are:
b0 set: no write
b1 set: no read
b2 set: the file handle will be inherited by a new process created by the “fork” system call
outp void outp(port, val)
unsigned port;
char val;		 clibmac.mac Output value val to port port.
perror VOID perror(msg)
char *msg;		 stdlib.c Print previous error from dos.
printf STATUS printf(nargs, format)
int nargs;
char *format;		 stdio.c Equivalent to fprintf(stdout, format).
putc STATUS putc(c, fp)
char c;
FILE *fp;		 stdio.c Putc writes the character s (which need not contain ‘\n’) on fp. It returns the character written, or EOF for error.
putchar STATUS putchar(c)
char c;		 stdio.c Putchar is equivalent to putc(c, stdout).
putenv STATUS putenv(env)
char *env;		 stdlib.c Sets environment item to the specified value. env must be of format:
<varname>=<value>
putenv returns non-zero if an error occured.
puts STATUS puts(s)
char *s;		 stdio.c Puts writes the string s and a newline to stdout. It returns EOF if an error occurs, non-negative otherwise.
qsort void qsort(base, n, width, compar)
char *base;
unsigned n;
size_t width;
int (*compar)();		 stdlib.c Sorts into ascending order an array base[0]…base[n-1] of objects of size size. The comparison function cmp must return negative if its first argument (the search key) is less than its second (a table entry), zero if equal, and positive if greater.
read int read(fd, buf, bytes)
FD fd;
char *buf;
size_t bytes;		 clibmac.mac Reads bytes number of bytes from file fd to buffer buf. Returns with the number of bytes transferred; read returnes no error code. To obtain error codes, see fileno, feof, ferror or eof must be used.
rename STATUS rename(oldname, newname)
char *oldname, *newname;		 clibmac.mac Changes the name of the ffile; it returns non-zero if the attempt fails.
rmdir STATUS rmdir(path)
char *path;		 direct.c Remove directory.
rsvstk void rsvstk(n)
size_t n;		 malloc.c Changes space to set aside for the stack to n. Default size is 1000.
sbrk char *sbrk(n)
size_t n;		 malloc.c Returns a pointer to n more bytes of storage. sbrk returns -1 if there was no space.
scanf int scanf(nargs, format)
int nargs;
char *format;		 stdio.c Identical to fscanf(stdin, format).
sensebrk VOID sensebrk() io.c If a character is ready (that is, a key was pressed) for input from the keyboard, it will be read and tested for certain special control characters. sensebrk directly calls the operating system, using the “Console status (0Bh)” BDOS-routine.
setbuf VOID setbuf(fp, buf)
FILE *fp;
char *buf; /* points allocated buffer (size BUFSIZ) */		 stdio.c If buf is NULL, buffering is turned off for the stream. Otherwise setbuf is equivalent to (void) setvbuf(stream, buf, _IOBF, BUFSIZ).
setjmp VOID setjmp(env)
jmp_buf env;		 clibmac.mac Saves state information in env for use by longjmp. The return is zero from a direct call of setjmp, and non-zero from a subsequent call of longjmp. A call to setjmp can only occur in certain contexts, basically the test of if, switch, and loops, and only in simple relational expressions.
if (setjmp(env) == 0)
/* get here on direct call */
else
/* get here by calling longjmp */
setmem VOID setmem(dest, byte, count)
char *dest, byte;
size_t length;		 Place character byte into first length characters of dest.
setvbuf STATUS setvbuf(fp, buf, mode, size)
FILE *fp;
char *buf;
int mode, size;		 stdio.c Controls buffering for the stream; it must be called before reading, writing, or any other operation. A mode of _IOFBF causes full buffering, _IOLBF line buffering of text files, and _IONBF no buffering. If buf is not NULL, it will be used as the buffer; otherwise a buffer will be allocated. size determines the buffer size. setvbuf returns non-zero for any error.
sprintf VOID sprintf(nargs, buffer, format)
int nargs;
char *buffer, *format;		 stdio.c The same as printf except that the output is written into the string buffer, terminated with ‘\0’. buffer must be big enough to hold the result.
sscanf int sscanf(nargs, line, format)
int nargs;
char *line, *format;		 Equivalent to scanf except that the input characters are taken from the string s.
strcat char *strcat(d, s)
char *d, *s;		 string.c Concatenate string s to end of string d; return s.
strchr char *strchr(s, c)
char *s, c;		 string.c Return pointer to first occurence of c in s, or NULL if not present.
strcmp int strcmp(s, t)
char *s, *t;		 string.c Compare string s to string t; return <0 if s<t, 0 if s==t, or >0 if s>t.
strcpy char *strcpy(d, s)
char *d, *s;		 string.c Copy string s to string d, including ‘\0’; return d.
strlen size_t strlen(s)
char *s;		 string.c Return lenght of string s.
strlwr char *strlwr(s)
char *s;		 string.c Convert string s to lower case; return s.
strncat char *strncat(d, s, n)
char *d, *s;
unsigned n;		 string.c Concatenate at most n characters of string s to string d, terminate d with ‘\0’; return d.
strncmp int strncmp(s, t, n)
char *s, *t;
unsigned n;		 string.c Compare at most n characters of string s to string t; return <0 if s<t, 0 if s==t, or >0 if s>t.
strncpy char *strncpy(d, s, n)
char *d, *s;
unsigned n;		 string.c Copy at most n characters of string s to d; return d. Pad with ‘\0’s if s has fewer than n characters.
strupr char *strupr(s)
char *s;		 string.c Convert string s to upper case; return s.
tolower char tolower(c)
char c;		 string.c Return c converted to lower case.
toupper char toupper(c)
char c;		 string.c Return c converted to upper case.
ungetc STATUS ungetc(c, fp)
char c;
FILE *fp;		 stdio.c Ungetc pushes c (converted to an unsigned char) back onto fp, where it will be returned on the next read. Only one character of pushback per stream is guarenteed. EOF may not be pushed back. Ungetc returns the character pushed back, or EOF for error.
ungetch VOID ungetch(c)
char c;		 stdio.c Ungetch(c) is equivalent to ungetc(c, stdin).
unlink STATUS unlink(filename)
char *filename;		 clibmac.mac Deletes the object (file or sub-directory) specified by filename from the file system. Returns non-zero if an error occured.
write int write(fd, buf, n)
FD fd;
char *buf;
size_t bytes;		 clibmac.mac Writes bytes number of bytes from buffer buf to file fd. Returns with the number of bytes transferred; write returnes no error code. To obtain error codes, see fileno, feof, ferror or eof.
xmain void xmain() ck.mac Used internally.

MSX-C Library System Disk
Table 6: Contents of Library System Disk

-------------------------------------------------------------------
                 PRIMARY FILES      SUPPORT FILES      SOURCE FILES
                 --------------------------------------------------
LIBRARY FILES:   mlib.rel . . . . . glib.rel
                 msxbios.rel
                 math.rel
                 curses.rel
                 glib.rel . . . . . . . . . . . . . . .glib.mac
                 msxbios.rel. . . . . . . . . . . . . .msxbios.mac
                 math.rel . . . . . . . . . . . . . . .mathmac.mac
                                                       prsc.c
                 curses.rel . . . . . . . . . . . . . .cursesc.c
                                                       curses2.c

T-CODE FILES: mlib.tco. . . . . .glib.tco
math.tco
msxbios.tco
curses.tco
glib.tco. . . . . .glibc.c
msxbios.tco . . . .msxbiosc.c
math.tco. . . . . .mathc.c
prsc.c
curses.tco. . . . .cursesc.c
curses2.c

HEADER FILES: glib.h . . . . . . msxbios.h
msxbios.h
math.h
curses.h . . . . . msxbios.h

BATCH FILES: msxc.bat
genall.bat . . . . genmath.bat
gencurs.bat
genglib.bat
genbios.bat
genmlib.bat
gentco.bat
gen.bat
mksys.bat
forremk.bat

SAMPLE FILES: gcal.com . . . . . . . . . . . . . . .gcal.c
——————————————————————

The MSX-C Library System Disk contains a fully equiped library to access functions via C which are specific for the MSX. The library consists of 4 parts:

GLIB grafische functies
MSXBIOS BIOS functies
MATH rekenkundige functies voor variabelen van het type ‘long’ en ‘float’
CURSES functies voor windows onder screen 0

These libraries (GLIB.REL, MSXBIOS.REL, MATH.REL and CURSES.REL) are combined into one library MLIB.REL. The source code of the graphic library can be found in GLIB.MAC: machine language! Many graphical functions are just BIOS calles, but some of the primary functions have been coded in ‘real’ machine language. The graphical library uses the MSXBIOS library to make its BIOS calls. The source code of MSXBIOS.REL can be found in MSXBIOS.MAC.
The source code of the arithmetic functions can be found in MATHMAC.MAC. The file PRSC.C contains new definitions of the ‘printf’ and ‘scanf’ functions, which are able to cope with the ‘slong’ and ‘xdouble’ type definitions of the math library. Finally, the source code of the curses library can be found at CURSESC.C and CURSES2.C. The following header files are present:

GLIB.H Header file voor de grafische library
MATH.H Header file voor de rekenkundige library
MSXBIOS.H Header file voor de MSXBIOS library
CURSES.H Header file voor de windows libary

An automatic build of a C project including the MSX-C library can be performed using the batch file MSXC.BAT. Also it is possible to change to library. With the batch file GENALL.BAT it is possible to rebuild the entire library. GENALL.BAT will use the batch files GENMATH.BAT, GENCURS.BAT, GENGLIB.BAT, GENBIOS.BAT, GENMLIB.BAT, GENTCO.BAT and GEN.BAT to perform this task.
MKSYS.BAT will create another ‘Library System Disk’. This disk will contain all files which are necessary to build an executable from C source files, using the MSX-C library. The batch file FORREMK.BAT is able to create a ‘Library Remake System Disk’. This disk will contain all files which are necessary to rebuild a modified MSX-C library. Finally, the disk contains an example program called GCAL.COM. This program has been coded entirely in C. The source code can be found within GCAL.C
Graphic Library
Table 7: Functions in Graphic Library

Name Declaration SourceFile HeaderFile Description English
boxfill VOID boxfill(x1, y1, x2, y2, color, logop)
NAT x1, y1, x2, y2;
TINY color, logop;		 glib.mac glib.h Draws a coloured rectangle on the screen with upper left corner (x1, y1) and lower right corner (x2, y2) and colour ‘color’. ‘Logop’ determines the logical operation for the colour. MSX-C uses its own routine (no BIOS) for this function.
boxline VOID boxline(x1, y1, x2, y2, color, logop)
NAT x1, y1, x2, y2;
TINY color, logop;		 glib.mac glib.h Draws a rectangle on the screen with upper left corner (x1, y1) and lower right corner (x2, y2) and colour ‘color’. ‘Logop’ determines the logical operation for the colour. MSX-C uses its own routine (no BIOS) for this function
calatr NAT calatr(plane)
TINY plane;		 glib.mac glib.h Returns a pointer to the sprite-attribute table of the specified plane.
calpat NAT calpat(patnum)
TINY patnum;		 glib.mac glib.h Returns a pointer to the defined sprite pattern with number ‘patnum’.
circle VOID circle(x, y, r, color, s_angl, e_angl, aspect)
TINY color;
int s_angl, e_angl;		 glib.mac glib.h Draws a circle on the screen at centre (x, y) and radius ‘r’ with colour ‘color’. ‘S_angl’ and ‘e_angl’ determine the start and endcorner if only a part of the circle needs to be drawn. ‘Aspect’ determines the ratio of the vertical and horizontal radius. Calls the BASIC ROM circle routine with string:
,color, s_angl*(pi/4000h), e_angl*(pi/4000h),
,(ABS(aspect)/32768)^((aspect<0)*2+1)
color VOID color(fore, back, bord)
TINY fore, back, bord;		 glib.mac glib.h Changes the colour of foreground, background and border to successively ‘fore’, ‘back’ and ‘bord’. Calls the CHGCLR BIOS routine.
colspr VOID colspr(plane, color)
TINY plane, *color;		 glib.mac glib.h Colours the specified sprite-plane. ‘Color’ points to colour data to either 8 or 16 bytes, dependant on the sprite size (8×8 or 16×16).
cpym2v VOID cpym2v(src, dir, dx, dy, dp, logop)
TINY *src, dir, dp, logop;
NAT dx, dy;		 glib.mac glib.h Fills a frame with data from the Z80 from address ‘src’. The VRAM frame is determined by (dx, dy). The new colour will be calculated by executing ‘logop’ between the old and new pixel colour. ‘Dir’ specifies if the data from the Z80 must be written to the left (0) or to the right (1). This function will work only at screen modes from 5 to 8.
cpyv2m VOID cpyv2m(sx1, sy1, sx2, sy2, sp, dest)
NAT sx1, sy1, sx2, sy2;
TINY sp, *dest;		 glib.mac glib.h Reads a frame from VRAM and places it at address ‘dest’ of normal RAM. The frame is specified by (sx1, sy1) – (sx2, sy2). ‘Sp’ specifies the number of dots of each line. This function will work only at screen modes from 5 to 8.
cpyv2v VOID cpyv2v(sx1, sy1, sx2, sy2, sp, dx, dy, dp, logop)
NAT sx1, sy1, sx2, sy2, dx, dy;
TINY sp, dp, logop;		 glib.mac glib.h Copies a frame from one VRAM location to another VRAM location. The source frame is specified by (sx1, sy1) – (sx2, sy2) and will be copied to (dx, dy). The new colour will be calculated by executing ‘logop’ between the new and old pixel colour. ‘Sp’ and ‘dp’ determine the number of dots of each line. This function will work only at screen modes from 5 to 8.
filvrm VOID filvrm(adr, len, data)
NAT adr, len;
TINY data;		 glib.mac glib.h Writes ‘len’ bytes with value ‘data’ to VRAM starting at address ‘adr’.
getplt NAT getplt(pal)
TINY pal;		 glib.mac glib.h Gets colour codes of palet colour ‘pal’. Returns with values ‘green’, ‘red’ and ‘blue’ successively. Calls GETPLT SUBROM routine.
ginit VOID ginit() glib.mac glib.h Initializes the read- and writeport of the VDP. On using the Graphic Library, this routine must be called before making any calls to the Graphic Library.
glocate VOID glocate(x, y)
NAT x, y;		 glib.mac glib.h Put the graphic cursor at location (x, y): (GRPACX, GRPACY) = (x, y).
grpprt VOID grpprt(c, logop)
char c;
TINY logop;		 glib.mac glib.h Prints the character ‘c’ on a graphic screen. The colour of the character is determined by executing logical operation ‘logop’ between the new and old pixel colours. Calls the GRPPRT BIOS routine.
gtxmax NAT gtxmax() glib.mac glib.h Returns the maximum number of horizontal pixels of the current screen mode.
gtymax NAT gtymax() glib.mac glib.h Returns the maximum number of vertical pixels of the current screen mode.
iniplt VOID iniplt() glib.mac glib.h Initializes the palet and VRAM by calling the INIPLT SUBROM routine.
inispr VOID inispr(size)
TINY size;		 glib.mac glib.h Initializes all sprites by calling the CLRSPR BIOS routine. Dependant on the value of ‘size’ the following actions will be taken:
1: 8×8 sprite setting
2: 16×16 sprite setting
4: disable sprites (MSX2 only)
interlace VOID interlace() glib.mac glib.h Switches the screen to interlaced mode.
invdp TINY invdp() glib.mac glib.h Reads a byte from the VDP read port. See also ‘setrd().
knjprt VOID knjprt(c, logop, mode)
NAT c;
TINY logop, mode;		 glib.mac glib.h Prints the KANJI character ‘c’ on a graphic screen. The colour of the character is determined by executing logical operation ‘logop’ between the new and old pixel colours. ‘Mode’ may vary from 0 to 2. Calls the KNJPRT BIOS routine.
ldirmv VOID ldirmv(dst, src, len)
NAT src, len;
TINY *dst;		 glib.mac glib.h Copies a block of ‘len’ bytes from VRAM address ‘src’ to RAM memory at destination address ‘dst’.
ldirvm VOID ldirvm(dst, src, len)
NAT dst, len;
TINY *src;		 glib.mac glib.h Copies a block of ‘len’ bytes from RAM address ‘src’ to VRAM memory at destination address ‘dst’.
line VOID line(x1, y1, x2, y2, color, logop)
NAT x1, y1, x2, y2;
TINY color;
TINY logop;		 glib.mac glib.h Draws a line on the screen from (x1, y1) to (x2, y2) with colour ‘color’. ‘Logop’ determines the logical operation with which the colour is calculated. MSX-C uses its own routine (no BIOS routine).
outvdp VOID outvdp(data)
TINY data;		 glib.mac glib.h Writes ‘data’ to the VDP write port. See ‘setwrt()’
paint VOID paint(x, y, color, b_color)
NAT x,y;
TINY color, b_color;		 glib.mac glib.h Paints an area on the graphic screen with colour ‘color’. The coordinates must point to a pixel which lies in the related area. ‘B_color’ determines the colour of the lines within which the computer must do the painting. Calls a routine from SUBROM.
point TINY point(x, y)
NAT x, y;		 glib.mac glib.h Returns the colour the specified pixel at (x, y). MSX-C uses its own rotine (no BIOS).
pset VOID pset(x, y, color, logop)
NAT x, y;
TINY color, logop;		 glib.mac glib.h Sets the colour of the specified pixel (x, y). The new colour will be determines by executing logical operation ‘logop’ between the new and old colour. MSX-C uses its own routine (no BIOS).
putspr VOID putspr(plane, x, y, color, pat) [GLIB.MAC, GLIB.H]
TINY plane, color, pat;
int x, y;		 glib.mac glib.h Puts the sprite with number ‘pat’ at position (x, y) of the specified plane. The sprite will be coloured with the specified colour. MSX-C uses its own routine (no BIOS).
rdvdp TINY rdvdp(vreg)
TINY vreg;		 glib.mac glib.h Reads register ‘vreg’ from VDP (0-23). The VDP registers can’t be read actually, but the BIOS maintains copies of these registers. These copies will be read by this function.
rdvsts TINY rdvsts(sreg)
TINY sreg;		 glib.mac glib.h Reads the value of the VDP status-register ‘sreg’ (0-9)
rstplt VOID rstplt() glib.mac glib.h Reset the palet from VRAM. Calls the RSTPLT SUBROM routine.
setpg VOID setpg(dsppag, actpag)
TINY dsppag, actpag;		 glib.mac glib.h Makes page ‘dsppag’ the VRAM page which is being displayed and page ‘actpag’ the VRAM page on which actions will be taken.
setplt VOID setplt(pal, grbdat)
TINY pal;
NAT grbdat;		 glib.mac glib.h Sets palet colour ‘pal’ with red, green and blue values from structure ‘grbdat’. Calls the SETPLT SUBROM routine.
setrd VOID setrd(adr)
NAT adr;		 glib.mac glib.h Prepares the VDP for reading from VRAM. After this call, one is able to read directly from VRAM with function ‘invdp()’. The VRAM address will be increased automatically after every read.
setwrt VOID setwrt(adr)
NAT adr;		 glib.mac glib.h Prepares the VDP for writing to VRAM. After this call, one is able the write directly to VRAM with function ‘outvdp()’. The VRAM address will be increased automatically after every write.
sprite VOID sprite(pat, data)
TINY pat, *data;		 glib.mac glib.h Defines sprite with number ‘pat’. ‘Data’ is a pointer to a sprite definition which can be either 8 or 16 bytes, depending on the size of the sprite (8×8 or 16×16).
totext VOID totext() glib.mac glib.h Puts the screen into textmode. Calls the TOTEXT BIOS routine.
vpeek TINY vpeek(adr)
NAT adr;		 glib.mac glib.h Reads address ‘adr’ from VRAM.
vpoke VOID vpoke(adr, value)
NAT adr;
TINY value;		 glib.mac glib.h Writes ‘value’ to address ‘adr’ of VRAM.
vramsize NAT vramsize() glib.mac glib.h Returns the size of the video memory (VRAM) (16, 64 or 128K).
wrtvdp VOID wrtvdp(regnum, value)
TINY regnum, value;		 glib.mac glib.h Writes ‘value’ to VDP register ‘regnum’. Calls the WRTVDP BIOS routine.

BIOS Library
Table 8: Functions in BIOS Library

Name Declaration SourceFile HeaderFile Description English
*fnkstr char *fnkstr(n) msxbios.h msxbios.h Returns a pointer to the memory area which holds the definition of function key ‘n’.
*inlin char *inlin() msxbios.mac msxbios.h Reads keyboard input starting at the cursor, into a buffer until a CR or CTRL-STOP is pressed. Returns the starting address of the buffer. Calls INLIN BIOS routine ($00B1).
beep VOID beep() msxbios.mac msxbios.h Sounds a beep. Call the BEEP BIOS routine ($00C0).
breakx TINY breakx() msxbios.mac msxbios.h Checks the status of the CTRL-STOP key combination. Returns with 1 if CTRL-STOP is pressed, 0 if not. Calls the BREAKX BIOS routine ($00B7).
calbas VOID calbas(adrs, reg)
NAT adrs;
REGS *reg;		 msxbios.mac msxbios.h Calls a routine from BASIC-ROM whose begin address is ‘adrs’. ‘Reg’ must point to a table with register values for F, A, BC, DE and HL.
calbio VOID calbio(adrs, reg)
NAT adrs;
REGS *reg;		 msxbios.mac msxbios.h Calls a routine from BIOS-ROM whose begin address is ‘adrs’. ‘Reg’ must point to a table with register values for F, A, BC, DE and HL.
callx VOID callx(adrs, reg)
NAT adrs;
REGS *reg;		 msxbios.mac msxbios.h Calls a routine whose address is ‘adrs’. ‘Reg’ must point to a table with register values for F, A, BC, DE and HL.
calslt VOID calslt(slot, adrs, reg)
TINY slot;
NAT adrs;
REGS *reg;		 msxbios.mac msxbios.h Calls a routine from ‘slot’ whose address is ‘adrs’. ‘Reg’ must point to a table with register values for F, A, BC, DE and HL.
calsub VOID calsub(adrs, reg)
NAT adrs;
REGS *reg;		 msxbios.mac msxbios.h Calls a routine from SUB-ROM whose address is ‘adrs’. ‘Reg’ must point to a table with register values for F, A, BC, DE and HL.
chget char chget() msxbios.mac msxbios.h Waits for and returns with input from the console (the keyboard). Calls the CHGET BIOS routine ($009F).
chgsnd VOID chgsnd(onoff)
BOOL onoff;		 msxbios.mac msxbios.h Changes the status of the 1 bit sound port (??). If ‘onoff’ equals 0 (FALSE), it will be put off, otherwise on.
chput VOID chput(c)
char c;		 msxbios.mac msxbios.h Sends character ‘c’ to the console (the screen). Calls the CHPUT BIOS routine ($00A2).
chsns BOOL chsns() msxbios.mac msxbios.h Checks the status of the keyboard buffer. Returns with 0 if the buffer is empty. Calls the CHSNS BIOS routine ($009C).
cls VOID cls() msxbios.mac msxbios.h Clear screen. Calls the CLS BIOS routine ($00C3).
di VOID di() msxbios.mac msxbios.h Disable interrupt.
disscr VOID disscr() msxbios.mac msxbios.h Disables screen appearance. Calls the DISSCR BIOS routine ($0041). See also ‘enascr()’.
dspfnk VOID dspfnk() msxbios.mac msxbios.h Display of function key display. Calls the DSPFNK BIOS routine ($00CF)
ei VOID ei() msxbios.mac msxbios.h Enable interrupt.
enascr VOID enascr() msxbios.mac msxbios.h Enables screen appearance. Calls the ENASCR BIOS routine ($0044). See also ‘disscr()’.
erafnk VOID erafnk() msxbios.mac msxbios.h Disable function key display. Calls the ERAFNK BIOS routine ($00CC).
gicini VOID gicini() msxbios.mac msxbios.h Initializes the PSG (Programmable Sound Generator). Calls the GICINI BIOS routine ($0090).
gtpad TINY gtpad(pad)
TINY pad;		 msxbios.mac msxbios.h Get status of device ‘pad’:
0- 3: touchpad on connection 1
4- 7: touchpad on connection 2
8-11: lightpen
12-15: mouse or trackball on connection 1
16-19: mouse or trackball on connection 2
Dependant on the value of ‘pad’ the following values can be returned:
0/4/ 8/12/16: 0 if not present, -1 if present/touched. This status has to be checked before the x or y coordinate of the device can be checked.
1/5/ 9/13/17: x coordinate
2/6/10/14/18: y coordinate
3/7/11: status of switch (0 not pressed, -1 pressed)
The status of the mouse buttons must be checked using ‘gttrig()’. Calls the GTPAD BIOS routine ($00DB).
gtpdl TINY gtpdl(pdl)
TINY pdl;		 msxbios.mac msxbios.h Get status of paddle ‘pdl’ (1-12). The paddles at connection 1 are identified as 1, 3, 5, 7, 9 and 11. The paddles at connection 2 are 2, 4, 6, 8, 10 and 12. Returns with value of paddle (0-255). Calls GTPDL BIOS routine ($00DE).
gtstck TINY gtstck(port)
TINY port;		 msxbios.mac msxbios.h Reads current setting of the joystick or the four cursor keys, dependable on ‘port’:
0: cursor keys
1: connection 1
2: connection 2
Returns with code which indicates the direction:
8 1 2
\ | /
7- 0 -3
/ | \
6 5 4
Calls GTSTCK BIOS routine ($00D5).
gttrig BOOL gttrig(trig)
TINY trig;		 msxbios.mac msxbios.h Get status of fire button, indicated by ‘trig’:
0: spacebar
1: first fire button at connection 1
2: first fire button at connection 2
3: second fire button at connection 1
4: second fire button at connection 2
Returns 1 if the fire button is pressed, 0 if not. Calls GTTRIG BIOS routine ($00D8).
inifnk VOID inifnk() msxbios.mac msxbios.h Initializes the function key definion. Calls INIFN BIOS routine ($003E).
kilbuf VOID kilbuf() msxbios.mac msxbios.h Clears keyboard buffer. Calls KILBUF BIOS routine ($0156).
locate VOID locate(csrx, csry)
TINY csrx, csry;		 msxbios.mac msxbios.h Positions the cursor. Calls POSIT BIOS routine ($00C6).
lptout BOOL lptout(c)
char c;		 msxbios.mac msxbios.h Sends character ‘c’ to the printer. Returns 0 if output succeeded, 1 if not. Calls LPTOUT BIOS routine ($00A5).
lptstt BOOL lptstt() msxbios.mac msxbios.h Checks status of printer. Returns 1 if printer is ready, 0 if not. Calls LPTSTT BIOS routine.
msx2 TINY msx2() msxbios.h msxbios.h Returns 0 if the machine is a MSX1.
pinlin char *pinlin() msxbios.mac msxbios.h Reads input from the keyboard starting at column 1 into a buffer untill a CR or CTRL-STOP is pressed. Returns the start address of the buffer. Calls PINLIN BIOS routine ($00AE).
rdpsg TINY rdpsg(reg)
TINY reg;		 msxbios.mac msxbios.h Reads the content of PSG register ‘reg’. Calls RDPSG BIOS routine ($0096).
rdslt TINY rdslt(slot, adrs) msxbios.mac msxbios.h Reads address ‘adrs’ of slot ‘slot’. Calls the RDSLT BIOS routine.
rnd NAT rnd(range)
NAT range;		 msxbios.mac msxbios.h Returns a random number whose size lies between 0 and ‘range’.
screen VOID screen(mode) msxbios.mac msxbios.h Switches screen in ‘mode’ and initializes the palet on a MSX2 machine. Calls the CHGMOD BIOS routine ($005F).
snsmat TINY snsmat(row)
TINY row;		 msxbios.mac msxbios.h Returns the status of the specified ‘row’ of the keyboard:
rij\kolom X7 X6 X5 X4 X3 X2 X1 X0
Y0 7 6 5 4 3 2 1 0
Y1 ; [ @ \ ^ – 9 8
Y2 B A _ / . , ] :
Y3 J I H G F E D C
Y4 R Q P O N M L K
Y5 Z Y X W V U T S
Y6 F3 F2 F1 CODE CAPS GRAPH CTRL SHIFT
Y7 RET SEL BS STOP TAB ESC F5 F4
Y8 RIGHT DOWN UP LEFT DEL INS HOME SPACE
The corresponding bit will be 0 if a key is pressed. Calls the SNSMAT BIOS routine ($0141).
sound VOID sound(reg, val)
TINY reg, val;		 msxbios.mac msxbios.h Writes value ‘val’ to register ‘reg’ of the PSG. Calls WRTPSG BIOS routine ($0093).
wrslt VOID wrslt(slot, adrs, value)
TINY slot;
NAT adrs;
TINY value;		 msxbios.mac msxbios.h Writes value ‘val’ to address ‘adrs’ of slot ‘slt’. Calls the WRSLT BIOS routine.

Math Library
The Math Library contains routines which handle calculation with ‘signed long’ and ‘xdouble’ variables. To perform this task, the Math Library will use function calls from the Basic-ROM. These function calls, which is ofter referred to as ‘MathPack’, are present in both MSX1 and MSX2. They are able to process all kind of numbers. Integers and numbers of single and double precision can be converted, moved and be subjected to calculations. A function call to the MathPack however, isn’t a simple inter-slot call. Due to a design fault in the MathPack, page 1 of the Basic-ROM also needs to be active. Also the error handler must be hooked to prevent jumping to the BASIC interpreter in case an error occurs. Unfortunately the Math Library itself states it still contains some bugs:

  • too many instrunctions are used before the MathPack is called eventually
  • H.NMI is overwritten without being restored
  • the value of H.ERROR gets lost

The routine for calling a MathPack-funtion is almost identical to the CALBAS routine, as defined in the MSXBIOS library. It would be possible to combine both routines.
It would be possible to rebuild a faster version of the MATH-library by defining the lable ‘FAST’ and rebuilding the library. The drawback of this method, is the calling C program has to call ‘MATHINI’ at the begin and ‘MATHEND’ at the end of the program.
Table 9: Function in Math Library

Name Declaration SourceFile HeaderFile Description English
atosl SLONG *atosl(v, s)
SLONG *v;
char *s;		 mathmac.mac math.h Converts ASCII string ‘s’ to a ‘long’ value.
atoxd STATUS atoxd(ans, s)
XDOUBLE *ans;
char *s;		 mathmac.mac math.h Converts an ASCII string ‘s’ to a ‘xdouble’ value.
itosl SLONG *itosl(ans, p1)
SLONG *ans;
int p1;		 mathmac.mac math.h Converts an ‘integer’ value to a ‘long’ value.
itoxd STATUS itoxd(ans, i)
XDOUBLE *ans;
int i;		 mathmac.mac math.h Converts an ‘integer’ value to ‘xdouble’ value.
math2 STATUS math2(add, ?, ?, ans, p1, p2)
STATUS (*add)();
ans, p1, p2 is in back regs		 mathmac.mac math.h *p1 -> dac, *p2 -> arg
Calls the ‘add’ routine from the Math-pack.
mathu VOID mathu(hl, de, bc, add)
unsigned hl, de, bc;
STATUS (*add)();		 mathmac.mac math.h Calls the ‘add’ routine from the Math-pack.
slabs SLONG *slabs(ans, p1)
SLONG *ans, *p1;		 mathmac.mac math.h *ans = |*p1|;
sladd SLONG *sladd(ans, p1, p2)
SLONG *ans, *p1, *p2;		 mathmac.mac math.h *ans = *p1 + *p2;
sland SLONG *sland(ans, p1, p2)
SLONG *ans, *p1, *p2;		 mathmac.mac math.h *ans = *p1 & *p2;
slcmp int slcmp(p1, p2)
SLONG *p1, *p2;		 mathmac.mac math.h (*p1 – *p2)
slcpy SLONG *slcpy(ans, p1)
SLONG *ans, *p1;		 mathmac.mac math.h
sldiv SLONG *sldiv(ans, p1, p2)
SLONG *ans, *p1, *p2;		 mathmac.mac math.h *ans = *p1 / *p2 (signed)
slmod SLONG *slmod(ans, p1, p2)
SLONG *ans, *p1, *p2;		 mathmac.mac math.h *ans = *p1 % *p2 (signed)
slmul SLONG *slmul(ans, p1, p2)
SLONG *ans, *p1, *p2;		 mathmac.mac math.h *ans = *p1 * *p2;
slneg SLONG *slneg(ans, p1)
SLONG *ans, *p1;		 mathmac.mac math.h *ans = -*p1
slnot SLONG *slnot(ans, p1)
SLONG *ans, *p1;		 mathmac.mac math.h *ans = ~*p1;
slor SLONG *slor(ans, p1, p2)
SLONG *ans, *p1, *p2;		 mathmac.mac math.h *ans = *p1 | *p2;
slrl SLONG *slrl(ans, p1, k)
SLONG *ans, *p1;
TINY k;		 mathmac.mac math.h *ans = *p1 << k;
slrlc SLONG *slrlc(ans, p1, k)
SLONG *ans, *p1;
TINY k;		 mathmac.mac math.h *ans = *p1 << k;
slrr SLONG *slrr(ans, p1, k)
SLONG *ans, *p1;
TINY k;		 mathmac.mac math.h *ans = *p1 >> k;
slrrc SLONG *slrrc(ans, p1, k)
SLONG *ans, *p1;
TINY k;		 mathmac.mac math.h *ans = *p1 >> k;
slsgn int slsgn(p1)
SLONG *p1;		 mathmac.mac math.h
slsla SLONG *slsla(ans, p1, k)
SLONG *ans, *p1;
TINY k;		 mathmac.mac math.h *ans = *p1 << k;
slsll SLONG *slsll(ans, p1, k)
SLONG *ans, *p1;
TINY k;		 mathmac.mac math.h *ans = *p1 << k;
slsra SLONG *slsra(ans, p1, k)
SLONG *ans, *p1;
TINY k;		 mathmac.mac math.h *ans = *p1 >> k;
slsrl SLONG *slsrl(ans, p1, k)
SLONG *ans, *p1;
TINY k;		 mathmac.mac math.h *ans = *p1 >> k;
slsub SLONG *slsub(ans, p1, p2)
SLONG *ans, *p1, *p2;		 mathmac.mac math.h
sltoa char *sltoa(str, sl, radix)
char *str;
SLONG *sl;
TINY radix; /* if (bit7 of radix)=1, *sl is unsigned. */		 mathmac.mac math.h Converts a ‘long’ value to an ASCII string.
sltoxd STATUS sltoxd(ans, p1)
XDOUBLE *ans;
SLONG *p1;		 mathmac.mac math.h Converts a ‘signed long’ value to a ‘xdouble’ value. See also ‘ultoxd()’.
slxor SLONG *slxor(ans, p1, p2)
SLONG *ans, *p1, *p2;		 mathmac.mac math.h *ans = *p1 ^ *p2;
uitosl SLONG *uitosl(ans, p1)
SLONG *ans;
unsigned p1;		 mathmac.mac math.h Converts an ‘unsigned int’ value into a ‘long’ value.
uldiv SLONG *uldiv(ans, p1, p2)
SLONG *ans, *p1, *p2;		 mathmac.mac math.h *ans = *p1 / *p2 (unsigned)
ulmod SLONG *ulmod(ans, p1, p2)
SLONG *ans, *p1, *p2;		 mathmac.mac math.h *ans = *p1 % *p2
ultoxd STATUS ultoxd(ans, p1)
XDOUBLE *ans;
SLONG *p1;		 mathmac.mac math.h Converts an ‘unsigned long’ value to a ‘xdouble’ value. See also ‘sltoxd()’.
xdadd STATUS xdadd(ans, p1, p2)
XDOUBLE *ans, *p1, *p2;		 mathmac.mac math.h *ans = *p1 + *p2; in xdouble type
xdatn STATUS xdatn(ans, p1)
XDOUBLE *ans, *p1;		 mathmac.mac math.h *ans = (XDOUBLE)atn((*p1)); in xdouble type
xdceil STATUS xdceil(ans, p1)
XDOUBLE *ans, *p1;		 mathmac.mac math.h *ans = (XDOUBLE)ceil((*p1)); in xdouble type
ceil(x) = ((floor(x) == x ? floor(x) : floor(x)+1);
xdcmp int xdcmp(p1, p2)
XDOUBLE *p1, *p2;		 mathmac.mac math.h Returns ‘1’ if (*p1 > *p2), ‘0’ if (*p1 == *p2) or ‘-1’ if (*p1 < *p2)
xdcos STATUS xdcos(ans, p1)
XDOUBLE *ans, *p1;		 mathmac.mac math.h *ans = (XDOUBLE)cos((*p1)); in xdouble type
xdcpy XDOUBLE *xdcpy(ans, p1)
XDOUBLE *ans, *p1;		 mathmac.mac math.h Copies value ‘p1’ to ‘ans’.
xddiv STATUS xddiv(ans, p1, p2)
XDOUBLE *ans, *p1, *p2;		 mathmac.mac math.h *ans = *p1 * *p2; in xdouble type
xdexp STATUS xdexp(ans, p1)
XDOUBLE *ans, *p1;		 mathmac.mac math.h *ans = (XDOUBLE)exp((*p1)); in xdouble type
xdfabs STATUS xdfabs(ans, p1)
XDOUBLE *ans, *p1;		 mathmac.mac math.h *ans = (XDOUBLE)fabs((*p1)); in xdouble type
xdfix STATUS xdfix(ans, p1)
XDOUBLE *ans, *p1;		 mathmac.mac math.h *ans = (XDOUBLE)fix((*p1)); in xdouble type
xdfloor STATUS xdfloor(ans, p1)
XDOUBLE *ans, *p1;		 mathmac.mac math.h *ans = (XDOUBLE)floor((*p1)); in xdouble type
xdlog STATUS xdlog(ans, p1)
XDOUBLE *ans, *p1;		 mathmac.mac math.h *ans = (XDOUBLE)log((*p1)); in xdouble type
xdmul STATUS xdmul(ans, p1, p2)
XDOUBLE *ans, *p1, *p2;		 mathmac.mac math.h *ans = *p1 * *p2; in xdouble type
xdneg STATUS xdneg(ans, p1)
XDOUBLE *ans, *p1;		 mathmac.mac math.h *ans = -(*p1); in xdouble type
xdnrm STATUS xdnrm(ans, p1)
XDOUBLE *ans, *p1;		 mathmac.mac math.h *ans = (XDOUBLE)(*p1); in xdouble type
xdpow STATUS xdpow(ans, p1, p2)
XDOUBLE *ans, *p1, *p2;		 mathmac.mac math.h *ans = pow(*p1, *p2); in xdouble type
xdrnd STATUS xdrnd(ans, p1)
XDOUBLE *ans, *p1;		 mathmac.mac math.h *ans = (XDOUBLE)rnd((*p1)); in xdouble type
xdsgn int xdsgn(p1)
XDOUBLE *p1;		 mathmac.mac math.h Returns ‘1’ if (*p1 > 0), ‘0’ if (*p1 == 0) or ‘-1’ if (*p < 0).
xdsin STATUS xdsin(ans, p1)
XDOUBLE *ans, *p1;		 mathmac.mac math.h *ans = (XDOUBLE)sin((*p1)); in xdouble type
xdsqrt STATUS xdsqrt(ans, p1)
XDOUBLE *ans, *p1;		 mathmac.mac math.h *ans = (XDOUBLE)sqrt((*p1)); in xdouble type
xdsub STATUS xdsub(ans, p1, p2)
XDOUBLE *ans, *p1, *p2;		 mathmac.mac math.h *ans = *p1 – *p2; in xdouble type
xdtan STATUS xdtan(ans, p1)
XDOUBLE *ans, *p1;		 mathmac.mac math.h *ans = (XDOUBLE)tan((*p1)); in xdouble type
xdtoa char *xdtoa(s, p1, digits)
char *s;
XDOUBLE *p1;
TINY digits;		 mathmac.mac math.h Converts ‘xdouble’ value ‘p1’ to an ASCII string. Variable ‘digits’ defines the number of decimals.
xdtoi STATUS xdtoi(ans, p1)
int *ans;
XDOUBLE *p1;		 mathmac.mac math.h Converts an ‘xdouble’ value to an ‘integer’ value.
xdtosl STATUS xdtosl(ans, p1)
SLONG *ans;
XDOUBLE *p1;		 mathmac.mac math.h Converts an ‘integer’ value to a ‘signed long’ value.

Curses Library
Table 10: Functions in Curses Library

Name Declaration SourceFile HeaderFile Description English
addch STATUS addch(ch)
char ch;		 cursesc.c curses.h
addstr STATUS addstr(str)
char *str;		 cursesc.c curses.h
box STATUS box(win, vert, hor)
WINDOW *win;
char vert, hor;		 cursesc.c curses.h
cgetch char cgetch() curses2.c curses.h
clear STATUS clear() curses2.c curses.h
clearok clearok(win, bf) curses.h curses.h
clrtobot VOID clrtobot() cursesc.c curses.h
clrtoeol VOID clrtoeol() cursesc.c curses.h
delch STATUS delch() cursesc.c curses.h
deleteln VOID deleteln() cursesc.c curses.h
delwin VOID delwin(win)
WINDOW *win;		 cursesc.c curses.h
echo VOID echo() curses.h curses.h
endwin VOID endwin() cursesc.c curses.h
erase VOID erase() cursesc.c curses.h
getstr STATUS getstr(str)
char *str;		 curses2.c curses.h
getyx getyx(win, y, x) curses.h curses.h
inch char inch() curses2.c curses.h
initscr WINDOW *initscr() cursesc.c curses.h
insertln STATUS insch(ch)
char ch;		 cursesc.c curses.h
insertln VOID insertln() cursesc.c curses.h
memmove VOID memmove(d, s, n)
char *d, *s;
unsigned n;		 cursesc.c curses.h
move STATUS move(y, x)
int y, x;		 cursesc.c curses.h
mvaddch STATUS mvaddch(y, x, ch)
int y, x;
char ch;		 curses2.c curses.h
mvaddstr STATUS mvaddstr(y, x, str)
int y, x;
char *str;		 curses2.c curses.h
mvdelch STATUS mvdelch(y, x)
int y, x;		 curses2.c curses.h
mvgetch char mvgetch(y, x)
int y, x;		 curses2.c curses.h
mvgetstr STATUS mvgetstr(y, x, str)
int y, x;
char *str;		 curses2.c curses.h
mvinch char mvinch(y, x)
int y, x;		 curses2.c curses.h
mvinsch STATUS mvinsch(y, x, c)
int y, x;
char c;		 curses2.c curses.h
mvprintw STATUS mvprintw(nargs, y, x, format)
int nargs;
int y, x;
char *format;		 curses2.c curses.h
mvwadch STATUS mvwadch(win, y, x, ch)
WINDOW *win;
int y, x;
char ch;		 curses2.c curses.h
mvwadstr STATUS mvwadstr(win, y, x, str)
WINDOW *win;
int y, x;
char *str;		 curses2.c curses.h
mvwdelch STATUS mvwdelch(win, y, x)
WINDOW *win;
int y, x;		 curses2.c curses.h
mvwgtch char mvwgtch(win, y, x)
WINDOW *win;
int y, x;		 curses2.c curses.h
mvwgtstr STATUS mvwgtstr(win, y, x, str)
WINDOW *win;
int y, x;
char *str;		 curses2.c curses.h
mvwin STATUS mvwin(win, y, x)
WINDOW *win;		 cursesc.c curses.h
mvwinch char mvwinch(win, y, x)
WINDOW *win;
int y, x;		 curses2.c curses.h
mvwinsch STATUS mvwinsch(win, y, x, c)
WINDOW *win;
int y, x;
char c;		 curses2.c curses.h
mvwprintw STATUS mvwprintw(nargs, win, y, x, format)
int nargs;
WINDOW *win;
int y, x;
char *format;		 curses2.c curses.h
newwin WINDOW *newwin(lines, cols, begin_y, begin_x)
int lines, cols, begin_y, begin_x;		 cursesc.c curses.h
noecho VOID noecho() curses.h curses.h
offcur VOID offcur() cursesc.c curses.h
oncur VOID oncur() cursesc.c curses.h
overwrite VOID overwrite(win1, win2)
WINDOW *win1, *win2;		 cursesc.c curses.h
printw STATUS printw(nargs, format)
int nargs;
char *format;		 curses2.c curses.h
raw VOID raw() curses.h curses.h
refresh STATUS refresh() cursesc.c curses.h
scroll STATUS scroll(win)
WINDOW *win;		 cursesc.c curses.h
scrollok scrollok(win, bf) curses.h curses.h
subwin WINDOW *subwin(win, lines, cols, begin_y, begin_x)
int lines, cols, begin_y, begin_x;		 cursesc.c curses.h
touchwin STATUS touchwin(win)
WINDOW *win;		 cursesc.c curses.h
waddch STATUS waddch(win, ch)
WINDOW *win;
char ch;		 cursesc.c curses.h
waddstr STATUS waddstr(win, str)
WINDOW *win;
char *str;		 cursesc.c curses.h
wclear STATUS wclear(win)
WINDOW *win;		 curses2.c curses.h
wclrbot VOID wclrbot(win)
WINDOW *win;		 cursesc.c curses.h
wclreol VOID wclreol(win)
WINDOW *win;		 cursesc.c curses.h
wclrtobot VOID wclrtobot(win)
WINDOW *win;		 curses.h curses.h
wclrtoeol VOID wclrtoeol(win)
WINDOW *win;		 curses.h curses.h
wdelch STATUS wdelch(win)
WINDOW *win;		 cursesc.c curses.h
wdeleteln VOID wdeleteln(win)
WINDOW *win;		 cursesc.c curses.h
werase VOID werase(win)
WINDOW *win;		 cursesc.c curses.h
wgetch char wgetch(win)
WINDOW *win;		 curses2.c curses.h
wgetstr STATUS wgetstr(win, str)
WINDOW *win;
char *str;		 curses2.c curses.h
winch char winch(win)
WINDOW *win;		 curses2.c curses.h
winsch STATUS winsch(win, ch)
WINDOW *win;
char ch;		 cursesc.c curses.h
winsertln VOID winsertln(win)
WINDOW *win;		 cursesc.c curses.h
wmove STATUS wmove(win, y, x)
WINDOW *win;		 cursesc.c curses.h
wprintw STATUS wprintw(nargs, win, format)
int nargs;
WINDOW *win;
char *format;		 curses2.c curses.h
wrefresh STATUS wrefresh(win)
WINDOW *win;		 cursesc.c curses.h

Tips & Tricks
Identifiers
The subsequent programs which treat the C source, all use their own treatment of identifiers as shown underneath:
Table 11: Treatment of identifiers

-----------------------------------------------------------
                      significance      treats uppercase
                       characters   different from lowercase
-----------------------------------------------------------
Compiler (CF & CG)           16               YES
Assembler (M80)               6               NO
Linker (L80)                  6               NO
-----------------------------------------------------------

The MSX-C Compiler (CF & CG) treats uppercase different from lowercase and has a significant label lengt of 16 characters. The assembler (M80) and the linker (L80) do not treat uppercase different from lowercase and their significant labellengt is a mere 6 characters. Because identifiers of C variables are passed on to M80 and L80 by the MSX-C Compiler, we’re stuck with a significant label length of 6 characters for C variables. Identifiers of define labels and typedefs on the other hand, are used by the compiler only, so their significant label length will be 16 characters, whereas uppercase will be treated different from lowercase.
For example: The next function declarations are identical to M80, so if they’re all used in the same program, M80 will generate an error message during the compile phase:

VOID Functn1() ()
VOID Functn2() ()
VOID FUNCTN3() ()

The compiler DOES see the next declarations as all different identifiers:

#define Defined_label1 GreenPeace
#define Defined_label2 Ozon
#define Defined_Label2 Gasoline
typedef unsigned shoarmapositive
typedef char shoarmanegative

Argument passing
If you have machinecode programs and you want to call them directly from C language, you have to know how arguments are passed. That’s what this section is all about.
Argument passing between the different MSX-C functions can be done by the stack, the Z80 registers, or both. By putting the compiler in recursivemode, all arguments will be passed by the stack, allowing recursive programming. In non-recursivemode, the first 3 arguments of any function call will be passed using the Z80 registers, thus taking account for faster argument passing.
Using the preprocessor commands:

#pragma rec
#pragma nonrec

one is able to switch the compiler between recursiveand nonrecursivemode respectively. Also it is possible to declare just one function as recursiveby putting this keyword in front of the function:

recursive VOID function()

The default mode for the compiler is non-recursive. The next table shows how the arguments are passed depending on the different modes and type of arguments:
Table 12: Argument passing

----------------------------------------------------------
                       non-recursive             recursive
            ----------------------------------------------
                    length of parameter
            ----------------------------------
            1 byte (char)    2 bytes (integer)
----------------------------------------------------------
   1              A                HL             (SP-1)
   2              E                DE             (SP-2)
   3              C                BC             (SP-3)
   4                    (SP-1)                    (SP-4)
   5                    (SP-2)                    (SP-5)
   :                       :                         :
   n                  (SP-(n-3))                  (SP-n)
----------------------------------------------------------
                                      (SP = Stack Pointer)

Depending of the type of the argument – char or integer – and assuming the compiler is in non-recursivemode, the argument will be passed using the A or the HL register respectively. In non-recursivemode the DE and BC register will be used to pass the second and third arguments respectively. Keep in mind the high-byte (D resp. B) will contain non-determined values once a char is passed as an argument. If the function call contained a fourth or even more arguments, they will be passed to the function using the stack. Once on the stack, both a char and an integer will be treated as 2 byte values.
If the compiler is in recursivemode, arguments will be passed to the function using the stack for each argument.
The last address on the stack is the return address to which the called function will return once it has completed. If an argument is passed without declaration – i.e. the variable is not declared as either integer or char – the compiler will assume the value to be an integer.
For example: Suppose the function EXAMPL is called, using the following syntax:

EXAMPL (char1, int1, char2, char3, int2, int3);

Now EXAMPL can find the arguments at the following locations:

char1: A
int1: DE
char2: C
char3: (SP-1)
int2: (SP-2)
int3: (SP-3)

With syntax:

EXAMPL(12);

the value 12 will be passed using register HL. If you want to pass the argument using register A, you’ll have to use type casting:

EXAMPL((char) 12);

Memory management
A typical MSX-C program would have its 64K arranged as shown underneath:
Table 13: Memory layout

--------------------------------------------------------
       0FFFFh -----------------------------
                          hooks
       0FD99h -----------------------------
                      working area
       0F380h -----------------------------
      (00006h)----------------------------- Top of TPA
                          stack           ^
                            :             | (_torelance)
             _ _ _ _ _ _ _ _ _ _ _ _ _ _ _v_
                          heap

       ----------------------------- (_endx)

Transient Program

      0100h ----------------------------- Start of TPA

	  Transient Program
      Parameter Areas
      0000h 
            -----------------------------
--------------------------------------------------------
(TPA = Transient Program Area)

RAM memory from address 0FD9Ah up to and including 0FFCAh is reserved to be used by hook-addresses. The memory between addresses 0F380h and 0FD99H – known as the working area – contains the variables which are used by the BIOS and the BASIC interpreter. The available memory to external devices or even small programs is located below the working area and above the TPA (Transient Program Area).
Each MSX-C program will automatically set the stack pointer to the top of the TPA by reading the contents of address 0006h. This piece of code resides in CK.REL , which will automatically be linked into every MSX-C program. The source code can be found at CK.MAC .
The memory between the stack and address 0100h is available to the MSX-C program. The high limit of the memory space is hold by the variable _endx . The variable _torelance defines the available space for the stack to grow. The free space between the lower limit of the stack and the higher limit of the program is often referred to as heap. To manage this heap memory, MSX-C offers 4 functions: alloc() , free() , rsvstk() and sbrk() :
char *alloc(size_t nbytes) [MALLOC.C]
Returns with a pointer to nbytes of free heap space, or NULL if the request cannot be aggreed to. The allocated space will not be initialized (i.e. contains garbage).
Once the memory gotten from alloc isn’t used anymore, it can be given ‘back’ to alloc by calling the free() function with the returned pointer of alloc as argument.
Keep in mind the memory available to alloc() very well may not be one continuous block of free memory. This especially is true once a program uses a number of sbrk() calls. To keep track of this discontinuous memory spaces, alloc() uses a list of free memory blocks internally. Every block contains information about its size, a pointer to the next free memory space and a pointer to the start of its memory space. The memory blocks are stored, sorted from low to high memory address and the last (highest) memory block points to the first.
Now if someone calls for memory, alloc() will walk through this list untill it founds a piece of memory which is big enough to hold the requested amount of memory. If no memory block satisfies the request, alloc() will call sbrk() for a brand new piece of memory.
VOID free(char *ap) [MALLOC.C]
Frees the memory pointed to by pointer ap . ap has to be retrieved from a alloc() call.
VOID rsvstk(size_t n) [MALLOC.C]
Modifies the reserved stack space ( _torelance ). The default value of _torelance is 1000.
char *sbrk(size_t n) [MALLOC.C]
Returns a pointer to n bytes of free memory, or -1 if the heap can’t deliver this amout. If the heap is big enough, sbrk() takes the first available memory space just above the program code and raises _endx with n .
Bibliography
The C programming Language
Brian W. Kernighan/ Dennis M. Ritchie
Prentice Hall Software Series, ISBN 0-13-110362-8
CP/M voor gevorderden
A. Clarke/ J.M. Eaton/ D. Powys-Lybbe
Academic Service, ISBN 90 6233 166 1
MSX ROM BIOS handboek
MSX-DOS 2.20 Programme Reference Manual 1; Function Codes Specifications,
H.S.H. Computervertrieb GmbH, 1989
MSX-DOS 2.20 Programme Reference Manual 2; Transient Program Interface Specifications,
H.S.H. Computervertrieb GmbH, 1989
HiSoft C Manual
H.S.H. Computervertrieb GmbH, 1988
MSX Math-Pack (deel 1)
MSX Computer Magazine 44
Ken uw computer: de V9938 videochip
Emil Hensen, MSX Club Magazine 25, 26 en 27
De MSX-2 videoprocessor
Nico van Rooijen, HCC Nieuwbrief 113 en 114