Power-Programmierung/CD2.mdf/c/compiler/miracl/miracle.txt

Text File | 1993-02-08 | 60KB | 2,660 lines

            User Manual


            Miracle C Compiler



            version 1.5
            17 January 1993



            Copyright 1989-93  T Szocik
















The Miracle C Compiler runs on a 386 PC (or better) under
MS-DOS, accepting a dialect of the C language and
generating object code suitable for Microsoft or
compatible linker.

All of traditional (Kernighan & Ritchie) C syntax is
implemented, including record (struct/union) and
enumerated data types, int, long and floating point data
types, user type definition, bit fields in structs,
initializers for all data types. Both traditional and new
(ANSI) function declaration is supported. There is a
comprehensive library of functions.


REGISTRATION

The compiler is shareware, and is supplied  on a trial
use basis. The compiler package is copyright material and
should not be modified or disassembled. Programs written
using the compiler may be freely distributed.

If you find it useful you should register. Registration
costs 10 pounds in the UK, 25 dollars overseas, and
entitles you to receive a printed copy of the
documentation and upgrades for one year.

Registration is from the author;

    T Szocik
    45 Englewood Road
    London S.W.12 9PA
    United Kingdom.

Miracle C is under active development by the author. By
registering you support further development of the
compiler. Should you wish to make a direct contribution
to a future release (for example by writing a compiler
utility, library functions or source code), please write
to the developer at the above address.



USING THE COMPILER

The following files are present in a compressed form in
the self-extracting archive;

miracle.doc    documentation in MS Word format
miracle.txt    documentation in text format
cc.exe        the C Compiler
ccl.lib        C compiler library
mc.bat        batch file for compiler

and several example programs;

example.c
hanoi.c
cat.c
sieve.c
maze.c    maze
slr.c    grammar.c



Floating point support;

The compiler requires an 8087 coprocessor (or better), or
emulation program, to perform floating point arithmetic.
A public domain emulation program (em87.com) is to be
found in the compiler archive.






The compiler uses the following environment variables;

LIB        directory containing library ccl.lib
        (this is only used by a linker)

INCLUDE    directory containing system include files <*.h>
        (if unset, defaults to \cc\include)

LINKER    name of linker, eg LINKER=BLINK
        (if unset, defaults to LINK, the Microsoft
linker)

        Note that a linker is not supplied with the
compiler.
        Use the Microsoft linker supplied with DOS, or
a compatible linker.

        CC output is Microsoft/Intel object module
format, as documented
        in the MS-DOS Encyclopedia. The linker must
accept Microsoft object.

Before compiling a program set the environment variables
to suitable values;

C:\> SET LIB=\CC
C:\> SET INCLUDE=\CC\INCLUDE
C:\> SET LINKER=LINK

Compile one of the example files;

C:\CC> MC EXAMPLE.C
Microsoft (R) Overlay Linker  Version 3.51
Copyright (C) Microsoft Corp 1983, 1984, 1985, 1986.  All
rights reserved.

C:\CC>

This will compile and link `example.c', creating
example.obj, example.exe.



Compiler switches;

    -c    compile only (generate .obj, don't link)
    -j    signed char constants
    -n    noisy compile
    -p    disable autoprototyping
    -r    set error limit
    -s    generate source listing (.src) after
preprocessing
    -t    allow trigraphs
    -w    no warnings

    -Dname    define macro
    -Uname    undefine macro
    -Iname    add include directory


Only one program file may be compiled at one time. To
compile and link together several programs, compile them
separately with `-c' option, then link them with ccl.lib.


If the compiler finds an error (in preprocessing, parsing
or other compilation error, eg an undeclared variable) it
will print the statement where it occurred and stop if
the error limit has been reached. Functions should be
declared before being called, although this is not
mandatory. If they are not, then auto-prototyping will
generate a prototype for a new function returning int. A
function definition automatically declares the function
if it has not been declared or auto-prototyped earlier.



EXAMPLE PROGRAMS

A few example programs are included to illustrate Miracle
C facilities.

example.c    hanoi.c
cat.c        sieve.c
maze.c    maze
slr.c    grammar.c



example.c    shows most of CC's features; structs/unions;
initializers for structs and arrays;
        typedefs; function prototyping; functions with
local variables, and scoping;
        data types; signed and unsigned int, char and
long variables, floating point;
        use of some library functions for file handling

cat.c        reverse words in a sentence, eg `I am
here' to `here am I'

hanoi.c        non-recursive towers of hanoi
        (originally from a Programmer's Challenge in
Computer Shopper magazine!!)
        gives the sequence of moves to move all discs
from first to third peg via second

sieve.c        Eratosthenes sieve to find prime numbers
by eliminating composites
        developed from a BYTE C benchmark program

maze.c        maze solver, finds shortest path through
maze from A to B
maze        eg.    C:\> MAZE<MAZE
        uses an algorithm from graph theory to find
shortest path

slr.c        simple parser generator for SLR grammar
        given a grammar file, generates a recognizer
program to parse the SLR grammar
grammar    grammar file for slr.c


LANGUAGE FEATURES

This is a summary of the C language as implemented by the
Miracle C compiler.

For a tutorial on the C language, read `The C Programming
Language' by Kernighan and Ritchie. A comprehensive
reference to the language is the book `C: A Reference
Manual' by Harbison and Steele, published by Prentice-
Hall, which describes both traiditional and the new ANSI
C syntax and semantics. Miracle C implements the
traditional C language and some of the ANSI extensions.

Lexical Elements

Tokens
The fundamental lexical elements of the language are
operators, separators, identifiers, reserved-words and
constants.

A C source program consists of tokens separated by
whitespace. Whitespace is defined as chars 9-13 and 32.
Tokens can be operators, separators, identifiers,
reserved-words or constants.

1.    Operators
The following operators are legal in C.

    ! % ^ & * - + = ~ | < > ' ? += -= *= /= %= <<= >>=
&= ^= |=
        -> ++ -- << >> <= >= == != && ||

2.    Separators
Whitespace characters 9-13, and space character 32 are
separators.
( ) [ ] { } , ; :

3.    Identifiers
A sequence of any number of letters/digits/underscores
starting with a letter or underscore character.
Identifiers are case-sensitive so name, Name and NAME are
different, but external symbols (such as function names)
are not case-sensitive.

4.    Reserved words
auto break case char default do else enum extern for goto
if int long register return short signed sizeof static
struct switch typedef union unsigned void while

5.    Constamts
A C constanr can be an integer, character or string, or
floating point constant.

integer
An integer can be represented as a decimal, octal (base
8) or hexadecimal (base 16) constant.

*    decimal (digits)
*    octal 0(digits), eg 0243
*    hex '0x' (or 0X) (hex-digits 0-9 a-f A-F), eg 0x4afb

A numeric constant can be unsigned (suffixed by U, eg
56U), long (eg 128374L) or floating point.
Floating point constants have syntax  aaa.bbbEeee    where
    aaa.bbb = mantissa
                            eee = exponent
(signed, optional



character
A character is 'char' or '\esc-char'
    where esc-char= nnn octal literal
            xnn hex literal

            a alert        b backspace
            f form feed    n newline
            t tab        r carriage return
            v vertical tab    ' single quote
            ? question mark    " double quote

A character constant may contain more than one byte, on
which case bytes are packed into a word,
for example    int a='xy';

string
A string is "string" where the string has printable
characters or \escaped-characters.
Constant strings are null-terminated, eg
sizeof("hello")=6





Preprocessor

The preprocessor performs macro substitution, file
inclusion and conditional compilation on the source
program. Use the `-s' compiler option to see the program
text after preprocessing.

The preprocessor allows a line to be continued by ending
it with a `\' character. Tokens and strings can be split
across lines.

Preprocessor directives are lines starting with `#'. A
line with only '#' is a null directive and is ignored by
the preprocessor.


Macro substitution
The #define preprocessor directive defines a macro,
optional parameter list and associated substitution
string. A macro can have no parameter list, eg

    #define WORD_SIZE 16

then every occurrence of WORD_SIZE in the program text is
replaced with `16'.
The general form of a macro definition allows zero or
more parameters;

    #define <name>(parameters) <replacement text>

    #define afunc() otherfunc()
    #define times(x,y) ((x)*(y))

every call to afunc() is replaced with a call to
otherfunc(); when `times' is used, actual arguments are
substituted for macro parameters in the replacement text,
eg


    times(4,times(5,6))
gives
    ((4)*(((5)*(6))))

The number of arguments when the macro is used must match
the number of parameters when it is declared.

A macro definition may be split across more than one line
by line continuation with \

    #define plus(x,y) \
        ((x) + (y))

After macro substitution, the line is scanned again so
macros created by the expansion can be recognized and
expanded.


The following macros are predefined by the preprocessor;

MIRACLE    defined as 1
        use for code specific to Miracle C compiler

MSDOS        defined as 1
        use for code specific to MS-DOS

__FILE__    current source file

__LINE__    line in current source file

__DATE__    today's date, returned as "Mmm dd yyyy"

__TIME__    time of compilation, returned as "hh:mm:ss"


Redefinition of macros (benign or otherwise) is allowed.
No warning or error is given if redefinition occurs.

A macro definition can be cleared using `#undef'
directive;

    #undef times


File inclusion
The `#include' directive allows C source files to be
included in the program text. When the end of the
included file is reached, compilation continues from the
line after the `#include' directive. Include files may be
nested; but they should including themselves, directly or
indirectly, causes the compiler to crash. Preprocessor
include files usually have a .h suffix (header files).
There are two forms of #include directive;

    #include "filename"

includes a file in the current directory,

    #include <filename>

includes a file from the system include directory, which
is given by the INCLUDE environment variable. If INCLUDE
is not set, the system include directory defaults to
`\cc\include'.

The inclusion-file can be specified by a macro;

    #define MYINCLUDES "my.h"
    #include MYINCLUDES

A complete pathname can be given in the first form of
include;

    #include "\cc\graphics\graf.h"

Conditional Compilation
The preprocessor allows compilation of sections of code
to be conditional on the values of expressions, using the
directives `#if' `#ifdef' `#ifndef' `#else' `#endif'.
Lines after an unsuccessful conditional compilation
directive are discarded until the next conditional
compilation directive.

A conditionally compiled section of code starts with #if
#ifdef or #ifndef and ends with a matching #endif. It may
contain #else or #elif directives, and other (nested)
conditionally compiled code sections.


`#if expr'
If the C expression `expr' evaluates to 1, lines are
processed until a matching else, elif or endif is found.
If it evaluates to 0, following lines of code are
discarded until a matching else, elif or endif is found.
The expression `expr' must be a constant recognisable to
the preprocessor, containing macro, character and number
constant values only.


`#ifdef name'  `#ifndef name'
If the macro `name' is defined (ifdef) or undefined
(ifndef), lines are processed until a matching else, elif
or endif is found. Otherwise, following lines of code are
discarded until a matching else, elif or endif is found.

`#else'
The else directive follows an if, ifdef or ifndef, or can
follow #elif directives. Lines of code following #else
are processed only if preceeding lines were not
processed.

`#elif'
This is a switch/case construct for conditional
compilation;

    #if expr1
    ...
    #elif expr2
    ...
    #elif expr3
    (etc)
    #else
    ...
    #endif

`#endif'
terminates a conditionally compiled code section.


Other Features
The #error directive aborts compilation with an error
message;

    #ifdef x_once
    #error Illegal include recursion
    #endif
    #define x_once

detects a program's attempt to include itself; implement
"once-only" inclusion of header files similarly.


Stringification converts a token into a string, and is
useful when debugging a program;

    #define fatal(tok1,tok2) printf("bad tokens:
%s;%s;",#tok1,#tok2)

Concatenation of adjacent strings is supported by Miracle
C compiler,
so
    #define fatal(tok1,tok2) printf("bad tokens: " #tok1
";" #tok2)
is allowed.


Token merging using the ## operator creates a single
token from two or more
tokens in a macro definition;

    #define line(i) line ## i

then    line(1) == line(2)
becomes    line1 == line2




Functions

Miracle C supports a both the traditional syntax for
function definition, and a syntax similar to ANSI C for
function prototyping. Functions can be declared and
prototyped before use. The traditional way of introducing
functions, eg.

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

is supported. Traditionally, functions weren't declared
before use or definition; CC allows functions to be
declared and prototyped before use, zero times or exactly
once, or a parse error results. Note that 'parse errors'
occur when the current symbol is not one of the expected
legal symbols, hence a function redeclaration may
generate a parse error.

CC's function declaration syntax is similar to ANSI, eg

    void afunc(int one, char *b);

but the ANSI syntax

    void afunc(int, char *);

is not supported (yet). The number and type of
parameters, and return value, in a function definition
must match exactly that of the function declaration.
Miracle CC supports declaration of functions with a
variable number of
parameters, eg

    int printf(char *fmt, ...);

but their definition is not supported (yet).

Miracle C has the concept of `function types' which are

    type1 x .. x typen x varargs -> typer

for a function taking n parameters of type (type1, ...,
typen) and returning a result of type typer, with a
variable number of arguments if varargs set.

A pointer to a function is assigned a function type,
which should match the type of a function assigned to it;
for example,

    void (*fptr)();
    int printf(char *fmt, ...);

    (fptr=&printf,*fptr)("hello");

will fail with the error message

158: wrong # args in function call

'(fptr=&printf,*fptr)("hello")'


Functions may return signed or unsigned int, char or long
values, but not struct or union. They may return pointers
to any item (including struct), or a user defined type,
as long as that type isn't a struct. Nor can a function
return an array, or another function.

Parameters in a function call are pushed on the stack
using normal C linkage conventions, ie right-to-left, to
allow for functions with a variable number of parameters
(eg printf, first argument specifies number and type of
subsequent). Parameters should be word entities, ie int
char and pointer type.

Functions may be declared as extern, static or register,
but these classes are ignored by the compiler. Miracle C
marks functions defined in the program text as `internal'
and others as `external' and generates object
accordingly. Static functions (visible only within a
program) are not supported (yet!).

Miracle C needs functions with no parameters to be
declared by

    int afunc();

It does not follow the ANSI convention of declaring such
as function by

    int afunc(void);

nor does it follow the traditional C convention of
declaring a function's return type, but omitting a
declaration of parameters, using the above syntax.

Parameters in a definition count as local variables in
the highest level block in the function body, following
the ANSI definition.

Storage classes are not allowed for parameters in a
definition. Functions with return type `void' must not
return a value.

A function declared to have return type `int' need not
specify return type in the function definition, so we
allow

    int main();
    ....
    main() { ... }

Function prototypes may not be nested;

   void (*signal(int sig, void (*func)(int sig)))(int
sig);

is illegal, but can circumvent this by

   typedef void sig_handler(int sig);
   sig_handler *signal(int sig,sig_handler *func);


Autoprototyping of functions is allowed. If a function
call is introduced for a function which has not been
declared, a declaration is automatically generated for
the function. The automatically generated prototype will
use the types of parameters which are given to the
function on call, and will assume a function return type
of int. If the desired function type is different to that
which will be implicitly generated from the function call
then an explicit declaration should be made before the
function is called. Function autoprototyping may be
disabled by a compiler flag.



Types

Miracle C supports void, scalars (pointers, signed and
unsigned char int long), enumeration types, floating
point types, pointers to any object, struct/union and
multi-dimensional array types. It also has `function
types' (see the section on functions).

As a small-model 8086 compiler, CC supports 16-bit ints
and pointers, 8 bit char values (expanded to 16 bits when
passed as parameters on the stack), and 32 bit longs. The
type `short' is a synonym for `int'. An object declared
by

    signed avar;

is a signed integer. Floating point numbers are not
implemented. Long integers are not completely
implemented; for example, adding a long to an int is not
allowed, but adding two longs is (so cast the int to long
before adding); and long values should not be passed as
function arguments.

Miracle C maintains a type value for each expression,
computed from the types of its components; a data size is
associated with each type value.Traditional C casts are
allowed, but type checking of assignments etc is not
strict.

Array subscripts, and adding an int to a pointer, is
scaled up according to the data size of the type being
pointed to, eg if intptr is int * then intptr+1 (or
intptr[1]) will point to intptr plus 2 in memory.

Arrays of any type except void can be declared and can be
multi-dimensional. Void variables are not allowed.

Enumerations are introduced by an `enum' declaration,
such as

    enum colour { red, green, blue } mycolour;
    enum colour anothercolour.

The tag (here `colour') is optional, and can be used in a
later declaration. Enumerations must start at zero, the
traditional "red=2" syntax is not supported. An enum
variable is int. The enum namespace is separate from
others, hence
    enum one { one, two } number;

is allowed.


Record (Struct/Union)

Structure (record) type is a collection of named
components;

    struct structag
        {
        int x, y[3];
        char z;
        struct structag *sptr, *tptr;
        }
        sarray[10], *sptr;

    struct structag another, *anotherptrs[5];

Structure tag `structag' identifies this structure type
for other declarations. The struct has components x,y,z
and two pointers to other `structag' structs (so we've
declared a tree structure type). Structure declarations
cannot be nested (that would be infinitely silly).
Structure component names live in a separate namespace
for each struct/union type, hence we can introduce
variables with the same name. Struct components occupy
successive memory locations, and the size of a struct (as
given by sizeof) is the sum of the sizes of it's
components.

Struct components are referred to using . and ->
operators. In the example above we declare sarray an
array of 10 `structag' structs and allocate space for it
(either static or on the stack). Direct reference by
sarray[i].y[0], indirect reference via pointer to struct
by sptr->z, sptr->tptr->y[i].

A union is declared using the same syntax as struct, but
contains only one of its members at any one time (so the
size of a union is the max of the size of it's
components, and all items are at offset zero in the
union).

Nested structs/unions are allowed. Bit fields in structs
aren't implemented.

Struct bitfields are permitted. A single bitfield must
not exceed the capacity of a machine word (16 bits). All
the normal arithmetic operations and assignment are
permitted on bitfields, as are struct bitfield
initializers.

Typedef

User defined type synonyms are introduced by the
`typedef' statement;

    typedef int *ptr, (*func)(), afun();
    ptr wordptr;
    afun main;
    func funcptr=main;

    ptr    `ptr to int'
    func    `ptr to function: void->int'
    afun    `function: void->int'

Typedef doesn't create a new type, only type synonyms, so
type compatibility/comparison works. Typedef for function
can include function prototypes;

    typedef int funci(char *x);
    funci funky;

A typedef name may be global, or local to a function. The
ANSI standard allows typedefs to be redeclared in a
block, but CC doesn't (yet).

Type Compatibility

Two expressions are assignment compatible  t1=t2  if t1
is an lvalue, and;

    - t1 is (u)long, t2 is (u)int/char, extended to 32
bits
    - t1 is (u)int/char, t2 is (u)long, truncated to 16
bits
    - t1 and t2 are both (u)long, 32 bit assignment
    - t1 is (u)char, 8 bit assignment

    else 16 bit assignment (of int, pointer etc)

Bitfields may be signed or unsigned integer quantities
and have the same type compatibility rules as integers.

Some operators eg  || && ^ | & * / %  require (u)int
operands.
Pointers may be subtracted (t1-t2 yields a pointer of
type t1) but not added (addition of pointer is
meaningless).

Array types count as ptrs, depth of ptr=dimensionality of
array.
Struct/unions types are compatible if they have the same
struct tag.





Declarations

Variables, functions and user defined data types are
introduced by declaration statements. A declarator gives
identifier name and type;

Scalar        int x
Floating point    double x;
Pointer        int *x; char *y[];  (y is pointer to
array, same as char **y;)
Array        int (*x)[4];        (x is pointer to array
of 4 ints)
Function    int x(), y(int a,char *b), (*x[])(int a);

To parse a declaration, start from name and work out
according to precedence rules;

    int *a[10]       a is array of 10 ptrs to int
    int (*x[])(int a)  x is array of ptrs to functions:
int->int


Global variables are visible throughout the program from
the point of declaration, unless they are hidden by a
local declaration with the same name. Local variables are
visible throughout the block in which they are defined,
unless they are hidden by a declaration at an inner level
with the same name. Globals are extern by default.

Static variables (globals and local statics) have storage
allocated at compile time in static data area to hold a
possible initializer. Local variables are allocated on
the stack at runtime and are local to a block, or are
function parameters.

Parameters to a function are considered as being declared
at the topmost local level in the function, so a local
declaration using a parameter name is an error. Local
objects may not be declared more than once.

All floating point types (float, double and long double)
are treated internally as 8-byte double quantities.
Normal floating point arithmetic is allowed on these
quantities. No support for numeric coprocessing is
included in this version.

Initializers are allowed for both global and local
objects and follow traditional syntax. Global
initializers are evaluated at compile-time, a constant is
stored in the static data segment. Therefore, expressions
in global initializers can only contain things which can
be evaluated at compile-time, such as constants and
address of objects.

Local initializers are evaluated when a function is
called, so expressions may (even) contain function calls.

Multi-dimensional arrays, structs/unions, arrays of
structs and initializers for them are supported using
traditional C syntax.

A struct tag can be declared before any variables are;

    struct S { int a, b; };
    struct S fred;

A struct can be declared without tag or variables;

    struct { int a,b; };

is allowed but pointless.

Also  static struct S { int a,b; }; is allowed but
`static' is meaningless.


A global variable may be declared more than once, but all
declarations must agree on type. A local variable may
only be declared once. Global arrays must have the same
dimensions when redeclared, but the first dimension need
not be specified;

    char uu[5][4][3]; char uu[][4][3];

Only one definition may exist for a variable, so a global
may have only one declaration with an initializer.
Redeclaration of functions is not supported.

Type definitions, structs/unions and enumerated types are
supported; see the section on `types'.

Global variables are allocated in a static data area.
Uninitialized globals are set to zero; uninitialized
parts of partly initialized globals are zeroed.
Initialized globals give PUBDEF records for the linker,
uninitialized globals give COMDEF records.

Arrays are allocated at compile-time (static) or run-time
(auto), hence  static char p1[]="hello"  allocated 6
bytes and copies "hello" into it, but pointer
initialization is to run-time objects, hence  char
*p2="hello" allocates 2 bytes for p2 and points it to a
static string item.

Statement labels are local to a function body, and the
target of goto statements

    here:
        ...
        goto here;

Forward references are allowed if;

    - statement label may be used by goto before it is
declared

    - an identifier should be visible immediately after
declaration,
      eg int fred=sizeof(fred)
      but this is not yet implemented

    - struct can contain pointer to instance of itself

    - function declaration and use before definition



Overloading of identifiers permits an identifier to have
different meanings depending on context;

    - macro names are defined and used by the
preprocessor

    - struct tag names have a separate name space

    - enum tag names have a separate name space

    - typedef, enum and label names are checked before
variable names.
      a compile error results if a variable is declared
with the same
      name as a typedef or enum name, or goto-label

    - struct component names are specific to a
struct/union type,
      so two structs can have components of the same
name



External names must be defined at top-level (global
variables). Extern declarations inside functions are not
supported and are treated as declarations of internal
variables. Global variables are defined to the linker and
accessible to other programs.

The storage classes auto and register are ignored by the
compiler. Static variables local to a function are
allocated in the static data area, and should have
constant initializers.




Initializers
The compiler allows initialization of scalars, strings,
struct/unions and arrays. An initializer sets the initial
value of a variable, at compile time for static objects
(globals or local statics) or run time for automatic
variables. If no initializer exists for a global
variable, it's set to zero; if none exists for a local,
it's initial value is unpredictable.

The traditional C syntax for initializers is supported;

    int x=4;

    struct { int a; char *s; int b; } icky = { 1,
"astr", 2 };

    enum { red, blue } colour = blue;

Union initializer is for the first component of the
union. Structs and multi-dimensional arrays are
initialized recursively;

int m1[2][3] = { { 1, 2, 3 }, { 4, 5, 6 } };

The `shape' of an initializer (brace structure) must
match that of the object being initialized. If there
aren't enough initializing items for an array or struct
initializer, the rest of the object is zeroed. If there
are too many, a compile time error results.

If the outermost dimension of an array is unspecified,
it's taken from the initializer;

    char a[] = { 'a', 'b', 'c', '\0' }, *b="hello";

Braces can be dropped in the initializer;

    int a[2][3]={1,2,3,4,5,6};

the number of items in the initializer must not exceed
the declared object.

Static variable initializer expressions contain only
objects which can be evaluated at compile-time, ie
constants and addresses of static objects. The address of
a global variable cannot be found if it is declared but
not defined;

    int a, *b=&a;

won't compile, but

    int a=2, *b=&a;

is allowed.

Local variable initializer expressions are evaluated at
runtime, when a function is called. They can contain any
expression (even function calls). If goto jumps to a
label in a block, initializers for that block don't run.

Initializers are permitted for floating point variables,
and bitfields in struct (record) types, using the
standard C syntax.



Expressions

An expression consists of operators acting on other
expressions, or base values (variables or constants). An
expression is either an lvalue or an rvalue; an lvalue
refers to an object in memory, eg a variable; an rvalue
is a non-lvalue.

Lvalues can be `variable'  e[k]  lvalue.name  e->name  *e
they are used by  &  ++  --  assignment-operators


Expressions are formed from operators, in precedence
order:

,    sequential evaluation, yields second operand

=   +=    -=  *=     /=   %=
&=  |=    ^=  >>=  <<=  assignment

    assign    (u)long = (u)(int|char)
        (u)long = (u)long
        (u)(int|char) = (u)long
        word/byte lvalue = word/byte rvalue

?:    conditional   exp1 ? exp2 : exp3
    depending on value of exp1, yields exp2 or exp3
    type of exp1 must be int
    types of exp2 and exp3 must match, and must be byte
or word

||    logical or    exp1 || exp2    only evaluate exp2 if
exp1 false

&&    logical and    exp1 || exp2    only evaluate exp2 if
exp1 true

|    bit or
^    bit xor
&    bit and
    bit or, xor, and take (u)int operands and yield
(u)int result

== !=    compare, signed or unsigned
< >    signed if at least one operand is signed, both are
int or char
<= >=    unsigned if both operands are unsigned int or
char, or pointers


<< >>    shift, arithmetic for signed, logical for
unsigned

+ -    add sub
    (u)(char|int), (u)(char|int)
    ptr, (u)(char|int)    scale up by size of object
pointed to
    (u)long, (u)long
    can subtract two pointers giving an integer

* / %    mul div rem
    take (u)int operands, yield (u)int result

(type)    cast
    cannot cast to/from structs/voids
    cannot cast between chr and ptr, but can between int
and ptr
    if casting long->int then lose high word, int->long
high word zero

*    indirection

&    address of

-    unary minus

!    logical not

~    bit not

sizeof    sizeof(typename)        size of type
    sizeof("string")        size of constant string + 1
    sizeof(array-expr)    size of array in bytes
    sizeof(expr)            sizeof type of expr

++ --    post/pre decr/incr
    if pointer, scaled up by size of object pointed to

->    indirect selection by pointer (struct/union member
or bitfield)

.    direct selection (struct/union member or bitfield)

f(..)    function call, where f is a function designator
    f has function type and identifies a function

(expr)    brackets

a[k]    array subscript; type of k = (u)(int|char)
    the result of an array subscript is an lvalue only
if a is a pointer, or we have reached the last
    array dimension

    for example, if  int a[3][2];  then  a[1]=4;  is
meaningless and is flagged as an error
    but this means that

        int a[2][3], **x;
        x=&a[1];

    will not compile. The ANSI solution (`modifiable
lvalues') is not implemented.

number    constant

string    constant

variable global, local, lstatic

Initializer constant expressions are arithmetic constant
expressions and address constant expressions (not fully
implemented in CC). These can have normal operators &
casts, which are evaluated at compile-time.



Statements

All traditional C statements are implemented, except for
`continue'.
A statement can be one of the following;

expr    expression; (discarded)

null    null statement (actually a null expression)

label    label: stmt;
    which can be a goto-label, case-label, or default-
label in switch

goto    goto name;
    where `name' is a goto-label defined somewhere in
function

block    { decl-list; stmt; ... stmt; }
    A block starts with zero or more declarations, and
contains zero or more statements. Blocks
     may be nested. Names declared within the block hide
declarations of the same name outside
    the block, and are visible throughout the block
unless hidden by a declaration at an inner
    level.

    Goto a label inside a block jumps past local
variable allocation and initialization code; but
    the locals are de-allocated at end of block anyway,
so don't jump into a block!

if    if (expr) stmt
    if (expr) stmt1 else stmt2    NB else belongs to
nearest if

    if `expr' evaluates to non-zero, do stmt1 (else do
stmt2)
    `else' belongs to the nearest `if'

while    while (expr) stmt
    continue executing `stmt' while `expr' evaluates to
non-zero

do    do stmt while(expr)
    do `stmt' at least once, then while `expr' evaluates
to non-zero


for    for(expr1; expr2; expr3) stmt        each of exp1,2,3
optional
    expr1= evaluated once at start of loop
    expr2= continuation condition, tested before stmt
executed
    expr3= iteration expression, evaluated after
statement

    if expr2 omitted then it defaults to true
    eg.  for(;;) is an infinite loop



switch    switch(expr)
       {
       case n1: ...;
       case n2: ...;
         ...
       default: ...;
       }

    case labels must be numbers or char literals;
    case labels should not be duplicated, at most one
default exists;
    when a case or default is chosen, execution
continues until
    break or end of block

break    terminate smallest enclosing  while. do, for,
switch

continue continue smallest enclosing  while. do, for

return    return opt-expr        return from function
with optional value
    void functions must not return a value



ASSEMBLER PROGRAMMING INTERFACE

Miracle C functions can call, and be called by, assembler
routines.

Function call is by pushing arguments onto the stack in
right to left order,
and call (pushes ip on stack). The called function pushes
bp and allocate
stack space for local variables. Function return is the
reverse; deallocate
local variables, pop bp, return; caller pops arguments.

        +-------+
        | arg n |
        |   .   |
        |   .   |
        | arg 1 |
        |  ip   |
        |  bp   |
        | local |
        |   .   |
        |   .   |
        | local |
        +-------+

At entry to a C function, SP points to the return value
of IP on the stack.
To access word arguments;

        push    bp
        mov    bp,sp
        mov    AX,[bp+2]    ; first argument
        mov    BX,[bp+4]    ; second argument
        ...
        pop    bp
        mov    ax,retvalue    ; return value
        ret



FUNCTION LIBRARY

Startup code

The startup code initializes segment registers, sets
argc/argv parameters
to zero, and calls function `main'. If `main' returns to
the startup routine,
an exit handler is called which closes files and
terminates.



Include header files

The following header files are supplied with the compiler
in the 'include' subdirectory.

ctype.h        Prototypes for alphanumeric test and
conversion functions.
io.h        Prototypes for elementary file functions.
stdio.h        Prototypes for higher level file handling
and input/output functions.
string.h        Prototypes for memory and string handling
functions.
system.h    Prototypes for memory and other functions.



Library Functions

The Miracle C library contains functions for string
handling, file operations, input/output formatting,
memory allocation and other functions.



abs, labs

    #include <system.h>

    int abs(int i)
    long labs(long i)


    Produces the absolute (positive or zero) value of
its argument.
    abs takes an int argument returning an int, labs
takes a long argument and returns a long.



calloc

    #include <system.h>

    void *calloc(int nitems, int itemsize)

    Allocates a block of memory that ia nitems *
itemsize bytes in size from the heap. The
    initial contents of the block is zeroed.
    If not enough memory is available to satisfy the
request a null pointer is returned. Since the
    compiler uses the small memory model, memory
requests should be made accordingly.
    Allocated memory should be freed explicitly when it
is no longer required.


    Example

        #include <system.h>
        #include <stdio.h>

        void main()
        {
            char **buffer;
            int nitems=100;

            buffer = calloc(nitems,sizeof(char *));    /*
allocate 50 pointers to char */
            if(buffer==NULL)
                {
                    printf("out of memory\n");
                    exit(1);
                }
            printf("calloc allocated %d items of %d at
: %x\n",nitems,sizeof(char *),buffer);
            free(buffer);
            return;
        }



close

    #include <io.h>

    int close(int fd)

    Close the file given by file descriptor handle `fd'.
freesing the file descriptor for use by
    another file.
    close does not write an eof character 26.
    Returns 0 if successful, otherwise -1 if failed.


    Example
        #include <io.h>
        #include <stdio.h>
        #include <system.h>

        void main()
        {
        int fd;
            if((fd = open("tfile",O_RDONLY))<0)
                {
                    printf("failed to open tfile\n");
                    exit(1);
                }
            printf("close code %d\n",close(fd));
            return;
        }



create

    #include <io.h>

    int create(char *fname)

    Create a file with name `fname'.
    If successful, returns a file descriptor for the
newly created file. Otherwise returns -1 if
    unsuccessful.


    Example
        #include <io.h>
        #include <stdio.h>

        void main()
        {
            int n;
            n = create ("tfile");
            if (n == -1) {
                printf("Cannot create tfile\n");
            }
            return;
        }



exit

    #include <system.h>

    void exit(int code)

    Closes files, flushes all output buffers and
terminates with return code `code'.

    Example
        #include <io.h>
        #include <stdio.h>
        #include <system.h>

        void main()
        {
            int n;
            n = create ("tfile");
            if (n == -1) {
                printf("Cannot create tfile\n");
                exit(1);
            }
            exit(0);
        }



fclose

    #include <stdio.h>

    int fclose(FILE *fp)

    Close an open file, and flush output buffer for the
file. Returns 0 if successful, EOF if not.

    Example
        #include <io.h>
        #include <stdio.h>

        void main()
        {
            FILE *fp;
            if((fp = fopen("tfile","r"))==NULL) {
                printf("failed to open file tfile\n");
                return;
            }
            else {
                    fclose(fp);
                    printf("closed file tfile\n");
                }
            return;
        }

feof

    #include <stdio.h>

    int feof(FILE *fp)

    Tests end of file condition for file fp. Returns
non-zero if end of file.
    After an EOF condition no further reads should be
performed.

    Example
        #include <io.h>
        #include <stdio.h>

        void main()
        {
            FILE *fp;
            char buffer[100];

            fp = fopen ("tfile", "r");

                    while ( !feof(fp) )
            fgets(buffer, 100, fp);

            return;
        }



fflush

    #include <stdio.h>

    int fflush(FILE *fp)

    Flush buffer for an output file. If the file is open
for writing the output buffer is wriiten to
    disk. If it is open for reading the buffer     is
cleared and another read operation is forced
    to occur.

    Returns 0 is operation successful, otherwise EOF if
an error occurred.

    Example
        #include <stdio.h>
        #include <system.h>

        void main()
        {
        FILE *fp;

            if((fp = fopen("tfile","w"))==NULL)
                 exit(1);

            fflush(fp);
        }



fgetc

    #include <stdio.h>

    int fgetc(FILE *fp)

    Reads and returns a character from a file. Returns
next character or EOF.


    Example
        #include <stdio.h>

        void main()
        {
            FILE *fp;

            fp = fopen ("tfile", "r");

             while ( !feof(fp) )
            putchar(fgetc(fp));

            return;
        }



fgets

    #include <stdio.h>

    char *fgets(char *buf, int n, FILE *fp)

    Get a string (maximum n characters) from file `fp'
to buffer `buf'.
    Returns NULL if an error occurred or no characters
were read,
    otherwise returns the (null-terminated) string.

    Example
        #include <io.h>
        #include <stdio.h>

        void main()
        {
            FILE *fp;
            char buffer[100];

            fp = fopen ("tfile", "r");

                    while ( !feof(fp) )
            fgets(buffer, 100, fp);

            return;
        }



fopen

    #include <stdio.h>

    FILE *fopen(char *name, char *mode)

    Open a file with filename `name' returning a pointer
to FILE.
    The following modes are allowed;
        `r'    open file for reading only
        `w'    open file for writing
        `a'    open file for append; position at end of
file

        `r+'    open file for reading and writing
        `a+' `w+' create new file for reading and
writing


    Example
        #include <io.h>
        #include <stdio.h>

        void main()
        {
            FILE *fp;
            if((fp = fopen("tfile","r"))==NULL) {
                printf("failed to open file tfile\n");
                return;
            }
            else {
                    fclose(fp);
                    printf("closed file tfile\n");
                }
            return;
        }



fprintf

    #include <stdio.h>

    int fprintf(FILE *fp, char *fmt, ...)

    Print formatted values to file. Arguments follow the
format string and are interpreted
    according to the format string.
    fprintf writes its characters to the file stream fp.

    The format string is a sequence of characters with
embedded conversion commands.
    Characters at are not part of the conversion
    command are output. Conversion commands
    are the same as for the printf function.

    fprintf returns the number of characters written.

    Example
        #include <io.h>
        #include <stdio.h>

        void main()
        {
            FILE *fp;
            char *msg = "number formats are: ";
            int n = 42;
            fp=fopen("con","w");

            fprintf(fp,"%sx: 0%x d: %d o:
%o\n",msg,n,n,n,n);
            fclose(fp);
            return;
        }



fputc

    #include <stdio.h>

    int fputc(int c, FILE *fp)

    Write a character c to file fp. Returns the
character written.

    Example
        #include <io.h>
        #include <stdio.h>

        void main()
        {
            FILE *fp;
            char *buffer = "this text is written to
console";
            fp=fopen("con","w");

            while(*buffer)
                fputc(*buffer++, fp);
            fclose(fp);
            return;
        }



fputs

    #include <stdio.h>

    int fputs(char *str, FILE *fp)

    Write a string str to file stream fp.
    Returns non-negative if successful, EOF if error
occurred.

    Example
        #include <io.h>
        #include <stdio.h>

        void main()
        {
            FILE *fp;
            char *buffer = "this text is written to
console";
            fp=fopen("con","w");
            fputs(buffer,fp);
            fclose(fp);
            return;
        }


fread

    #include <stdio.h>

    int fread(void *buf, int sizelem, int n, FILE *fp);

    Read `n' items, each of size `sizelem' from file
`fp' into buffer `buf'.
    Returns the number of complete elements read.

    Example
        #include <io.h>
        #include <stdio.h>
        #include <system.h>

        void main()
        {
            FILE *fp;
            char *dest;
            int n;

            if((fp = fopen("tfile","r")) == NULL)
return;
            dest = calloc(81,1);
            n = fread(dest,1,80,fp);
            printf("read %d bytes\n%s",n,dest);
            return;
        }



free

    #include <system.h>

    void free(void *ptr)

    Free memory block pointed to by `ptr'. The memory
block described by ptr must have been
    allocated by calloc, malloc or realloc.

    Example
        #include <stdio.h>
        #include <system.h>

        void main()
        {
          char *p;
          if((p = malloc(100)) == NULL) {
              printf("out of memory\n");
              return; }
          free(p);
          return;
          }



fscanf

    #include <stdio.h>

    int fscanf(FILE *fp, char *format,...);

    Read characters from file `fp' and convert according
to format string `format', storing via
    argument pointers which follow `format'.
    See the description of`scanf' for input format
specification.

    Returns the number of arguments read from input.

    Example
        #include <stdio.h>
        #include <system.h>

        void main()
        {
        FILE *fp;
        char fst[10], sec[20];
        int n;

        fp=fopen("con","r");
        fscanf(fp, "%s %s %d",fst,sec,&n);
        printf("You typed %s %s %d\n",fst,sec,n);
        return;
        }



fwrite

    #include <stdio.h>

    int fwrite(void *buffer,int sizelem, int n,FILE
*fp);

    Write `n' items, each of size `sizelem' to file `fp'
from
    buffer `buf'.

    Returns the number of complete elements written.



getc

    #include <stdio.h>

    int getc(char *fp)

    Get a single character from file `fp'. Returns the
character, or EOF if input error.

    Example

        #include <stdio.h>

        void main()
        {
            int n;
            FILE *fp;

            fp = fopen ("tfile", "r");

             while ( !feof(fp) )
            putchar(getc(fp));

            return;
        }



getchar

    #include <stdio.h>

    int getchar()

    Get a single character from stdin. Returns the
character, or EOF if input error.

    Example

        #include <stdio.h>

        void main()
        {
            int n;
            FILE *fp;

             while ((n=getchar())!=EOF)
            putchar(n);

            return;
        }



gets

    #include <stdio.h>

    char *gets(char *buf)

    Get string from stdin into buffer `buf'. Reads
characters from file until newline or end-of-
    file. The string written to `buf' is null-
terminated.

    If a string was read into the buffer it's returned,
else returns NULL.

    Example

        #include <stdio.h>

        void main()
        {
            char buf[80];
            gets(buf); puts(buf);
            return;
        }



is-ctype

    #include <ctype.h>

    int isxx(char c)

    Test a character to see if it's of a specified type.
    If it is, a non-zero value is returned; if not, zero
is returned.


        isalnum        alphanumeric, letter or digit
        isalpha        alpha, letter
        isascii        ascii, 0-127
        iscntrl        control character
        isdigit        digit
        isgraph        graphic, printable
        islower        lowercase letter
        isprint        printable
        ispunct        punctuation
        isspace        space character
        isupper        uppercase letter
        isxdigit    hex digit



malloc

    #include <system.h>

    void *malloc(int n)

    Allocate buffer of n bytes from the heap,
    Returns address of buffer, or NULL if no memory
available.

    Example
        #include <stdio.h>
        #include <system.h>

        void main()
        {
          char *p;
          if((p = malloc(100)) == NULL) {
              printf("out of memory\n");
              return; }
          free(p);
          return;
          }



memchr

    #include <string.h>

    void *memchr(void *buf, int c, int count);

    Search buffer `buf' for a character `c'. The search
stops when a character `c' is found, or
    after `count' bytes.



memcmp

    #include <string.h>

    int memcmp(void *buf1, void *buf2, int n);

    Compare data in buffers `buf1' and `buf2', of size
`n'.

    Returns        = 0    buf1 and buf2 hold identical
data
            < 0    first differing byte in buf1 < buf2
            > 0    first differing byte in buf1 > buf2



memcpy, memmove

    #include <string.h>

    void *memcpy(void *buf1, void *buf2, int count);
    void *memmove(void *buf1, void *buf2, int count);

    Copy `count' bytes from buffer `buf2' to buffer
`buf1'.
    Returns `buf1'.



memset

    #include <string.h>

    void *memset(void *buf, int val, int n);

    Sets contents of buffer `buf' of size `n' to value
`val'.
    Returns buffer `buf'.



open

    #include <io.h>

    int open(char *name, int mode)

    Open a disk file `name' using read/write mode
`mode', which can be O_RDONLY,
    O_WRONLY, O_RDWR
    returns file handle for the opened file, or EOF if
there was an error opening the file.

    The mode may be    0 read-only    O_RDONLY
                1 write-only    O_WRONLY
                2 read-write    O_RDWR

    Example
        #include <io.h>
        #include <stdio.h>

        void main()
        {
            int fd;
            if (EOF == (fd = open("tfile",O_RDWR))) {
                printf ("failed to open tfile");
            }
            return;
        }



printf

    #include <stdio.h>

    int printf(char *fmt, ...)

    Print formatted values to screen. Arguments follow
the format string and are interpreted
    according to the format string.
    The format string is a sequence of characters with
embedded conversion commands.
    Characters that are not part of the conversion
command are output.

    printf returns the number of characters written.

    The format string can contain text values, or a
format specification for arguments, one per
    argument, beginning with a `%' character, the type
matching the argument's type;

    % (conversion-flag) (min-field-width) (precision)
(operation)

    eg %-20s  %12.4d

    The conversion flag character can be one of

        -    left adjust
        +    force sign output
        0    pad with 0 instead of space
        (space)    produce sign `-' or space

    Minimum field width is the minimum number of
characters output for the field; if fewer
    characters are available from the argument, pad
characters (0 or space) are inserted.

    Precision is the minimum number of characters
printed from a number, or the maximum
    number of characters printed from a string.

    Operation specifies the expected argument type and
what will be output; the expected output
    type must match the type of the corresponding
argument for output to be meaningful.

        `h'    short int
        `l'    long int
        `c'    character
        `d' `i'     integer
        `o'    octal integer
        `p'    pointer
        `x'    hexadecimal
        `s'    string
        `u'    unsigned

    The number of characters written is returned.

    Example
        #include <io.h>
        #include <stdio.h>

        void main()
        {
            char *msg = "number formats are: ";
            int n = 42;

            printf(fp,"%sx: 0%x d: %d o:
%o\n",msg,n,n,n,n);
            return;
        }



putc

    #include <stdio.h>

    int putc(int c, FILE *fp)

    Write character `c' to file `fp'. Returns `c'.



putchar

    #include <stdio.h>

    int putchar(int c)

    Write character `c' to stdout. Returns `c'.

    Example

        #include <stdio.h>

        void main()
        {
            int n;
            FILE *fp;

            fp = fopen ("tfile", "r");

             while ( !feof(fp) )
            putchar(getc(fp));

            return;
        }



puts

    #include <stdio.h>

    int puts(char *str)

    Writes string `str' to stdout, then writes a newline
character.

    Example

        #include <stdio.h>

        void main()
        {
            char buf[80];
            gets(buf); puts(buf);
            return;
        }



read

    #include <io.h>

    int read(int fd, void *buf, int n)

    Read `n' bytes from file given by file descriptor
`fd' into buffer `buf'. Direct DOS read from
    file.

    Returns        -1  error
            0   end of file
            n   number of bytes read

    Example

        #include <io.h>
        #include <stdio.h>

        void main()
        {
            char buf[80];
            int fd;
            if (EOF == (fd = open("tfile",O_RDWR))) {
                printf ("failed to open tfile");
            }
            read(fd,buf,80); puts(buf);
            return;
        }



scanf

    #include <stdio.h>

    int scanf(char *format,...);

    Read arguments from stdin. Parse it according to
specification in `format' string, and assign
    input to arguments following the format string.

    The arguments following `format' must be pointers to
objects where the input is to be stored,
    and must match the specification in the format
string.

    Returns the number of arguments assigned to. If no
arguments were assigned, an EOF is
    returned.

    The format string may contain;

        - space characters; skip whitespace characters
in input.

        - any other characters (except %) which should
match input
          (match a `%' character by specifying `%%')

        - input conversion specification

            % (size) conversion-char

    If the conversion specification is %*(size) c-char
then the converted input is not
    stored and no argument is used.

    If `size' is specified then at most `size'
characters are converted. Otherwise
    conversion stops when an invalid input character is
read.

    The conversion character specifies the input object
type and must match the type of
    argument pointer;

        `h'    short int
        `l'    long int
        `c'    character
        `d' `i' integer
        `x'    hexadecimal
        `s'    string


    Example

        #include <io.h>
        #include <stdio.h>

        void main()
        {
            unsigned n;
            printf("type a number: ");
            scanf("%i",&n);
            printf("number %d is %x hex",n,n);
            return;
        }



sprintf

    #include <stdio.h>

    int sprintf(char *buf, char *fmt, ...)

    Print formatted values to memory. Arguments follow
the format string and are interpreted
    according to the format string.

    sprintf returns the number of characters written.
    See printf for description of format string.



sscanf

    #include <stdio.h>

    int sscanf(char *buf, char *fmt, ...)

    Parse string in buffer `buf' according to
specification in `format' string, and assign input to
    arguments following the format string.

    The arguments following `format' must be pointers to
objects where the input is to be stored,
    and must match the specification in the format
string.

    Returns the number of arguments assigned to. If no
arguments were assigned, an EOF is
    returned.



strcat

    #include <string.h>

    char *strcat(char *buf1,  char *buf2)

    Catenate null-terminated string in `buf2' to the
string in buffer `buf1'. Returns `buf1'.



strchr

    #include <string.h>

    char *strchr(char *str, int c)

    Search string `str' for character `c', return first
occurrence.



strcmp

    #include <string.h>

    int strcmp(char *str1, char *str2)

    Compare null-terminated strings `str1' and `str2'.
If they are identical then return 0. If the
    first differing character in `str1' is greater than
that in `str2' then return a positive value,
    else return a negative value.



strcpy

    #include <string.h>

    char *strcpy(char *buf1, char *buf2)

    Copy null-terminated string in `buf2' to buffer
`buf1'.



strdup

    #include <string.h>

    char *strdup(char *str)

    Create copy of null-terminated string `str' in newly
allocated buffer, and return the buffer.



strlen

    #include <string.h>

    int strlen(char *str)

    Return length of null-terminated string `str'.



strlwr

    #include <string.h>

    char *strlwr(char *str)

    Convert string `str' to lowercase and return it.



strncat

    #include <string.h>

    char *strncat(char *buf1, char *buf2, int n)

    Catenate null-terminated string in `buf2' to null-
terminated string in `buf1'. At most `n'
    bytes are catenated.
    Returns `buf1'.



strncmp

    #include <string.h>

    int strncmp(char *buf1, char *buf2, int n)

    Compare null-terminated strings `str1' and `str2'.
The strings are compared for at most `n'
    characters. If they are identical then return 0. If
the first differing character in `str1' is
    greater than that in `str2' then return a positive
value, else return a negative value.



strncpy

    #include <string.h>

    char *strncpy(char *buf1, char *buf2, int n)

    Copy null-terminated string in buffer `buf2' to
buffer `buf1'. Exactly `n' characters are
    copied. If `buf2' contains fewer than `n'
characters, destination `buf1' is padded with nulls.



strnicmp

    #include <string.h>

    int strnicmp(char *buf1, char *buf2, int n)

    Compares `n' characters of strings `buf1' and
`buf2', ignoring case.

    Returns        0    strings equal, ignoring case
            < 0    first differing character `buf1' <
`buf2'
            > 0    first differing character `buf1' >
`buf2'



strpbrk

    #include <string.h>

    char *strpbrk(char *str1, char *str2)

    Search string `str1' for a character occurring in
string `str2', return first occurrence.



strrchr

    #include <string.h>

    char *strrchr(char *buf, int c)

    Search null-terminated string in buffer `buf' for
character `c', returning pointer to last
    occurrence of `c' in `buf'.



strrev

    #include <string.h>

    char *strrev(char *str)

    Reverses the contents of string `str'. Returns
`str'.



strspn

    #include <string.h>

    int strspn(char *str1, char *str2)

    Span string `str1' skipping any characters in string
`str2'.



strupr

    #include <string.h>

    char *strupr(char *str)

    Convert string `str' to uppercase, and return
uppercased string.



tolower, toupper

    #include <string.h>

    int tolower(int c)
    int toupper(int c)

    Convert character `c' to lower/upper case.



ungetc

    #include <stdio.h>

    int ungetc(int c, FILE *fp)

    Push character `c' back to input file `fp'. Only one
character may be ungetc'd.
    Returns `c' if succeeded, else EOF.

    Example

        #include <io.h>
        #include <stdio.h>
        #include <ctype.h>

        void main()
        {
            FILE *fp;
            char c;

            fp = fopen("tfile","r");
            while((c = fgetc(fp)) != EOF)
                if(isspace(c))
                  break;
                else
                  putchar(c);

          ungetc(c,fp);
          fclose(fp);
          return;
        }



vsprintf

    #include <stdio.h>

    int vsprintf(char *buf, char *fmt, char *args)

    Prints the arguments pointed to by stack segment
pointer `args' to output buffer `buf'.
    See printf for description of format string,
    Returns the number of characters written.



write

    #include <stdio.h>

    int write(int fd, void *buffer, int size);

    Write memory buffer of length `size' to file `fd'.
This is a direct DOS write to file.
    Returns the number of characters written or -1 if
error.

    Example

        #include <io.h>
        #include <stdio.h>
        #include <string.h>

        void main()
        {
            int n, fd;
            char *buf = "test data to be written";

            if((fd = open("tfile",O_WRONLY)) == -1)
                {
                    puts("failed to open file");
                    return;
                }
            n = write(fd,buf,strlen(buf));
            printf("%u bytes written\n",n);
            close(fd);
            return;
        }
Miracle C Compiler, version 1.5    Page 5