




          ===========================================================
                DDDDD           DDDDD               SSSS
                 D   Dunfield    D   D             S
                 D   D           D   Development    SSSS
                 D   D           D   D                  Services
                DDDDD           DDDDD               SSSS
          ===========================================================
          MM   MM  IIIIIII    CCCC   RRRRRR     OOO             CCCC
          M M M M     I      C    C  R     R   O   O           C    C
          M  M  M     I     C        R     R  O     O         C
          M     M     I     C        RRRRRR   O     O  -----  C
          M     M     I     C        R   R    O     O         C
          M     M     I      C    C  R    R    O   O           C    C
          M     M  IIIIIII    CCCC   R     R    OOO             CCCC
          ===========================================================


                             A compact 'C' compiler
                                      for
                                 Small Systems.


                          DVM/Win64 Library Reference


                                  Release 3.23

                               Revised 21-Apr-04










                         Dunfield Development Services
                         -----------------------------
                             High quality tools for
                              Embedded Development


                      https://dunfield.themindfactory.com


                       Copyright 1988-2020 Dave Dunfield
                              All rights reserved



                               MICRO-C PC Library

                               TABLE OF CONTENTS


                                                                         Page

     1. ALPHABETICAL FUNCTION INDEX                                         1


     2. STANDARD LIBRARY                                                    7


     3. IBM-PC/MS-DOS LIBRARY                                               8


     4. DVM LIBRARY DIFFERENCES                                             9

    MICRO-C PC Library                                               Page: 1


    1. ALPHABETICAL FUNCTION INDEX

    --Flags--
    Documented :  S=Std-lib  P=PC-lib  W=Window-lib  D=DVM-only L=LRG-lib H=HRG-lib
    Portability:  A=ANSI     U=UNIX    *=Differs from standard

    Name          Flags   Description
    ---------------------------------
    abort         SA*     Terminate program with error message
    abs           SA      Get absolute value
    alloca        P       Allocate "automatic" memory
    alloc_seg     P       Allocate external (far) memory
    atoi          SA      Convert ASCII-decimal string to value
    atox          S       Convert ASCII-hex string to value
    beep          P       Generate a beep
    calloc        SA      Allocate and clear memory
    cbreak        P       Get/Set DOS control-break handling
    Cclose        P       Close COMM port
    cd            S       Change current directory
    Cgetc         P       Get character from COMM port
    chdir         SU      Change current directory
    clearerr      SA      Clear I/O stream error flag
    close         SU      Close an open file (handle)
    concat        S       Join multiple strings into one
    Copen         P       Open COMM port
    copy_seg      P       Copy external (far) memory
    coreleft      S       Get amount of free memory
    cpu           P       Get CPU type
    Cputc         P       Write character to COMM port
    create        S       Create a file
    Csignals      P       Get COMM port signals
    Ctestc        P       Test for character from COMM port
    delay         P       Delay in milliseconds
    delete        S       Delete a file
    disable       P       Disable interrupts
    dup           SU      Duplicate a file handle
    dup2          SU      Duplicate one file handle into another
    enable        P       Enable interrupts
    exec          P       Execute external program
    exit          SA      Terminate program with return code
    fclose        SA      Close a file (stream)
    ferror        SA      Get I/O stream error flag
    fflush        SA      Flush stream file
    fget          S       Get one block of data from file (stream)
    fgetc         SA      Get character from file (stream)
    fgets         SA*     Get string from file (stream)
    findfirst     S       Locate first directory entry with wildcards
    findnext      S       Locate subsequent directory entries
    fimd_close    D       Close a directory entry searcg
    find_first    S       Locate first directory entry with wildcards
    find_next     S       Locate subsequent directory entries
    fopen         SA      Open a file (stream)
    fprintf       SA*     Formatted output to file (stream)
    fput          S       Write one block of data to file (stream)
    fputc         SA      Write character to file
    fputs         SA      Write string to file
    fread         SA      Read multiple blocks of data from file
    MICRO-C PC Library                                               Page: 2


    free          SA      Release allocated memory
    free_seg      P       Release external (far) memory
    freopen       SA      Reopen a file using existing stream
    fscanf        SA*     Formatted input from file (stream)
    fseek         SA*     Position file I/O pointer (stream)
    ftell         SA*     Get position in file (stream)
    fwrite        SA      Write multiple blocks of data to file (stream)
    getc          SA      Get character from file (stream)
    getchar       SA      Get character from stdin
    getdir        S       Get current directory
    getenv        SA*     Get string from environment
    gets          SA      Get string from stdin
    get_attr      P       Get file attributes
    get_cs        P       Get code segment
    get_date      P       Get current date
    get_drive     P       Get current drive
    get_ds        P       Get data segment
    get_es        P       Get extra segment
    get_time      P       Get current time
    get_vector    P       Get interrupt vector
    halt          D       Similar to exit() but ALL DVM ends.
    hrg_arc       H       Draw an ARC
    hrg_box       H       Draw an outline BOX
    hrg_circle    H       Draw an outline CIRCLE
    hrg_close     H       Terminate high-res graphics
    hrg_delay     H       Delay synchronized to video update
    hrg_fbox      H       Draw a filled (solid) box
    hrg_fcircle   H       Draw a filled (solid) circle
    hrg_fill      H       Fill screen with a color
    hrg_getpal    H       Get a palette entry
    hrg_hline     H       Draw a horizontal line
    hrg_line      H       Draw an arbitrary line
    hrg_open      H       Init the display for high-res graphics
    hrg_printf    H       Formatted print to graphics screen
    hrg_putc      H       Draw a character
    hrg_puts      H       Draw a string
    hrg_plot      H       Plot a single pixel
    hrg_retrace   H       Wait for video refresh
    hrg_setpal    H       Set a palette entry
    hrg_vline     H       Draw a vertical line
    in            S       Read byte from I/O port
    int86         P       Generate 8086 interrupt
    intr          P       Generate 8086 interrupt
    inw           S       Read word from I/O port
    isacon        S       Test for a console device
    isadev        S       Test for any device
    isalnum       SU      Test for alphabetic or numeric character
    isalpha       SA      Test for alphabetic character
    isascii       SU      Test for ASCII character
    isatty        S       Test for a tty device
    iscntrl       SA      Test for control character
    isdigit       SA      Test for numeric character
    isgraph       SA      Test for graphic character
    islower       SA      Test for lowercase alphabetic character
    isprint       SA      Test for printable character
    ispunct       SA      Test for punctuation character
    isspace       SA      Test for whitespace character
    MICRO-C PC Library                                               Page: 3


    isupper       SA      Test for uppercase alphabetic character
    isxdigit      SA      Test for hex-digit character
    itoa          S       Convert integer to ASCII-decimal
    joystick      P       Read joystick port
    keyboard      P       Direct keyboard interface functions
    lgetc         S       Get character from file (handle)
    lgets         S       Get string from file (handle)
    longjmp       SA      Execute non-local goto
    longmath      S       Long (32 bit) math functions
    lprintf       S       Formatted output to file (handle)
    lputc         S       Write character to file (handle)
    lputs         S       Write string to file (handle)
    lrewind       S       Reset file I/O pointer (handle)
    lrg_arc       L       Draw an ARC
    lrg_blit      L       Transfer image to screen
    lrg_box       L       Draw an outline BOX
    lrg_circle    L       Draw an outline CIRCLE
    lrg_close     L       Terminate low-res graphics
    lrg_delay     L       Delay synchronized to video update
    lrg_draw      L       Draw a sprite graphic
    lrg_erase     L       Erase a sprite graphic
    lrg_fbox      L       Draw a filled (solid) box
    lrg_fcircle   L       Draw a filled (solid) circle
    lrg_fill      L       Fill screen with a color
    lrg_getpal    L       Get a palette entry
    lrg_hline     L       Draw a horizontal line
    lrg_line      L       Draw an arbitrary line
    lrg_open      L       Init the display for low-res graphics
    lrg_printf    L       Formatted print to graphics screen
    lrg_putc      L       Draw a character
    lrg_puts      L       Draw a string
    lrg_plot      L       Plot a single pixel
    lrg_retrace   L       Wait for video refresh
    lrg_setpal    L       Set a palette entry
    lrg_vline     L       Draw a vertical line
    lscanf        S       Formatted input from file (handle)
    lsearch       SU      Linear search
    lseek         S       Position file I/O pointer (handle)
    ltell         S       Get position in file (handle)
    malloc        SA      Allocate memory
    max           S       Get maximum value
    memchr        SA      Scan memory for a character
    memcmp        SA      Compare memory blocks
    memcpy        SA      Copy memory blocks
    MemReadcode1  D       Read 1 byte from code memory
    MemReadcode2  D       Read 2 bytes from code memory
    memmove       SA      Move memory blocks
    memset        SA      Set memory block to value
    min           S       Get minimum value
    mkdir         S       Create a directory
    nargs         S       Get # function arguments
    open          SU*     Open a file (handle)
    out           S       Write byte to I/O port
    outw          S       Write word to I/O port
    peek          S       Read byte from memory
    peekw         S       Read word from memory
    poke          S       Write byte to memory
    MICRO-C PC Library                                               Page: 4


    pokew         S       Write word to memory
    printf        SA*     Formatted output to stdout
    putc          SA      Write character to file
    putchar       SA      Write character to stdout
    puts          SA      Write string to stdout
    qsort         SA      Quicksort
    rand          SA      Generate random number
    random        S       Generate random number with range
    read          SU      Read block of data from file (handle)
    realloc       SA      Resize allocated memory block
    remove        SA      Delete a file
    rename        SA      Rename a file
    resize_seg    P       Resize external (far) memory
    restore_video P       Restore video text page
    rewind        SA      Reset file I/O pointer (stream)
    RDsetup       D       RamDrive: make temp storage accssible as files
    rmdir         S       Delete a directory
    RPend         D       Remote Process end
    RPread        D       Remote Process read data
    RPstart       D       Remote Process start
    RPwrite       D       Remote Process write data
    save_video    P       Save video text page
    scanf         SA*     Formatted input from stdin
    setbuf        SA*     Resize file I/O buffer (stream)
    setCapture    D       Capture console output to file
    setjmp        SA      Setup a non-local goto
    set_attr      P       Set file attributes
    set_date      P       Set current date
    set_drive     P       Set current drive
    set_es        P       Set extra segment
    set_time      P       Set current time
    set_vector    P       Set interrupt vector
    sleep         D       Delay in milliseconds
    sound         P       Generate a tone
    sound_off     P       Turn off sound
    sprintf       SA      Formatted output to string (memory)
    sqrt          SA*     Get square root of integer
    sscanf        SA      Formatter input from string (memory)
    stpcpy        SU      Copy string to another
    strbeg        S       Test for string beginning with another
    strcat        SA      Concatenate string to another
    strchr        SA      Locate character in string
    strcmp        SA      Compare two strings
    strcpy        SA      Copy string to another
    strcspn       SA      Scan string excluding a set
    strdup        SU      Duplicate a string
    stricmp       S       Compare strings without case
    strlen        SA      Get length of string
    strlwr        S       Convert string to lowercase
    strncat       SA      Append string to another with limit
    strncmp       SA      Compare strings with limit
    strncpy       SA      Copy string with limit
    strnicmp      S       Compare string without case with limit
    strnset       S       Set string to value with limit
    strpbrk       SA      Scan string for character from set
    strrchr       SA      Scan string for last character
    strrev        S       Reverse string
    MICRO-C PC Library                                               Page: 5


    strset        S       Set string to value
    strspn        SA      Scan string including a set
    strstr        SA      Scan string for substring
    strtok        SA      Parse tokens from string
    strupr        S       Convert string to uppercase
    system        SA      Execute system command
    tolower       SA      Convert character to lowercase
    toupper       SA      Convert character to uppercase
    tsr           P       Terminate and stay resident
    unlink        SU      Delete a file
    vclear_box    P       Clear a text box
    vcleol        P       Clear to end of line
    vcleos        P       Clear to end of screen
    vclscr        P       Clear entire screen
    Vcolor        D       Set Video color attribute
    vcursor_block P       Set cursor to block
    vcursor_line  P       Set cursor to line
    vcursor_off   P       Set cursor off
    vdraw_box     P       Draw text box
    version       P       Get DOS version
    vgetc         P       Get character from console
    Vgetk         D       "" without special keypad keys
    vgets         P       Get string from console
    vgotoxy       P       Position console cursor
    vmenu         P       Present menu to console
    vmessage      P       Output message to console
    vopen         P       Open console for output
    vprintf       P       Formatted output to console
    vputc         P       Output character to console
    vputf         P       Output string in field to console
    vputs         P       Output string to console
    vtstc         P       Test for character from console
    vupdatexy     P       Update console cursor position
    wcleol        W       Clear to end of line in current window
    wcleow        W       Clear to end of current window
    wclose        W       Close current window
    wclwin        W       Clear current window
    wcursor_block W       Set window cursor to block
    wcursor_line  W       Set window cursor to line
    wcursor_off   W       Set window cursor off
    wform         W       Present input form in window
    wgetc         W       Get character in current window
    wgets         W       Get string in window
    wgotoxy       W       Position cursor in current window
    wmenu         W       Present menu in a window
    wmessage      W       Present a message in a window
    wopen         W       Open a window
    wprintf       W       Formatted print to current window
    wputc         W       Output character in current window
    wputf         W       Output string to window in field
    wputs         W       Output string to current window
    write         SU*     Write block of data to file (handle)
    wtstc         W       Test for character in current window
    wupdatexy     W       Update cursor position in current window
    w_cleol       W       Clear to end of line in any window
    w_cleow       W       Clear to end of any window
    w_close       W       Close any window
    MICRO-C PC Library                                               Page: 6


    w_clwin       W       Clear any window
    w_getc        W       Get character in any window
    w_gotoxy      W       Position cursor in any window
    w_printf      W       Formatted print to any window
    w_putc        W       Output character in any window
    w_puts        W       Output string to any window
    w_tstc        W       Test for character in any window
    w_updatexy    W       Update cursor position in any window
    _format_      S       Perform custom "printf" formatting
    MICRO-C PC Library                                               Page: 7



                         +----------------------------+
                         |                            |
                         |  ************************  |
                         |  * The STANDARD library *  |
                         |  ************************  |
                         |                            |
                         +----------------------------+










    2. STANDARD LIBRARY

          The  library  functions  described  on  the  following  pages  are
       currently available in  the  IBM/PC  MICRO-C  library  as  "standard"
       functions which are of a general nature,  and should be  portable  to
       most implementations of MICRO-C.

          The exact syntax and  capabilities  of  the  system  or  processor
       dependent functions may vary in different implementations,  see  your
       implementation notes  (README.TXT)  for details.  Different  possible
       forms of such functions are shown using (1), (2), ... In these cases,
       the form (1) of the function is the one used in the MS-DOS library.
    ABORT                                                             ABORT



    PROTOTYPE:

        abort(char *message)


    ARGUMENTS:

        message - Pointer to message to display


    RETURN VALUE:

        N/A - Function never returns


    DESCRIPTION:

          This function writes the string passed as an argument to  standard
       error,  and then terminates the program with a return  code  of  '-1'
       (Indicating general  failure).  This  provides  a  simple  method  of
       terminating a program on an error condition with a message explaining
       why.

          MICRO-C's  implementation  of  this  function  differs  from  ANSI
       standards in that it accepts a user supplied error message.


    EXAMPLES:

        abort("Invalid operand\n");
    ABS                                                                 ABS



    PROTOTYPE:

        int abs(int number)


    ARGUMENTS:

        number  - Any integer value


    RETURN VALUE:

        The absolute value of "number"


    DESCRIPTION:

          The "abs" function returns the absolute value of the argument.  If
       "number" is a positive value, it is returned unchanged.  If negative,
       the negate of that value is returned (giving a positive result).


    EXAMPLES:

        difference = abs(value1 - value2);
    ATOI                                                               ATOI



    PROTOTYPE:

        int atoi(char *string)


    ARGUMENTS:

        string  - Pointer to a string containing a decimal number


    RETURN VALUE:

        16 bit integer value


    DESCRIPTION:

          The  "atoi"  function converts an ASCII string containing a signed
       decimal number (-32768 to 32767) to a 16 bit value which is returned.
       An unsigned number of the range  (0 to 65535)  may also be used,  and
       the result if assigned to an "unsigned" variable will be correct.


    EXAMPLES:

        value = atoi("1234");
        value = atoi("-1");
    ATOX                                                               ATOX



    PROTOTYPE:

        unsigned atox(char *string)


    ARGUMENTS:

        string  - Pointer to a string containing a hexadecimal number


    RETURN VALUE:

        16 bit unsigned value


    DESCRIPTION:

          The  "atox"  function  converts  an  ASCII  string  containing   a
       hexadecimal number (0 to FFFF) to a 16 bit value which is returned.


    EXAMPLES:

        value = atox("00FF");
    BSEARCH                                                         BSEARCH



    PROTOTYPE:

        char *bsearch(char *k, char *t, unsigned e, unsigned s, int (*f)())


    ARGUMENTS:

        k   - Key to search for
        t   - Table to search
        e   - Number on entries in the table
        s   - Size of each entry
        f   - Pointer to function performing compare


    RETURN VALUE:

        Address of found record, or zero (0) if no match


    DESCRIPTION:

          Performs a binary search of the specified table,  looking for  the
       given key.  Since  this  is  a  binary  search,  the  table  must  be
       maintained in sequential order with lower entries appearing first.

          Any fixed format table can be used.  The key and a pointer to each
       entry to test are passed to the user supplied compare function, which
       must return 0 if equal,  <0 if the key  (first arg)  is less than the
       table entry, or >0 if the key is larger than the table entry.


    EXAMPLES:

        #include <stdio.h>
        int table[] = { 123, 187, 236, 392, 481, 599, 600, 737 };
        int test(int *a, int *b) { return *a - *b; }
        main(argc, char *argv[])
        {
            int key;
            key = atoi(argv[1]);
            printf("%04x", bsearch(&key, table, 8, sizeof(int), &test));
        }
    CALLOC                                                           CALLOC



    PROTOTYPE:

        char *calloc(int items, int size)


    ARGUMENTS:

        items   - Number of items to allocate size for
        size    - Size of each item (in bytes)


    RETURN VALUE:

        0       - Memory allocation failed
        !0      - Pointer to allocated memory block


    DESCRIPTION:

          The "calloc" function allocates a block of (items * size) bytes of
       memory from the heap,  and returns a pointer  to  it.  The  allocated
       memory is automatically cleared to zeros.  This  memory  will  remain
       allocated until it is explicitly released with the "free" function.


    EXAMPLES:

        if(!(ptr = calloc(10, LINSIZ)))     /* Allocate buffer for 10 lines */
            abort("Not enough memory");
        for(i=0; i < 10; ++i)               /* Read lines into buffer */
            fgets(ptr+(i*LINSIZ), LINSIZ-1, inf_fp);
        do_something(ptr);                  /* Whatever you like */
        free(ptr);                          /* Release temporary buffer */
    CD                                                                   CD
    CHDIR                                                             CHDIR


    PROTOTYPE:

        int cd(char *pathname)
        int chdir(char *pathname)


    ARGUMENTS:

        pathname- Name of directory to make current


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          This function sets the "current" directory, causing all subsequent
       file references which do not explicitly indicate a directory path  to
       access the path specified by "pathname".


    EXAMPLES:

        cd("\\mc\\l_source");       /* MS-DOS */
        chdir("/mc/c_source");      /* UNIX */
    CONCAT                                                           CONCAT



    PROTOTYPE:

        register concat(char *dest, char *source, ...)


    ARGUMENTS:

        dest    - Pointer to destination string
        source  - Pointer to source string
        ...     - Additional sources may be given


    RETURN VALUE:

        None


    DESCRIPTION:

          The  "concat"  function concatenates the given source strings into
       one destination string.  The destination string must be large  enough
       to hold all of the source strings plus the string  terminator  (zero)
       byte. No value is returned.

          NOTE: This function uses a variable number of arguments,  and must
       be declared as "register" (See "stdio.h").


    EXAMPLES:

        concat(filename,"/tmp/", input_name);
    CORELEFT                                                       CORELEFT



    PROTOTYPE:

        unsigned coreleft()


    ARGUMENTS:

        None


    RETURN VALUE:

        Amount of memory remaining on the heap


    DESCRIPTION:

          Computes the amount of memory  available  for  allocation  on  the
       heap.

          The highest memory address allocated on  the  heap  is  subtracted
       from  the  stack  pointer,  along  with  a  protective  "margin"  for
       potential stack growth.

          The value returned is approximate,  and will continue to vary  due
       to stack use.

          Every call to  "calloc/malloc"  will reduce the amount  of  memory
       left in the heap by 3 plus the size of the memory allocated bytes.


    EXAMPLES:

        printf("There is enough memory to allocate %u records\n",
            coreleft() / (sizeof(record)+3));
    DELETE                                                           DELETE



    PROTOTYPE:

        int delete(char *pathname)



    ARGUMENTS:

        pathname- Name of file to delete


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          The "delete" function removes an existing file from the disk.  Any
       disk space occupied by the file is released.


    EXAMPLES:

        delete("temp");
    EXIT                                                               EXIT



    PROTOTYPE:

        exit(int rc)


    ARGUMENTS:

        rc      - Termination return code


    RETURN VALUE:

        N/A - Function never returns


    DESCRIPTION:

          This function terminates the execution of the program and passes a
       specific return code back to the caller.  A return code value of zero
       is used to indicate successful program  completion.  Non-zero  return
       code values may be used to indicate a particular type of  failure.  A
       value of '-1' is often used to indicate a non-specific failure.  Note
       that the  "rc"  value is very system specific,  in  particular,  some
       systems support only 8 bit return codes,  so values which are greater
       than 255 should be avoided.


    EXAMPLES:

        exit(0);        /* success */
        exit(-1);       /* failure */
    FCLOSE                                                           FCLOSE



    PROTOTYPE:

        int fclose(FILE *fp)


    ARGUMENTS:

        fp      - File pointer to an open file


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          This function closes a file  which  was  previously  opened  using
       "fopen".  The I/O buffer space used by the file is released.  In  the
       case of a file open for write ('w'),  the last disk buffer is flushed
       and written to disk.


    EXAMPLES:

        fclose(fp);
    FFLUSH                                                           FFLUSH



    PROTOTYPE:

        fflush(FILE *fp)


    ARGUMENTS:

        fp       File pointer to an open file


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          The  "fflush"  function flushes the I/O buffers for the given open
       file. If the file is opened for WRITE, this causes any data remaining
       in a partially filled output buffer to be written.  If  the  file  is
       opened for READ,  this has the effect of throwing away any data which
       is pending in the input buffer.


    EXAMPLES:

        fputs("Enter you name?", stdout);
        fflush(stdout);         /* Make sure prompt is output */
        fgets(name, 80, stdin);
    FGET                                                               FGET



    PROTOTYPE:

        int fget(char *buffer, int size, FILE *fp)


    ARGUMENTS:

        buffer  - Pointer to buffer to receive data
        size    - Number of bytes to read
        fp      - File pointer to an input file


    RETURN VALUE:

        Number of bytes read from file


    DESCRIPTION:

          This function reads a block of data from a file and places  it  in
       memory at the address of  "buffer".  Data will be read in either TEXT
       or BINARY form,  depending on how the file was opened.  If the number
       of bytes returned is less than the number of bytes requested,  either
       the end of the file was encountered or an  error  condition  occurred
       (in which case the value will be zero).


    EXAMPLES:

        fget(block, 512, input_fp);
    FGETC                                                             FGETC



    PROTOTYPE:

        int fgetc(FILE *fp)


    ARGUMENTS:

        fp      - File pointer to an input file


    RETURN VALUE:

        Value of a character read from the file (0-255)
        EOF (-1) if end of file or an error condition occurs


    DESCRIPTION:

          This function reads a single character from  an  input  file,  and
       returns it as a positive value in the range of 0 to 255.  A  full  16
       bit value is returned,  allowing the end  of  file  condition  to  be
       distinct from the character value 255.


    EXAMPLES:

        if((c = fgetc(input_file)) == EOF)
            abort("End of file encountered\n");
    FGETS                                                             FGETS



    PROTOTYPE:

        char *fgets(char *buffer, int size, FILE *fp)


    ARGUMENTS:

        buffer  - Pointer to string to receive line
        size    - Maximum size of line to read
        fp      - File pointer to an input file


    RETURN VALUE:

        Pointer to "buffer", or 0 if end of file


    DESCRIPTION:

          The  "fgets"  function reads characters from the  specified  input
       file,  and places them in the character buffer  until  one  of  three
       things happens:

          1) A NEWLINE character is encountered.

          2) The END of the file is encountered.

          3) The limit of "size" character is read.

          The string is terminated with the standard  NULL  (00)  character.
       The trailing NEWLINE  '\n'  character is NOT included  in  the  input
       buffer.

          MICRO-C's  implementation  of  this  function  differs  from  ANSI
       standards in that it does not include the NEWLINE  '\n'  character in
       the input buffer.


    EXAMPLES:

        fgets(input_line, 80, input_file);
    FINDFIRST                                                     FINDFIRST



    PROTOTYPE:

        int findfirst(char *pattern, struct FF_block *block, int attrs)


    ARGUMENTS:

        pattern - File name pattern to match
        block   - Structure to receive information
        attrs   - File attributes to match


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          This function locates the first file on the disk which matches the
       given pattern. The "attrs" field specifies any special attributes the
       files must have in order to be matched,  use 0 for  normal  directory
       searches.

          Subsequent files may be located using the "findnext" function.

          The "FF_block" structure is defined in the FILE.H header file look
       there  to  see  the  information  that  is  filled   in.   Additional
       information is also stored in this structure which  permits  multiple
       findfirst and findnext's to be active at the same time.


    EXAMPLES:

        #include <file.h>
        struct FF_block blkptr;
        if(findfirst(pattern, blkptr, 0))
            abort("No matching files found\n");
    FIND_FIRST                                                   FIND_FIRST



    PROTOTYPE:

        int find_first(char *pattern, int mattrs, char name[], int &sizeh,
                       int &sizel, int &attrs, int &time, int &date)


    ARGUMENTS:

        pattern - File name pattern to match
        mattrs  - File attributes to match
        name    - Address of string to receive file name
        &sizeh  - Address of int to receive high word of size
        &sizel  - Address of int to receive low word of size
        &attrs  - Address of int to receive attributes
        &time   - Address of int to receive time stamp
        &date   - Address of int to receive date stamp


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          This function locates the first file on the disk which matches the
       given pattern.  The  "mattrs"  field specifies any special attributes
       the files must have  in  order  to  be  matched,  use  0  for  normal
       directory searches.

          Subsequent files may be located using the "find_next" function.

          Only one find_first/find_next may be active at any one time.  Each
       time a new find_first is executed, all information about the previous
       search is lost.


    EXAMPLES:

        if(find_first(pattern, 0, name, &sh, &sl, &a, &t, &d))
            abort("No matching files found\n");
    FINDNEXT                                                       FINDNEXT



    PROTOTYPE:

        int findnext(struct FF_block *block)


    ARGUMENTS:

        block   - Structure originally passed to findfirst


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          The function must be preceded by a call to  "findfirst"  with  the
       same structure.  The next file matching the original  search  pattern
       and attributes will be filled into the structure.


    EXAMPLES:

        do
            printf("%s\n", blkptr->name);
        while(!findnext(blkptr));
    FIND_NEXT                                                     FIND_NEXT



    PROTOTYPE:

        int find_next(char name[], int &sizeh, int &sizel, int &attrs,
                      int &time, int &date)


    ARGUMENTS:

        name    - Address of string to receive file name
        &sizeh  - Address of int to receive high word of size
        &sizel  - Address of int to receive low word of size
        &attrs  - Address of int to receive attributes
        &time   - Address of int to receive time stamp
        &date   - Address of int to receive date stamp


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          The function must be preceded by a call to "find_first",  and will
       locate the next file on  the  disk  which  matches  the  pattern  and
       attributes given to that function call.

          Only one find_first/find_next may be active at any one time.  Each
       time a new find_first is executed, all information about the previous
       search is lost.


    EXAMPLES:

        do
            printf("%s\n", name);
        while(!find_next(name, &sh, &sl, &a, &t, &d));
    FIND_CLOSE                                                   FIND_CLOSE



    PROTOTYPE:

        find_close(void)


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          The system on which DVM is built implements the find* functions in
       a way differently than my original library.  All filenames are  found
       at once and placed in an allocated memory buffer.  This buffer should
       be released when you have finished with the list of files.

          My library will automatically release it if  you  perform  another
       call to find[_]first, or if you find[_]next all the way to the end of
       the list, but otherwise the memory will not be released.

          find_close()  will terminate any  ongoing  find*  operations,  and
       release the memory buffer.


    EXAMPLES:

        find_close();
    FOPEN                                                             FOPEN



    PROTOTYPE:

        FILE *fopen(char *filename, char *options)


    ARGUMENTS:

        filename- Name of the file to open
        options - String containing open options:
                    'a' - Append to file (must use with 'w')
                    'b' - Binary mode (default is text)
                    'q' - Quit { exit(-1) } on failure
                    'r' - Open file for read
                    'v' - Issue error message on failure
                    'w' - Open file for write


    RETURN VALUE:

        File pointer to the file buffer for the open file
        Zero (0) if file could not be opened


    DESCRIPTION:

          This function opens a file for  buffered  input  ('r')  or  output
       ('w'),  allowing subsequent I/O operations to read or write the file.
       If the 'b'  option is NOT included,  the file is assumed to be a TEXT
       file,  and appropriate translations are  made  for  NEWLINE  and  EOF
       interpretation.

          The size of the I/O buffer used is established by "fopen" from the
       external variable  'IOB_size',  which has  a  default  value  of  256
       (bytes).  This variable is defined in the 'file.h'  header file,  and
       may be modified prior to calling this function if you wish to  use  a
       different buffer size.

          One I/O buffer is allocated from the heap for each open file. When
       using a large IOB_size value, you must be careful not to consume more
       memory than is available.


    EXAMPLES:

        fp = fopen("input_file", "r");
        fp = fopen("input_file", "rvq");
        IOB_size = 1024*10;         /* Set up a 10K buffer */
        fp = fopen("output_file", "wb");
    FPRINTF                                                         FPRINTF



    PROTOTYPE:

        register int fprintf(FILE *fp, char *format, arg, ...)


    ARGUMENTS:

        fp      - File pointer to an output file
        format  - Pointer to format string
        arg     - Argument as determined by format string
        ...     - Additional arguments may be required


    RETURN VALUE:

        Length of output string


    DESCRIPTION:

          This routine performs a formatted print to  a  file  specified  by
       'fp'.  The 'format'  string is written to the file with the arguments
       substituted for special  "conversion characters".  These  "conversion
       characters" are identified by a preceding '%',  and may be one of the
       following:

                    b       - Binary number
                    c       - Character
                    d       - Decimal (signed) number
                    o       - Octal number
                    s       - String
                    u       - Unsigned decimal number
                    x       - Hexadecimal number
                    %       - A single percent sign (No argument used)

          A numeric "field width" specifier may be placed in between the '%'
       and the conversion character,  in which case the value will be output
       in a field of that width.  If the "field width" is a negative number,
       the output will be left justified in the field, otherwise it is right
       justified. If the field width contains a leading '0', then the output
       field will be padded with zeros, otherwise spaces are used.

          If no  "field width"  is given,  the output is free format,  using
       only as much space as required.

          MICRO-C's  implementation  of  this  function  differs  from  ANSI
       standards in that it is allows a maximum  of  132  characters  to  be
       output with each call.

          NOTE: This function uses a variable number of arguments,  and must
       be declared as "register" (See "stdio.h").



    EXAMPLES:

        fprintf(stderr,"Filename='%s'\n", filename);
        fprintf(stdout,"Address=%04x\n", address);
        fprintf(outfile,"Amount: $%3u.%02u\n", amount / 100, amount % 100);
    FPUT                                                               FPUT



    PROTOTYPE:

        int fput(char *block, int size, FILE *fp)


    ARGUMENTS:

        block   - Pointer to a block of data to write
        size    - Number of bytes to write
        fp      - File pointer to an output file


    RETURN VALUE:

        The number of bytes written to the file


    DESCRIPTION:

          This function writes a block of data to the  indicated  file  from
       memory at the specified address.  Data is written in either  TEXT  or
       BINARY mode,  depending on how the file  was  opened.  If  the  value
       returned is less than the value of the "size"  parameter,  some error
       condition has occurred (Such as disk full).


    EXAMPLES:

        if(fput(buffer, 100, fp) < 100)
            abort("File write error\n");
    FPUTC                                                             FPUTC



    PROTOTYPE:

        fputc(char c, FILE *fp)


    ARGUMENTS:

        c       - Any character value
        fp      - File pointer to an output file


    RETURN VALUE:

        c if successful, otherwise -1


    DESCRIPTION:

          This function writes the character  'c'  to the file indicated  by
       the file pointer 'fp'.


    EXAMPLES:

        fputc('*', fp);
        fputc('\n', stderr);
    FPUTS                                                             FPUTS



    PROTOTYPE:

        fputs(char *string, FILE *fp)


    ARGUMENTS:

        string  - Pointer to a character string
        fp      - FIle pointer to output file


    RETURN VALUE:

        Last character in string if successful, otherwise -1


    DESCRIPTION:

          The "fputs"  function writes the specified string to the indicated
       output file. The zero terminating the string is NOT written.


    EXAMPLES:

        fputs("Text message", output_file);
    FREAD                                                             FREAD



    PROTOTYPE:

        int fread(char *ptr, unsigned size, unsigned count, FILE *fp)


    ARGUMENTS:

        ptr     - Pointer to block of memory to receive data
        size    - Size of each data item to read
        count   - Number of data items to read
        fp      - File pointer to an input file

    RETURN VALUE:

        Count of number of items read from file


    DESCRIPTION:

          This function reads data items of the specified size from an input
       file and places them sequentially in  memory.  The  total  number  of
       bytes read will be (size * count).

          The number of items  (not bytes)  actually read from the  file  is
       returned.  This will be  "count"  if no errors occur,  otherwise some
       value less than count.


    EXAMPLES:

        struct a b[10];
        fp = fopen("struct.dat", "rvqb");
        if(fread(b, sizeof(struct a), 10, fp) != sizeof(b))
            abort("Cannot read structure data);
    FREE                                                               FREE



    PROTOTYPE:

        free(char *block)


    ARGUMENTS:

        block       - Pointer to a previously allocated memory block


    RETURN VALUE:

        None


    DESCRIPTION:

          The "free" function releases (deallocates)  a block of memory that
       was obtained via a call to  "calloc/malloc",  and returns it  to  the
       heap. This makes it available for use by other memory allocations.


    EXAMPLES:

        if(!(ptr = malloc(BUFSIZ)))     /* Allocate a temporary buffer */
            abort("Not enough memory");
        do {                            /* Copy the file over */
            size = fget(ptr, BUFSIZ, in_fp);
            fput(ptr, size, out_fp); }
        while(size == BUFSIZ);
        free(ptr);                      /* Release temporary buffer */
    FREOPEN                                                         FREOPEN



    PROTOTYPE:

        FILE *freopen(char *filename, char *options, FILE *fp)


    ARGUMENTS:

        filename    - Name of file to open
        options     - Open options (see 'fopen')
        fp          - File pointer to an open file


    RETURN VALUE:

        Original file pointer if successful
        Zero (0) if file could not be opened


    DESCRIPTION:

          This substitutes the named file in place of  the  open  file.  The
       original file is closed,  and the new file is attached to  it's  file
       pointer.

          This is a useful function for changing the  file  associated  with
       stdin, stdout and stderr.


    EXAMPLES:

        freopen("OUTPUT.DAT", "wvq", stdout);
        printf("This goes to the output file\n");
    FSCANF                                                           FSCANF



    PROTOTYPE:

        register int fscanf(FILE *fp, char *format, &arg, ...)


    ARGUMENTS:

        fp      - File pointer to an input file
        format  - Pointer to format string
        arg     - Argument as determined by format string
        ...     - Additional arguments may be required


    RETURN VALUE:

        The number of successful matches
        EOF (-1) if end of file or an error condition occurs


    DESCRIPTION:

          This routine reads a line from the specified file and scans it for
       specific values which  are  then  assigned  to  the  passed  argument
       addresses.  The types of values scanned  are  determined  by  special
       "conversion characters" within the "format" string. These "conversion
       characters" are identified by a preceding '%',  and may be one of the
       following:

                    b       - Binary number
                    c       - Character
                    d       - Decimal (signed) number
                    o       - Octal number
                    s       - String
                    u       - Unsigned decimal number
                    x       - Hexadecimal number
                    %       - A single percent sign (No argument used)

          Before scanning for any value other than '%c', any leading "space"
       or "tab" characters in the input line are automatically flushed.

          Scanning of a particular value type will terminate when either the
       end of  the  line  or  a  non-applicable  character  is  encountered.
       Scanning of strings (%s) stops with a "space" or "tab" character, and
       the stored string will be zero terminated.

          A numeric "field width" specifier may be placed in between the '%'
       and the conversion character,  in which case scanning  of  the  value
       will  also  terminate  if  that  many  input  characters  have   been
       processed.

          Scanning  for  characters  (%c)  assumes  a  "field  width"  of  1
       character unless otherwise specified.  If a field width is specified,
       the output is assumed to be  a  string,  and  a  zero  terminator  is
       appended.










          Any other  (non-conversion)  characters in the format string  will
       cause the next character in the input string which is not  a  "space"
       or "tab" to be skipped if it matches that character.

          Any variable values from the input line  which  are  not  required
       must be cleared by scanning them into a "dummy" variable.

          The most common mistake when using  "fscanf"  is forgetting to use
       the  '&'  operator with  a  simple  variable  argument.  This  causes
       "fscanf"  to store the value INDIRECTLY at the address  contained  in
       that variable  (Similar to using  '*'  with  a  pointer)  instead  of
       storing the value into the actual variable  itself.  Arguments  which
       are array names do not require the '&' operator, since the address of
       the array is already generated by reference to its name.

          MICRO-C's  implementation  of  this  function  differs  from  ANSI
       standards in that it does not scan more than a single line  from  the
       input file.

          NOTE: This function uses a variable number of arguments,  and must
       be declared as "register".


    EXAMPLES:

        if(fscanf(infile,"%s %s %u", first_name, last_name, &age) != 3)
            abort("Error in user record\n");
    FSEEK                                                             FSEEK



    PROTOTYPE:

        int fseek(FILE *fp, int h_offset, unsigned l_offset, int mode)


    ARGUMENTS:

        fp      - File pointer to an open file
        h_offset- Highest 16 bits of offset value
        l_offset- Lowest 16 bits of offset value
        mode    - Type of seek
                    0 = Absolute from start of file
                    1 = Signed offset from current position
                    2 = Signed offset from end of file


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          This function positions the operating system internal pointer into
       a file so that any read or write will take  place  at  the  specified
       position in the file.

          Some implementations may not support  all  "modes",  or  may  only
       allow unsigned (positive)  offsets,  depending on the capabilities of
       the operating system.

          MICRO-C's  implementation  of  this  function  differs  from  ANSI
       standards in that it requires the  offset  to  be  specified  as  two
       unsigned integers instead of a single "long"  value.  This is because
       the compiler does not support the "long" type.


    EXAMPLES:

        fseek(in_file, 0, 2);   /* Advance to end of file */
    FTELL                                                             FTELL



    PROTOTYPE:

        int ftell(FILE *fp, int &h_offset, unsigned &l_offset)


    ARGUMENTS:

        fp      - File pointer to an open file
        h_offset- Address of int to receive high word of offset
        l_offset- Address of int to receive low word of offset


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          This function gets the current read/write position within a  file.
       The position returned indicates the absolute character (byte)  offset
       from the start of the file where the next read  or  write  will  take
       place.

          MICRO-C's  implementation  of  this  function  differs  from  ANSI
       standards in that it returns the  offset  as  two  unsigned  integers
       instead of a single "long"  value.  This is because the compiler does
       not support the "long" type.


    EXAMPLES:

        ftell(fp, &oldh, &oldl);    /* Save file position */
            . . .                   /* Perform some operations on the file */
        fseek(fp, oldh, oldl, 0);   /* Return to previous position */
    FWRITE                                                           FWRITE



    PROTOTYPE:

        int fwrite(char *ptr, unsigned size, unsigned count, FILE *fp)


    ARGUMENTS:

        ptr     - Pointer to block of memory containing data
        size    - Size of each data item to write
        count   - Number of data items to write
        fp      - File pointer to an output file

    RETURN VALUE:

        Count of number of items written to file


    DESCRIPTION:

          This function writes data items of the specified size to an output
       file from memory.  The total number of bytes written will be  (size *
       count).

          The number of items  (not bytes)  actually written to the file  is
       returned.  This will be  "count"  if no errors occur,  otherwise some
       value less than count.


    EXAMPLES:

        struct a b[10];
        /* ... Code that fills in structure ... */
        fp = fopen("struct.dat", "wvqb");
        if(fwrite(b, sizeof(struct a), 10, fp) != sizeof(b))
            abort("Cannot write structure data);
    GETC                                                               GETC



    PROTOTYPE:

        int getc(FILE *fp)


    ARGUMENTS:

        fp      - File pointer to an input file


    RETURN VALUE:

        Value of a character read from the file (0-255)
        EOF (-1) if end of file or an error condition occurs


    DESCRIPTION:

          This function reads a single character from  an  input  file,  and
       returns it as a positive value in the range of 0 to 255.  A  full  16
       bit value is returned,  allowing the end  of  file  condition  to  be
       distinct from the character value 255.


    EXAMPLES:

        if((c = getc(input_file)) == EOF)
            abort("End of file encountered\n");
    GETCHAR                                                         GETCHAR



    PROTOTYPE:

        int getchar()


    ARGUMENTS:

        None


    RETURN VALUE:

        Value of a character read (0-255)
        EOF (-1) if end of file or an error condition occurs


    DESCRIPTION:

          This function reads a single character from the  "standard  input"
       file, and returns it as a positive value in the range of 0 to 255.  A
       full 16 bit value is returned,  allowing the end of file condition to
       be distinct from the character value 255.


    EXAMPLES:

        if((c = getchar()) == EOF)
            abort("End of file on TTY input\n");
    GETDIR                                                           GETDIR



    PROTOTYPE:

        int getdir(char pathname[])


    ARGUMENTS:

        pathname- Address of string to receive directory path


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          This function retrieves from the system the name of the  "current"
       directory path.

          The  "pathname"  string must be long enough to  hold  the  largest
       pathname supported by the system,  as indicated  by  the  "PATH_SIZE"
       definition in the "file.h" header file.


    EXAMPLES:

        getdir(&current_dir);
    GETENV                                                           GETENV



    PROTOTYPE:

        int getenv(char *ename, char *dest)


    ARGUMENTS:

        ename   - String containing name of environment variable
        dest    - Buffer to receive variable string value


    RETURN VALUE:

        1 if environment variable was found, 0 if not.


    DESCRIPTION:

          The GETENV function gets the value of a variable in  the  programs
       environment, and returns it as a string.  If the environment variable
       is not found, zero is returned,  and the destination buffer is set to
       a null (zero length) string.

          Use of this  function  allows  a  programs  fixed  parameters  and
       options to be specified once in environment variables, which may then
       be extracted by the program,  eliminating the need to  specify  those
       values every time the program is executed.

          When operating  MICRO-C  under  operating  systems  which  do  not
       support environment variables, this function will not be available.

          MICRO-C's  implementation  of  this  function  differs  from  ANSI
       standards in that the user must  provide  a  buffer  to  receive  the
       environment string.  This is because the actual  environment  is  not
       directly addressable by the application program.


    EXAMPLES:

        if(!getenv("COMSPEC", command))
            abort("No command processor defined\n");
    GETS                                                               GETS



    PROTOTYPE:

        char *gets(char *buffer)


    ARGUMENTS:

        buffer  - Pointer to string to receive line


    RETURN VALUE:

        Pointer to "buffer", or 0 if end of file


    DESCRIPTION:

          The  "gets"  function reads characters from the  "standard  input"
       input file,  and places them in the character buffer until one of two
       things happens:

          1) A NEWLINE character is encountered.

          2) The END of the file is encountered.

          The string is terminated with the standard NUL '\0' character. The
       trailing NEWLINE '\n' character is NOT included in the output buffer.


    EXAMPLES:

        puts("Enter input>");
        gets(input_line);
    HALT                                                               HALT



    PROTOTYPE:

        halt(int rc)


    ARGUMENTS:

        rc      - Termination return code


    RETURN VALUE:

        N/A - Function never returns


    DESCRIPTION:

          This function is simlar to  EXIT  except  that  ALL  DVM  programs
       terminated along with DVM ifself,  and the return code is passed back
       to the host system.


    EXAMPLES:

        halt(0);        /* success */
        halt(-1);       /* failure */
    ISALNUM                                                         ISALNUM



    PROTOTYPE:

        int isalnum(char c)


    ARGUMENTS:

        c       - Any character value


    RETURN VALUE:

        1 if 'c' is alphabetic or numeric
        0 if 'c' is not alphabetic or numeric


    DESCRIPTION:

          Returns  TRUE  (1)  if  the  passed  character  'c'  is  an  ASCII
       alphabetic letter in either upper or  lower  case  or  if  'c'  is  a
       numeric digit, otherwise FALSE (0) is returned.


    EXAMPLES:

        while(isalnum(*ptr))        /* Copy over symbol name */
            *name++ = *ptr++;
    ISALPHA                                                         ISALPHA



    PROTOTYPE:

        int isalpha(char c)


    ARGUMENTS:

        c       - Any character value


    RETURN VALUE:

        1 if 'c' is alphabetic
        0 if 'c' is not alphabetic


    DESCRIPTION:

          Returns  TRUE  (1)  if  the  passed  character  'c'  is  an  ASCII
       alphabetic letter in either upper or lower case,  otherwise FALSE (0)
       is returned.


    EXAMPLES:

        flag = isalpha(input_char);
    ISASCII                                                         ISASCII



    PROTOTYPE:

        int isascii(int c)


    ARGUMENTS:

        c       - Any character value


    RETURN VALUE:

        1 if 'c' is an ASCII character
        0 if 'c' is not an ASCII character


    DESCRIPTION:

          Returns TRUE  (1)  if the passed character  'c'  is a valid  ASCII
       character (0x00-0xFF), otherwise FALSE (0) is returned.


    EXAMPLES:

        if(!isascii(*ptr))
            abort("Invalid character data");
    ISCNTRL                                                         ISCNTRL



    PROTOTYPE:

        int iscntrl(char c)


    ARGUMENTS:

        c       - Any character value


    RETURN VALUE:

        1 if 'c' is a "control" character
        0 if 'c' is not a "control" character


    DESCRIPTION:

          Returns TRUE (1) is the passed character 'c' is an ASCII "control"
       character (0x00-0x1F or 0x7F), otherwise FALSE (0) is returned.


    EXAMPLES:

        putc(iscntrl(c) ? '.' : c, stdout); /* Display controls as '.' */
    ISDIGIT                                                         ISDIGIT



    PROTOTYPE:

        int isdigit(char c)


    ARGUMENTS:

        c       - Any character value


    RETURN VALUE:

        1 if 'c' is numeric
        0 if 'c' is not numeric


    DESCRIPTION:

          Returns TRUE  (1)  is the passed character  'c'  is an ASCII digit
       ('0'-'9'), otherwise FALSE (0) is returned.


    EXAMPLES:

        value = 0;
        while(isdigit(*ptr))
            value = (value * 10) + (*ptr++ - '0');
    ISGRAPH                                                         ISGRAPH



    PROTOTYPE:

        int isgraph(char c)


    ARGUMENTS:

        c       - Any character value


    RETURN VALUE:

        1 if 'c' is a non-space printable character
        0 if 'c' is a space or not printable


    DESCRIPTION:

          Returns TRUE (1)  if the passed character 'c' is a printable ASCII
       character other than  a  space  character,  otherwise  FALSE  (0)  is
       returned.


    EXAMPLES:

        putc(isgraph(c) ? c : '.', stdout);
    ISLOWER                                                         ISLOWER



    PROTOTYPE:

        int islower(char c)


    ARGUMENTS:

        c       - Any character value


    RETURN VALUE:

        1 if 'c' is lower case alphabetic
        0 if 'c' is not lower case alphabetic


    DESCRIPTION:

          Returns  TRUE  (1)  if  the  passed  character  'c'  is  an  ASCII
       alphabetic letter of lower case, otherwise FALSE (0) is returned.


    EXAMPLES:

        flag = islower(input_char);
    ISPRINT                                                         ISPRINT



    PROTOTYPE:

        int isprint(char c)


    ARGUMENTS:

        c       - Any character value


    RETURN VALUE:

        1 if 'c' is a printable character
        0 if 'c' is not printable


    DESCRIPTION:

          Returns TRUE (1)  if the passed character 'c' is a printable ASCII
       character (0x20-0xFE), otherwise FALSE (0) is returned.


    EXAMPLES:

        putc(isprint(c) ? c : '.', stdout);
    ISPUNCT                                                         ISPUNCT



    PROTOTYPE:

        int ispunct(char c)


    ARGUMENTS:

        c       - Any character value


    RETURN VALUE:

        1 if 'c' is a printable non-alphanumeric character
        0 if 'c' is not printable or alphanumeric


    DESCRIPTION:

          Returns TRUE (1)  if the passed character 'c' is a printable ASCII
       character which is not a letter of the alphabet or a  numeric  digit,
       otherwise FALSE (0) is returned.


    EXAMPLES:

        while(ispunct(*ptr))
            ++ptr;
    ISSPACE                                                         ISSPACE



    PROTOTYPE:

        int isspace(char c)


    ARGUMENTS:

        c       - Any character value


    RETURN VALUE:

        1 if 'c' is a space character (space, tab or newline)
        0 if 'c' is not a space character


    DESCRIPTION:

          Returns TRUE  (1)  if the passed character 'c'  is one of a space,
       tab or newline, otherwise FALSE (0) is returned.


    EXAMPLES:

        while(isspace(*ptr))
            ++ptr;
    ISUPPER                                                         ISUPPER



    PROTOTYPE:

        int isupper(char c)


    ARGUMENTS:

        c       - Any character value


    RETURN VALUE:

        1 if 'c' is upper case alphabetic
        0 if 'c' is not upper case alphabetic


    DESCRIPTION:

          Returns  TRUE  (1)  if  the  passed  character  'c'  is  an  ASCII
       alphabetic letter of upper case, otherwise FALSE (0) is returned.


    EXAMPLES:

        flag = isupper(input_char);
    ISXDIGIT                                                       ISXDIGIT



    PROTOTYPE:

        int isxdigit(char c)


    ARGUMENTS:

        c       - Any character value


    RETURN VALUE:

        1 if 'c' is a hexadecimal digit
        0 if 'c' is not a hexadecimal digit


    DESCRIPTION:

          Returns TRUE  (1)  is the passed character  'c'  is an valid ASCII
       hexadecimal digit ('0'-'9', 'A'-'F', 'a'-'f'), otherwise FALSE (0) is
       returned.


    EXAMPLES:

        value = 0;
        while(isxdigit(*ptr))
            value = (value * 16) +
                (isdigit(*ptr) ? *ptr++ - '0' : toupper(*ptr++) - ('A'-10));
    ITOA                                                               ITOA



    PROTOTYPE:

        int itoa(unsigned value, char *string, int base)


    ARGUMENTS:

        value   - Value to convert to ASCII
        string  - String to receive ASCII representation
        base    - Numerical base in which to perform conversion


    RETURN VALUE:

        Number of digits written to the string buffer


    DESCRIPTION:

          This function accepts  a  binary  value,  and  converts  it  to  a
       printable ASCII number, using the specified numerical base.

          The numerical base used must be at least 2.  If a base of  greater
       than 36 is used,  the symbolic "digits"  for values greater than  'Z'
       are defined by the progression of the ASCII character set.

          The value is normally treated as an unsigned quantity,  however if
       the base is specified as a negative number, signed output (using '-')
       will be performed for negative values.

          The destination string buffer must be large  enough  to  hold  all
       digits resulting from the conversion plus a terminating '\0'.


    EXAMPLES:

        itoa(value, buffer, 10);    /* Get value in unsigned base 10 */
        itoa(value, buffer, -10);   /* Get value in signed base 10 */
        itoa(value, buffer, 16);    /* Get value in hexadecimal */
        itoa(value, buffer, 2);     /* Get value in binary */
    LONGJMP                                                         LONGJMP



    PROTOTYPE:

        longjmp(int savenv[3], int rvalue)


    ARGUMENTS:

        savenv  - Save area for program context
        rvalue  - Value to be returned by "setjmp"


    RETURN VALUE:

        N/A - Function never returns


    DESCRIPTION:

          The  "longjmp"  function  causes  execution  to  transfer  to  the
       "setjmp"  call which set  up  the  "savenv"  variable.  The  "setjmp"
       function will appear to return the value of "rvalue".

          NOTE-1:  "longjmp"  may only be  used  from  within  the  function
       calling "setjmp"  or a function which has been called "beneath"  that
       function. IT MUST NOT BE USED AFTER THE FUNCTION CALLING "SETJMP" HAS
       TERMINATED.

          NOTE-2:  If "rvalue" is zero,  the function calling "setjmp"  will
       assume that it is returning from initialization. Unless you want this
       unusual behavior,  you should not pass a  return  value  of  zero  to
       "longjmp".

          See also SETJMP.


    EXAMPLES:

        if(getc(stdin) == ('C'-'@'))    /* If Control-C entered... */
            longjmp(savearea, 1);       /* Return to main function */
    LSEARCH                                                         LSEARCH



    PROTOTYPE:

        char *lsearch(char *k, char *t, unsigned e, unsigned s, int (*f)())


    ARGUMENTS:

        k   - Key to search for
        t   - Table to search
        e   - Number on entries in the table
        s   - Size of each entry
        f   - Pointer to function performing compare


    RETURN VALUE:

        Address of found record, or zero (0) if no match


    DESCRIPTION:

          Performs a linear search of the specified table,  looking for  the
       given key.  Since this is a linear search,  the table may be  in  any
       order.

          Any fixed format table can be used.  The key and a pointer to each
       entry to test are passed to the user supplied compare function, which
       must return 0 if equal,  <0 if the key  (first arg)  is less than the
       table entry, or >0 if the key is larger than the table entry.


    EXAMPLES:

        #include <stdio.h>
        int table[] = { 453, 762, 132, 982, 281, 185, 300, 737 };
        int test(int *a, int *b) { return *a - *b; }
        main(argc, char *argv[])
        {
            int key;
            key = atoi(argv[1]);
            printf("%04x", lsearch(&key, table, 8, sizeof(int), &test));
        }
    MALLOC                                                           MALLOC



    PROTOTYPE:

        char *malloc(unsigned size)


    ARGUMENTS:

        size    - Size of memory block to allocate (in bytes).


    RETURN VALUE:

        0       - Memory allocation failed
        !0      - Pointer to allocated memory block


    DESCRIPTION:

          The "malloc" function allocates a block of memory of the specified
       size from the heap, and returns a pointer to it. The allocated memory
       will have undefined content until written by the user  program.  This
       memory will remain allocated until it is explicitly released with the
       "free" function.


    EXAMPLES:

        if(!(ptr = malloc(BUFSIZ)))     /* Allocate a temporary buffer */
            abort("Not enough memory");
        do {                            /* Copy the file over */
            size = fget(ptr, BUFSIZ, in_fp);
            fput(ptr, size, out_fp); }
        while(size == BUFSIZ);
        free(ptr);                      /* Release temporary buffer */
    MAX                                                                 MAX



    PROTOTYPE:

        int max(int value1, int value2)


    ARGUMENTS:

        value1  - Any integer value
        value2  - Any integer value


    RETURN VALUE:

        The greater of "value1" or "value2"


    DESCRIPTION:

          The "max" function returns the higher of its two argument values.


    EXAMPLES:

        biggest = max(a, b);
    MEMCHR                                                           MEMCHR



    PROTOTYPE:

        char *memchr(char *mem, char c, unsigned size)


    ARGUMENTS:

        mem     - Block of memory to search
        c       - Character to look for
        size    - Size of block


    RETURN VALUE:

        Pointer to first character found or zero (0) if not found


    DESCRIPTION:

          This function searches the specified block of memory,  looking for
       the given character.

          If the character is located within the block,  a  pointer  to  the
       character is returned.

          If the character is not found before the specified  "size"  number
       of bytes have been examined, a zero is returned.


    EXAMPLES:

        if(ptr = memchr(block, '*', sizeof(block))
            printf("Block contains '*' at address: %04x\n", ptr);
    MEMCMP                                                           MEMCMP



    PROTOTYPE:

        int memcmp(unsigned char *b1, unsigned char *b2, unsigned size)


    ARGUMENTS:

        b1      - First memory block to compare
        b2      - Second memory block to compare
        size    - Size of blocks


    RETURN VALUE:

        0   - Blocks match exactly
        1   - Block1 is greater than string2
        -1  - Block2 is greater than string1


    DESCRIPTION:

          This  function  compares  two  blocks  of  memory   character   by
       character.  If the two blocks are identical for the specified  "size"
       number of bytes,  a zero  (0)  is returned.  If the  first  block  is
       greater than the second (as far as ASCII is concerned),  a one (1) is
       returned.  If the second block is greater,  a negative  one  (-1)  is
       returned.


    EXAMPLES:

        if(memcmp(old_block, new_block, sizeof(old_block))
            printf("New copy of block has been modified");
    MEMCPY                                                           MEMCPY



    PROTOTYPE:

        char *memcpy(char *dest, char *source, unsigned size)


    ARGUMENTS:

        dest    - Pointer to the destination
        source  - Pointer to the source
        size    - Number of bytes to copy


    RETURN VALUE:

        Pointer to destination memory block


    DESCRIPTION:

          The "memcpy" function will copy the specified number of bytes from
       the source to the destination.  If the source and destination  blocks
       overlap, the function may not copy the entire block correctly.


    EXAMPLES:

        memcpy(buffer1, buffer2, 256);
    MEMMOVE                                                         MEMMOVE



    PROTOTYPE:

        char *memmove(char *dest, char *source, unsigned size)


    ARGUMENTS:

        dest    - Pointer to the destination
        source  - Pointer to the source
        size    - Number of bytes to copy


    RETURN VALUE:

        Pointer to destination memory block


    DESCRIPTION:

          This function is similar to  "memcpy",  with the exception that it
       will copy overlapping blocks  of  memory  correctly.  It  is  however
       slightly larger than memcpy().


    EXAMPLES:

        memmove(buffer1, buffer2, 256);
    MEMSET                                                           MEMSET



    PROTOTYPE:

        char *memset(char *block, char value, unsigned size)


    ARGUMENTS:

        block   - Pointer to a block of memory
        value   - Value to initialize memory with
        size    - Number of bytes to initialize


    RETURN VALUE:

        Pointer to destination memory block


    DESCRIPTION:

          Sets a block of memory  beginning  at  the  pointer  "block",  for
       "size" bytes to the byte value "value".


    EXAMPLES:

        memset(buffer, 0, 100);
    MEMREADCODE1                                               MEMREADCODE1
    MEMREADCODE2                                               MEMREADCODE2



    PROTOTYPE:

        unsigned char MemReadCode1(unsigned address)    // Read a BYTE
        unsigned MemReadCode2(unsigned address)         // Read a WORD


    ARGUMENTS:

        address - Memory address to read


    RETURN VALUE:

        The value read from code memory.


    DESCRIPTION:

          In SMALL model,  the CODE portion of the  .DVM  program  image  is
       invisible the program other than that instruction opcodes are fetched
       from there.  There may be times that you  would  like  to  put  large
       static tables there freeing up data space.

          These functions provide READ access to code memory.

          NOTE that in TINY model, CODE memory is the same as DATA.


    EXAMPLES:

        void function(void)
        {   unsigned a; unsigned char c;
            asm " LD #data";    // Access code label by ASM
            a = nargs();        // Put ACC is variable
            while(c = MemReadCode1(a++))
                putc(c, stdout);
        } asm { // Inline ASM after function insures CODE
        data:   STRZ    "Large data table!"
        }
       MIN MIN



       PROTOTYPE:

          int min(int value1, int value2)


       ARGUMENTS:

          value1 - Any integer value
          value2 - Any integer value


       RETURN VALUE:

          The smaller of "value1" or "value2"


       DESCRIPTION:

          The "min" function returns the lower of its two argument values.


    EXAMPLES:

        least = min(a, b);
    MKDIR                                                             MKDIR



    PROTOTYPE:

        int mkdir(char *pathname)


    ARGUMENTS:

        pathname- Name of directory to create


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          The "mkdir"  function create a new directory on the disk under the
       specified path name.


    EXAMPLES:

        mkdir("subdir");
    NARGS                                                             NARGS



    PROTOTYPE:

        int nargs()


    ARGUMENTS:

        None


    RETURN VALUE:

        The number of arguments passed to the calling function


    DESCRIPTION:

          Returns the number of arguments passed to a "register" function.

          NOTE:  When calling  a  "register"  function,  MICRO-C  loads  the
       accumulator with the number of arguments just prior  to  calling  the
       function.  This  "nargs"  routine is simply a null  definition  which
       returns with the same value in the accumulator as was there  when  it
       was called.  Therefore  "nargs"  MUST BE THE FIRST ARITHMETIC  ENTITY
       EVALUATED WITHIN  THE  REGISTER  FUNCTION  or  the  contents  of  the
       accumulator will be lost. Some examples of "register" definitions and
       the use of "nargs" may be found in the library source code.


    EXAMPLES:

        first_arg = nargs() * 2 + &arguments;
    PEEK                                                               PEEK



    PROTOTYPE:

        (1) int peek(unsigned address)
        (2) int peek(unsigned h_addr, unsigned l_addr)
        (3) int peek(unsigned segment, unsigned offset)


    ARGUMENTS:

        segment - Memory segment
        offset  - Offset into segment
        h_addr  - High word of memory address
        l_addr  - Low word of memory address
        address - 16 bit memory address


    RETURN VALUE:

        The 8 bit value read from the given memory address


    DESCRIPTION:

          The "peek" function reads and returns a byte (8 bits)  from memory
       as an integer value between 0 and 255.

          Processors such as the 8080 or 6809 which address 64K of memory or
       less use form (1) of the function.

          Non-segmented processors addressing more  than  64K  such  as  the
       68000 use form (2) of the function.

          Processors employing a  "segmented"  architecture such as the 8086
       use form (3) of the function.


    EXAMPLES:

        while(peek(0)); /* Wait for flag to clear */
    PEEKW                                                             PEEKW



    PROTOTYPE:

        (1) int peekw(unsigned address)
        (2) int peekw(unsigned h_addr, unsigned l_addr)
        (3) int peekw(unsigned segment, unsigned offset)


    ARGUMENTS:

        segment - Memory segment
        offset  - Offset into segment
        h_addr  - High word of memory address
        l_addr  - Low word of memory address
        address - 16 bit memory address


    RETURN VALUE:

        The 16 bit value read from the given memory address


    DESCRIPTION:

          The  "peekw"  function reads and returns a  word  (16  bits)  from
       memory as an integer value between 0 and 65535 (-1).

          Processors such as the 8080 or 6809 which address 64K of memory or
       less use form (1) of the function.

          Non-segmented processors addressing more  than  64K  such  as  the
       68000 use form (2) of the function.

          Processors employing a  "segmented"  architecture such as the 8086
       use form (3) of the function.


    EXAMPLES:

        var = peekw(0);
    POKE                                                               POKE



    PROTOTYPE:

        (1) poke(unsigned address, int value)
        (2) poke(unsigned h_addr, unsigned l_addr, int value)
        (3) poke(unsigned segment, unsigned offset, int value)


    ARGUMENTS:

        segment - Memory segment
        offset  - Offset into segment
        h_addr  - High word of memory address
        l_addr  - Low word of memory address
        address - 16 bit memory address
        value   - Value to be written to memory


    RETURN VALUE:

        None


    DESCRIPTION:

          The "poke" function writes a byte (8 bit) value to memory.

          Processors such as the 8080 or 6809 which address 64K of memory or
       less use form (1) of the function.

          Non-segmented processors addressing more  than  64K  such  as  the
       68000 use form (2) of the function.

          Processors employing a  "segmented"  architecture such as the 8086
       use form (3) of the function.


    EXAMPLES:

        poke(0, 0);     /* Write 0 to location 0 */
    POKEW                                                             POKEW



    PROTOTYPE:

        (1) pokew(unsigned address, int value)
        (2) pokew(unsigned h_addr, unsigned l_addr, int value)
        (3) pokew(unsigned segment, unsigned offset, int value)


    ARGUMENTS:

        segment - Memory segment
        offset  - Offset into segment
        h_addr  - High word of memory address
        l_addr  - Low word of memory address
        address - 16 bit memory address
        value   - Value to be written to memory


    RETURN VALUE:

        None


    DESCRIPTION:

          The "pokew" function writes a word (16 bit) value to memory.

          Processors such as the 8080 or 6809 which address 64K of memory or
       less use form (1) of the function.

          Non-segmented processors addressing more  than  64K  such  as  the
       68000 use form (2) of the function.

          Processors employing a  "segmented"  architecture such as the 8086
       use form (3) of the function.


    EXAMPLES:

        pokew(0, 0);    /* Write 0 to locations 0 and 1 */
    PRINTF                                                           PRINTF



    PROTOTYPE:

        register int printf(char *format, arg, ...)


    ARGUMENTS:

        format  - Pointer to format string
        arg     - Argument as determined by format string
        ...     - Additional arguments may be required


    RETURN VALUE:

        Length of output string


    DESCRIPTION:

          The  "printf"  routine performs a formatted print to the  standard
       output device  (usually  system  console).  The  "format"  string  is
       written  with  the  arguments  substituted  for  special  "conversion
       characters".

          See "fprintf" for more information on format strings.

          MICRO-C's  implementation  of  this  function  differs  from  ANSI
       standards in that it is allows a maximum  of  132  characters  to  be
       output with each call.

          NOTE: This function uses a variable number of arguments,  and must
       be declared as "register" (See "stdio.h").


    EXAMPLES:

        printf("Hello world!!!\n");
        printf("File '%s', has %u lines\n", filename, num_lines);
    PUTC                                                               PUTC



    PROTOTYPE:

        putc(char c, FILE *fp)


    ARGUMENTS:

        c       - Any character value
        fp      - File pointer to an output file


    RETURN VALUE:

        c if successful, otherwise -1


    DESCRIPTION:

          This function writes the character  'c'  to the file indicated  by
       the file pointer 'fp'.


    EXAMPLES:

        putc('*', fp);
        putc('\n', stderr);
    PUTCHAR                                                         PUTCHAR



    PROTOTYPE:

        putchar(char c)


    ARGUMENTS:

        c       - Any character value


    RETURN VALUE:

        c if successful, otherwise -1


    DESCRIPTION:

          This function writes the character  'c'  to the  "standard output"
       file.  This  is  normally  the  user  tty,  unless  output  has  been
       redirected by the operating system.


    EXAMPLES:

        putchar('*');
        putchar('\n');
    PUTS                                                               PUTS



    PROTOTYPE:

        puts(char *string)


    ARGUMENTS:

        string  - Pointer to a character string


    RETURN VALUE:

        Positive value on success, -1 if error


    DESCRIPTION:

          The "puts"  function writes the specified string to the  "standard
       output" file,  followed by a NEWLINE character.  The zero terminating
       the string is NOT written.


    EXAMPLES:

        puts("Enter input>");
        gets(input_line);
    QSORT                                                             QSORT



    PROTOTYPE:

        qsort(char *base, unsigned e, unsigned s, int (*f)())


    ARGUMENTS:

        base    - Beginning address of memory structure
        e       - Number of elements in structure
        s       - Size of each element
        f       - Pointer to compare function


    RETURN VALUE:

        None


    DESCRIPTION:

          Sorts  the  specified  table  in  memory  using  the   "quicksort"
       algorithm.

          Any fixed format table can be used.  Pointers to  elements  to  be
       sorted are passed to the user supplied compare function,  which  must
       return 0 if equal,  <0 if the first argument is less than the second,
       or or >0 if the first argument is larger than the second.


    EXAMPLES:

        #include <stdio.h>
        #define NELEM(x) ( sizeof(x) / sizeof(x[]) )
        char t[7][4] = { "foo","abc","car","abe","zax","bar","fun" };
        extern int strcmp();
        main()
        {
            int i;
            qsort(t, NELEM(t), sizeof(t[]), &strcmp);
            for(i=0; i < NELEM(t); ++i)
                printf("%s\n", t[i]);
        }
    RAND                                                               RAND



    PROTOTYPE:

        unsigned rand()


    ARGUMENTS:

        None


    RETURN VALUE:

        A pseudo-random number in the range of 0 to 65535


    DESCRIPTION:

          The  "rand"  function calculates the next value of a pseudo-random
       sequence, based on a 16 bit unsigned "seed" value, which it maintains
       in the global variable  "RAND_SEED".  The new value is stored as  the
       new seed value, and also returned to the caller.

          Any  particular  sequence  may  be  repeated,  by  resetting   the
       "RAND_SEED" value.


    EXAMPLES:

        value = rand();
    RANDOM                                                           RANDOM



    PROTOTYPE:

        unsigned random(unsigned range)


    ARGUMENTS:

        range   - Range of values to return


    RETURN VALUE:

        A pseudo-random number in the range of 0 to (range-1)


    DESCRIPTION:

          The "random" function calculates the next value of a pseudo-random
       sequence, based on a 16 bit unsigned "seed" value, which it maintains
       in the global variable  "RAND_SEED".  The new value is stored as  the
       new seed value,  and is then divided by  the  "range"  parameter,  to
       obtain the remainder,  which is returned.  This results in  a  random
       number in the range of zero (0) to (limit - 1).

          Any  particular  sequence  may  be  repeated,  by  resetting   the
       "RAND_SEED" value.


    EXAMPLES:

        card = random(52);
    RDSETUP                                                         RDSETUP



    PROTOTYPE:

        int RDsetup(char letter, unsigned size)


    ARGUMENTS:

        letter  - letter for RAMdrive (case sensitive!)
        size    - RAMdrive size in 256 byte sectors


    RETURN VALUE:

        !0 if sucessful


    DESCRIPTION:

          Establishes temp storage accessible through file system (RamDrive)
       under the specified drive 'letter'. Note that this IS case sensitive!
          ie: if you RDinit('Y', 1000) you can access host files with 'y:'

          RAMdisk  'size'  is in 256 byte sectors.  Note that DVM  uses  one
       sector  (256 bytes)  as a "busy" sector map,  so the maximum size you
       can use is:
          (256x8)-1 sectors or about 512k.

          if either 'letter' or 'size' is 0 (zero) RAMdrive is released.

          Only supports 10 files which MUST be named '0' to '9'.

          No subdirectories are supported.

          Not all file operations are supported, only:
          fopen(), fclose(), rewind(), delete(),
          putc(), fputs(), fput(), fwrite(), fprintf(),
          getc(), fgets(), fget(), fread(), fscanf();


    EXAMPLES:

        RDsetup('Z', 2000);
    REALLOC                                                         REALLOC



    PROTOTYPE:

        char *realloc(char *block, unsigned size)


    ARGUMENTS:

        block   - Pointer to previously allocated block
        size    - Desired size of block


    RETURN VALUE:

        0       - Memory allocation failed
        !0      - Pointer to resized memory block


    DESCRIPTION:

          This function resizes a block of memory previously allocated  with
       malloc/calloc.  The block is adjusted (up or down) to the size given.
       The  block  may  be  relocated  in  memory  during  this  process  if
       necessary.

          Note that if the new allocation fails,  the original block will be
       freed,  however the data will remain intact.  You can recover  it  by
       immediately calling realloc() with the original block and block size.


    EXAMPLES:

        text_buffer = malloc(500);
        /* ... */
        text_buffer = realloc(test_buffer, 1000);
    REMOVE                                                           REMOVE



    PROTOTYPE:

        int remove(char *pathname)



    ARGUMENTS:

        pathname- Name of file to remove


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          The "remove" function removes an existing file from the disk.  Any
       disk space occupied by the file is released.


    EXAMPLES:

        remove("temp");
    RENAME                                                           RENAME



    PROTOTYPE:

        int rename(char *pathname, char *newname)


    ARGUMENTS:

        pathname- Name of file to rename
        newname - New name for file


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          This function changes the name of an existing file  to  the  ASCII
       string specified by newname.


    EXAMPLES:

        rename("output.dat", "output.bak");
    REWIND                                                           REWIND



    PROTOTYPE:

        int rewind(FILE *fp)


    ARGUMENTS:

        fp      - File pointer to an open file


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          This function resets the operating system internal file pointer so
       than any subsequent read or writes will be at the  beginning  of  the
       file.


    EXAMPLES:

        rewind(input_file);
    RMDIR                                                             RMDIR



    PROTOTYPE:

        int rmdir(char *pathname)


    ARGUMENTS:

        pathname- Name of directory to delete


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          This function removes a directory from the disk.  On most systems,
       the directory  must  be  empty  (contains  no  files)  otherwise  the
       function will fail.


    EXAMPLES:

        rmdir("subdir");
    RPSTART                                                         RPSTART
    RPEMD                                                             RPEND


    PROTOTYPE:

        int RPstart(char *name, unsigned size)
        void RPend(int rp) 


    ARGUMENTS:
        name    - Name of .EXE file to start as Remote Process
                    If the name does not include a PATH, the DVM home
                    directory is assumed.
        size    - size of oioe buffer to allocate
        rp      - RemoteProcess index returned by RDstart (0 = all)


    RETURN VALUE:

        RPstart - ID index for started remote process   (0=failed)


    DSCRIPTION:

          Starts/Stops a Remote Process,  a Windows .EXE which runs  outside
       of DVM. It is launched in a detatched state and is passed two numeric
       arguments:
          arg1: decimal file-Handle to read data from DVM.
          arg2: decimal file-Handle to write data to DVM.

          If the Remote Process is sucessfully launched,  RPstart() return a
       !0 ID value which can be used  to  refer  to  that  process.  If  the
       process fails to start, zero is returned.

          A Remote Process can be commanded to  terminate  at  any  time  by
       RDend(). RPend(0) will instruct all launched Remote Processes to end.


    EXAMPLES:

        Please refer to my DVMRP download for a detailed example.
    RPREAD                                                           RPREAD
    RPWRITE                                                         RPWROTE


    PROTOTYPE:

        int RDread(int rp, char *data, unsigned size)
        int RPwrite(int rp, char *data, unsigned size)


    ARGUMENTS:

        rp      - the Remote Process ID returned by RPstart()
        data    - Pointer to a binady data block to read/write
        size    - RPread:   The maximum size ddata block to accept
                  WRwrite:  The size of the data block to send


    DESCRIPTION:

          Reads/Writes a data block to the  DVM  host.  This  allows  a  DVM
       program to send command to and receive information back from a Remote
       Process.

          Normally a Remote Process should call RDread()  which  will  block
       until DVM gives it a command. Then the command should be performed an
       a response sent pack to DVM (which will wait for it).

          This allows you to easily implement what is effectively a  set  of
       library functions which  and  accessable  to  DVM  but  will  execute
       directly om the host operating system.


       EXAMPLES:

          Please refer to my DVMRP download for a detailed example.
       SCANF SCANF



       PROTOTYPE:

          register int scanf(char *format, arg1, arg2, ...)


       ARGUMENTS:

          format - Pointer to format string
          arg - Argument as determined by format string
          ... - Additional arguments may be required


       RETURN VALUE:

          The number of successful matches
          EOF (-1) if end of file or an error condition occurs


       DESCRIPTION:

          The  "scanf"  function reads and scans a line  from  the  standard
       input device (usually system console) for specific values. Values are
       read and assigned to  the  passed  argument  addresses  according  to
       special "conversion characters" in the "format" string.

          See "fscanf" for more information on format strings.

          MICRO-C's  implementation  of  this  function  differs  from  ANSI
       standards in that it does not scan more than a single line  from  the
       input device.

          NOTE: This function uses a variable number of arguments,  and must
       be declared as "register".


    EXAMPLES:

        do
            printf("Please enter your First & Last names, and your age?");
        while(scanf("%s %s %u", first_name, last_name, &age) != 3);
    SETCAPTURE                                                   SETCAPTURE



    PROTOTYPE:

        void setCapture(FILE *fp)


    ARGUMENTS:

        fp      - open write file to receive output


    RETURN VALUE:

        None


    DESCRIPTION:

          sets DVM to copy all program output  (via stdout &  stderr)  to  a
       file open for write.

          This provides a simple way to capture the screen of  programs  run
       by exec().

          A 'fp' value of 0 will stop the output capture. Note that attempts
       by a program to close the capture file will be ignored so you  should
       setCatpure(0) before closing the file.


    EXAMPLES:

        fp = fopen("OUTPUT.TXT", "wvq");
        setCapture(fp);
        exec("SUNPGM args");
        setCapture(0);
        fclose(fp);
    SETJMP                                                           SETJMP



    PROTOTYPE:

        int setjmp(int savenv[3])


    ARGUMENTS:

        savenv  - Save area for program context


    RETURN VALUE:

        0 is returned when actually called
        Value passed to "longjmp" is returned otherwise


    DESCRIPTION:

          When called,  the  "setjmp"  function stores the current execution
       state of the program into the passed integer array,  and returns  the
       value zero.

          The  "longjmp"  function may then be used to return the program to
       the "setjmp" call.  In this case, the value returned by "setjmp" will
       be the value which was passed to "longjmp".  This allows the function
       containing "setjmp" to determine which call to "longjmp"  transferred
       execution to it.

          See also LONGJMP.


    EXAMPLES:

        switch(setjmp(savearea)) {
            case 0 : printf("Longjmp has been set up"); break;
            case 1 : printf("Control-C Interrupt");     break;
            case 2 : printf("Reset command executed");  break;
            default: printf("Software error trap");     break; }
    SPRINTF                                                         SPRINTF



    PROTOTYPE:

        register int sprintf(char *dest, char *format, arg, ...)


    ARGUMENTS:

        dest    - Pointer to destination string
        format  - Pointer to format string
        arg     - Argument as determined by format string
        ...     - Additional arguments may be required


    RETURN VALUE:

        Length of output string


    DESCRIPTION:

          The  "sprintf"  routine performs a formatted print to a string  in
       memory. The "format" string is written to the destination string with
       the arguments substituted for special "conversion characters".

          See "fprintf" for more information on format strings.

          NOTE: This function uses a variable number of arguments,  and must
       be declared as "register" (See "stdio.h").


    EXAMPLES:

        sprintf(header_file, "/lib/%s.h", header_name);
    SQRT                                                               SQRT



    PROTOTYPE:

        int sqrt(unsigned value)


    ARGUMENTS:

        value   - Number for which to calculate square root


    RETURN VALUE:

        The integer square root (rounded up) of the argument value


    DESCRIPTION:

          The  SQRT  function  returns  the  smallest  number   which   when
       multiplied by itself will give a number equal to or larger  that  the
       argument value.

          MICRO-C's  implementation  of  this  function  differs  from  ANSI
       standards in that it operates only on integer values.


    EXAMPLES:

    /*
     * Draw a circle about point (x, y) of radius (r)
     */
    circle(x, y, r)
        int x, y, r;
    {
        int i, j, k, rs, lj;

        rs = (lj = r)*r;
        for(i=0; i <= r; ++i) {
            j = k = sqrt(rs - (i*i));
            do {
                plot_xy(x+i, y+j);
                plot_xy(x+i, y-j);
                plot_xy(x-i, y+j);
                plot_xy(x-i, y-j); }
            while(++j < lj);
            lj = k; }
    }
    SSCANF                                                           SSCANF



    PROTOTYPE:

        register int sscanf(char *input, char *format, arg1, arg2, ...)


    ARGUMENTS:

        input   - Pointer to input string
        format  - Pointer to format string
        arg     - Argument as determined by format string
        ...     - Additional arguments may be required


    RETURN VALUE:

        The number of successful matches


    DESCRIPTION:

          The  "sscanf"  function scans a  string  in  memory  for  specific
       values. Values are read and assigned to the passed argument addresses
       according to special "conversion characters" in the "format" string.

          See "fscanf" for more information on format strings.

          NOTE: This function uses a variable number of arguments,  and must
       be declared as "register".


    EXAMPLES:

        sscanf(pathname,"/%s/%s", directory, filename);
    STPCPY                                                           STPCPY



    PROTOTYPE:

        char *stpcpy(char *dest, char *source)


    ARGUMENTS:

        dest    - Pointer to destination string
        source  - Pointer to source string


    RETURN VALUE:

        Pointer to zero terminating destination string


    DESCRIPTION:

          This function copies the source string to the destination  string.
       All data is copied up to and including the zero byte which terminates
       the string.  The destination string must be large enough to hold  the
       entire source.


    EXAMPLES:

        stpcpy(filename, argv[1]);
    STRBEG                                                           STRBEG



    PROTOTYPE:

        int strbeg(char *string1, char *string2)


    ARGUMENTS:

        string1 - Pointer to character string to test
        string2 - Pointer to character string to check for


    RETURN VALUE:

        0   - String1 does not begin with string2
        1   - String1 begins with string2


    DESCRIPTION:

          Tests the passed "string1" to determine if it begins with the same
       data as is contained within "string2".


    EXAMPLES:

        if(strbeg(command, "delete"))
            delete_file(&command[6]);
    STRCAT                                                           STRCAT



    PROTOTYPE:

        char *strcat(char *dest, char *source)


    ARGUMENTS:

        dest    - Pointer to destination string
        source  - Pointer to source string


    RETURN VALUE:

        Pointer to destination string


    DESCRIPTION:

          This function concatenates the source string on to the tail of the
       destination string.  The destination string must be large  enough  to
       hold the entire contents of both strings.


    EXAMPLES:

        strcat(program_name, ".c");
    STRCHR                                                           STRCHR



    PROTOTYPE:

        char *strchr(char *string, char chr)


    ARGUMENTS:

        string  - Pointer to a character string
        chr     - Character to look for


    RETURN VALUE:

        Pointer to the first occurrence of 'chr' in 'string'
        Zero (0) if character was not found


    DESCRIPTION:

          Searches the  passed  string  for  the  first  occurrence  of  the
       specified character.  If the character is found,  a  pointer  to  its
       position in the string is returned.  If the character is not found, a
       null pointer is returned.

          The null (0)  character is treated as valid data by this function,
       thus:
          strchr(string, 0);

       would return the position of the null terminator of the string.


    EXAMPLES:

        comma = strchr(buffer, ',');
    STRCMP                                                           STRCMP



    PROTOTYPE:

        int strcmp(char *string1, char *string2)


    ARGUMENTS:

        string1 - Pointer to first string
        string2 - Pointer to second string


    RETURN VALUE:

        0   - Strings match exactly
        1   - String1 is greater than string2
        -1  - String2 is greater than string1


    DESCRIPTION:

          This function compares two strings character by character.  If the
       two strings are identical,  a zero  (0)  is returned.  If  the  first
       string is greater than the second  (as far as ASCII is concerned),  a
       one (1) is returned.  If the second string is greater, a negative one
       (-1) is returned.


    EXAMPLES:

        if(!strcmp(command, "quit"))
            exit(0);
    STRCPY                                                           STRCPY



    PROTOTYPE:

        char *strcpy(char *dest, char *source)


    ARGUMENTS:

        dest    - Pointer to destination string
        source  - Pointer to source string


    RETURN VALUE:

        Pointer to destination string


    DESCRIPTION:

          This function copies the source string to the destination  string.
       All data is copied up to and including the zero byte which terminates
       the string.  The destination string must be large enough to hold  the
       entire source.


    EXAMPLES:

        strcpy(filename, argv[1]);
    STRCSPN                                                         STRCSPN



    PROTOTYPE:

        int strcspn(char *string, char *set)


    ARGUMENTS:

        string  - String to test
        set     - Set of characters to look for


    RETURN VALUE:

        Length of string segment containing chars NOT in set.


    DESCRIPTION:

          Scans a  string  for  an  "initial  segment"  not  containing  any
       characters from the specified set.  The value returned is the  number
       of characters at the beginning of the specified string which  do  not
       occur in the specified set.


    EXAMPLES:

        cmd_length = strcspn(command, " \t,.");
    STRDUP                                                           STRDUP



    PROTOTYPE:

        char *strdup(char *string)


    ARGUMENTS:

        string  - String to duplicate


    RETURN VALUE:

        Pointer to newly allocated character string
        Zero (0) of memory allocation failed


    DESCRIPTION:

          Allocates a buffer in memory (via malloc)  long enough to hold the
       specified string  (complete with  '\0'  terminator),  and copies  the
       string into it.


    EXAMPLES:

        ptr = strdup(command_line);     /* Copy because strtok modifies */
        ptr1 = strtok(ptr, " \t");
        while(ptr1) {
            process_token(ptr1);
            ptr1 = strtok(0, " \t"); }
        free(ptr);
    STRICMP                                                         STRICMP



    PROTOTYPE:

        int stricmp(char *string1, char *string2)


    ARGUMENTS:

        string1 - Pointer to first string
        string2 - Pointer to second string


    RETURN VALUE:

        0   - Strings match exactly
        1   - String1 is greater than string2
        -1  - String2 is greater than string1


    DESCRIPTION:

          This function compares two strings character by character  without
       case sensitivity. If the two strings are identical (except for case),
       a zero  (0)  is returned.  If the first string is  greater  than  the
       second (as far as ASCII is concerned), a one (1) is returned.  If the
       second string is greater, a negative one (-1) is returned.


    EXAMPLES:

        if(!stricmp(command, "quit"))
            exit(0);
    STRLEN                                                           STRLEN



    PROTOTYPE:

        int strlen(char *string)


    ARGUMENTS:

        string  - Pointer to a character string


    RETURN VALUE:

        The length of the string


    DESCRIPTION:

          Returns the length in character of the passed string.  The  length
       does not include the zero byte which terminates the string.


    EXAMPLES:

        length = strlen(command);
    STRLWR                                                           STRLWR



    PROTOTYPE:

        strlwr(char *string)


    ARGUMENTS:

        string  - String to convert to lower case


    RETURN VALUE:

        None


    DESCRIPTION:

          This function converts any  characters  in  the  specified  string
       which were originally in UPPER case to LOWER case. After the function
       has completed,  all alphabetic characters in the string  will  be  in
       LOWER case.


    EXAMPLES:

        strlwr(command);
        if(!strcmp(command, "quit"))
            exit(0);
    STRNCAT                                                         STRNCAT



    PROTOTYPE:

        char *strncat(char *dest, char *source, unsigned length)


    ARGUMENTS:

        dest    - Pointer to destination string
        source  - Pointer to source string
        length  - Maximum number of characters to copy


    RETURN VALUE:

        Pointer to destination string


    DESCRIPTION:

          This function concatenates the source string on to the tail of the
       destination string.  If the source string exceeds  "length"  bytes in
       size, only that many characters are copied.


    EXAMPLES:

        strncat(path, filename, 64);
    STRNCMP                                                         STRNCMP



    PROTOTYPE:

        int strncmp(char *string1, char *string2, unsigned length)


    ARGUMENTS:

        string1 - Pointer to first string
        string2 - Pointer to second string
        length  - Number of bytes to compare


    RETURN VALUE:

        0   - Strings match exactly
        1   - String1 is greater than string2
        -1  - String2 is greater than string1


    DESCRIPTION:

          This function compares two strings character  by  character  until
       either a difference is detected,  or  "length"  characters have  been
       compared.  If the two string portions are identical,  a zero  (0)  is
       returned.  If the first string is greater than the second  (as far as
       ASCII is concerned),  a one (1) is returned.  If the second string is
       greater, a negative one (-1) is returned.


    EXAMPLES:

        len = strlen(buffer) - 3;
        for(i=1; i < len; ++i)
            if(strncmp(&buffer[i], "***", 3)
                abort("Found three stars\n");
    STRNCPY                                                         STRNCPY



    PROTOTYPE:

        char *strncpy(char *dest, char *source, unsigned length)


    ARGUMENTS:

        dest    - Pointer to destination string
        source  - Pointer to source string
        length  - Number of bytes to copy


    RETURN VALUE:

        Pointer to destination string


    DESCRIPTION:

          This function copies "length" characters from the source string to
       the  destination  string.  If  the  source  string  is  shorter  than
       "length", the destination string is padded with nulls.  If the source
       string is longer than "length", only that many characters are copied,
       and the destination string is NOT zero terminated.


    EXAMPLES:

        strncpy(filename, argv[1], 64);
    STRNICMP                                                       STRNICMP



    PROTOTYPE:

        int strnicmp(char *string1, char *string2, unsigned length)


    ARGUMENTS:

        string1 - Pointer to first string
        string2 - Pointer to second string
        length  - Number of bytes to compare


    RETURN VALUE:

        0   - Strings match exactly
        1   - String1 is greater than string2
        -1  - String2 is greater than string1


    DESCRIPTION:

          This function compares two strings character by character  without
       case sensitivity until either a difference is detected,  or  "length"
       characters have  been  compared.  If  the  two  string  portions  are
       identical (except for case),  a zero  (0)  is returned.  If the first
       string is greater than the second  (as far as ASCII is concerned),  a
       one (1) is returned.  If the second string is greater, a negative one
       (-1) is returned.


    EXAMPLES:

        len = strlen(buffer) - 3;
        for(i=1; i < len; ++i)
            if(strnicmp(&buffer[i], "abc", 3)
                abort("Found 'ABC'\n");
    STRNSET                                                         STRNSET



    PROTOTYPE:

        strnset(char *string, char c, unsigned length)


    ARGUMENTS:

        string  - String to set
        c       - character value to use to set string
        length  - maximum number of characters to set


    RETURN VALUE:

        None


    DESCRIPTION:

          Sets the specified maximum number  of  characters  in  the  passed
       string  (up till the  '\0'  terminator),  to the specified  character
       value.


    EXAMPLES:

        static char s[6] = { "abcd" };  /* s == 'a','b','c','d',0,0 */
        strnset(s, '*', 3);             /* s == '*','*','*','d',0,0 */
    STRPBRK                                                         STRPBRK



    PROTOTYPE:

        char *strpbrk(char *string, char *set)


    ARGUMENTS:

        string  - String to test
        set     - Set of characters to look for


    RETURN VALUE:

        Pointer to first character from set occurring in string
        Zero (0) if no characters from the set were found


    DESCRIPTION:

          Scans the  specified  string  for  the  first  occurrence  of  any
       character in the given set.


    EXAMPLES:

        if(strpbrk(command, "()[]{}"))
            printf("Brackets of any form are not supported!");
    STRRCHR                                                         STRRCHR



    PROTOTYPE:

        char *strrchr(char *string, char chr)


    ARGUMENTS:

        string  - Pointer to a character string
        chr     - Character to look for


    RETURN VALUE:

        Pointer to the last occurrence of 'chr' in 'string'
        Zero (0) if character was not found


    DESCRIPTION:

          Searches  the  passed  string  for  the  last  occurrence  of  the
       specified character.  If the character is found,  a  pointer  to  its
       position in the string is returned.  If the character is not found, a
       null pointer is returned.


    EXAMPLES:

        last_comma = strchr(buffer, ',');
    STRREV                                                           STRREV



    PROTOTYPE:

        strrev(char *string)


    ARGUMENTS:

        string  - character string to reverse


    RETURN VALUE:

        None


    DESCRIPTION:

          Reverses the ordering of the characters in the specified string in
       memory.


    EXAMPLES:

        static char s[] = { "ABC" };    /* s == 'A','B','C',0 */
        strrev(s);                      /* s == 'C','B','A',0 */
    STRSET                                                           STRSET



    PROTOTYPE:

        strset(char *string, char c)


    ARGUMENTS:

        string  - String to set
        c       - character value to use to set string


    RETURN VALUE:

        None


    DESCRIPTION:

          Sets all characters  in  the  passed  string  (up  till  the  '\0'
       terminator), to the specified character value.


    EXAMPLES:

        static char s[6] = { "abcd" };  /* s == 'a','b','c','d',0,0 */
        strset(s, '*');                 /* s == '*','*','*','*',0,0 */
    STRSPN                                                           STRSPN



    PROTOTYPE:

        int strspn(char *string, char *set


    ARGUMENTS:

        string  - String to test
        set     - Set of characters to look for


    RETURN VALUE:

        Length of string segment containing only characters in set.


    DESCRIPTION:

          Scans a string for an "initial segment" containing only characters
       from  the  specified  set.  The  value  returned  is  the  number  of
       characters at the beginning of the specified string  which  occur  in
       the specified set.


    EXAMPLES:

        digit_length = strspn(command, "0123456789");
    STRSTR                                                           STRSTR



    PROTOTYPE:

        char *strstr(char *string1, char *string2)


    ARGUMENTS:

        string1 - Pointer to character string to test
        string2 - Pointer to substring to search for


    RETURN VALUE:

        Pointer to substring, or 0 if not found


    DESCRIPTION:

          Searches the passed  "string1"  for the first  occurrence  of  the
       passed  "string2".  If found,  a pointer to  the  beginning  of  that
       substring within "string1" is returned.


    EXAMPLES:

        if(ptr = strstr(command, "delete"))
            delete_file(&ptr[6]);
    STRTOK                                                           STRTOK



    PROTOTYPE:

        char *strtok(char *string, char *delim)


    ARGUMENTS:

        string  - String to parse (NULL = continue parsing last string)
        delim   - Delimiter characters


    RETURN VALUE:

        Pointer to token parsed from string
        Zero (0) if no more tokens are available


    DESCRIPTION:

          Parses a  "token"  from the specified string,  using the specified
       set of delimiters.

          Any delimiter characters  at  the  beginning  of  the  string  are
       skipped, then all non-delimiter characters are preserved,  and a '\0'
       terminator is inserted at the  end  of  the  non-delimiter  character
       string.  A pointer to the first  non-delimiter  character  string  is
       returned.

          If called with a NULL (0) pointer to "string",  this function will
       parse the next available token from the previous argument string.

       NOTE: The argument "string" is modified by this function.


    EXAMPLES:

        ptr = strtok("this is.a,test", " .,");  /* ptr -> "this" */
        ptr = strtok(NULL, " .,");              /* ptr -> "is"   */
        ptr = strtok(NULL, " .,");              /* ptr -> "a"    */
        ptr = strtok(NULL, " .,");              /* ptr -> "test" */
        ptr = strtok(NULL, " .,");              /* ptr == NULL   */
    STRUPR                                                           STRUPR



    PROTOTYPE:

        strupr(char *string)


    ARGUMENTS:

        string  - String to convert to upper case


    RETURN VALUE:

        None


    DESCRIPTION:

          This function converts any  characters  in  the  specified  string
       which were originally in LOWER case to UPPER case. After the function
       has completed,  all alphabetic characters in the string  will  be  in
       UPPER case.


    EXAMPLES:

        strlwr(command);
        if(!strcmp(command, "QUIT"))
            exit(0);
    SYSTEM                                                           SYSTEM



    PROTOTYPE:

        int system(char *command)


    ARGUMENTS:

        command - A system command to be executed


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          The SYSTEM function accepts any  operating  system  command  as  a
       string parameter,  and passes that command to the operating system to
       be executed.

          When the command has terminated,  execution  will  resume  in  the
       MICRO-C program, with the statement following the call to SYSTEM.


    EXAMPLES:

        system("DEL *.TMP");
    TOLOWER                                                         TOLOWER



    PROTOTYPE:

        char tolower(char c)


    ARGUMENTS:

        c   - Any character value


    RETURN VALUE:

        The value of 'c', converted to lower case


    DESCRIPTION:

          Returns the value of 'c' converted to lower case.  If 'c' is not a
       letter of upper case,  no change is made,  and the original value  of
       'c' is returned.


    EXAMPLES:

        input_char = tolower(getc(stdin));
    TOUPPER                                                         TOUPPER



    PROTOTYPE:

        char toupper(char c)


    ARGUMENTS:

        c   - Any character value


    RETURN VALUE:

        The value of 'c', converted to upper case


    DESCRIPTION:

          Returns the value of 'c' converted to upper case.  If 'c' is not a
       letter of lower case,  no change is made,  and the original value  of
       'c' is returned.


    EXAMPLES:

        putc(toupper(output_char), stdout);
    UNLINK                                                           UNLINK



    PROTOTYPE:

        int unlink(char *pathname)



    ARGUMENTS:

        pathname- Name of file to remove


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          The "unlink" function removes an existing file from the disk.  Any
       disk space occupied by the file is released.


    EXAMPLES:

        unlink("temp");
    _FORMAT_                                                       _FORMAT_



    PROTOTYPE:

        int _format_(int *argptr, char *dest)


    ARGUMENTS:

        argptr  - Pointer to stacked function arguments
        dest    - String to receive formatted information


    RETURN VALUE:

        Length of output string


    DESCRIPTION:

          The  "_format_"  function  perform  "printf"  type  formatting  on
       stacked function arguments, and places the output in a string.  It is
       useful to create customized formatted output functions.

          Note that most functions using _format_ will require  an  argument
       count,  and therefore should be declared  "register".  Also note that
       _format_(nargs() ...) should be the FIRST operation performed in such
       functions.

          The exact computation to obtain the  stack  argument  pointer  may
       differ on machines  with  different  stack  organizations.  For  most
       machines which use a high-to-low stack,  the equation is "nargs() * 2
       + &args".


    EXAMPLES:

        #define LINE_SIZE 132   /* Maximum output width */
        register err_printf(unsigned args)
        {
            char buffer[LINE_SIZE+1];
            unsigned length;

            length = _format_(nargs() * 2 + &args, buffer);
            fputs(buffer, stderr);
            return length;
        }
    MICRO-C PC Library                                               Page: 8



                      +---------------------------------+
                      |                                 |
                      |  *****************************  |
                      |  * The IBM-PC/MS-DOS library *  |
                      |  *****************************  |
                      |                                 |
                      +---------------------------------+










    3. IBM-PC/MS-DOS LIBRARY

          The  library  functions  described  on  the  following  pages  are
       available only under  the  MS-DOS  operating  system,  on  IBM-PC  or
       compatible systems.

          These routines perform operations which are closely  tied  to  the
       8086 family  of  processors,  the  IBM-PC  hardware,  or  the  MS-DOS
       operating system,  and are therefore impractical to  implement  on  a
       "general" basis.
    ALLOC_SEG                                                     ALLOC_SEG



    PROTOTYPE:

        int alloc_seg(int size)


    ARGUMENTS:

        size    - Number of 16 byte paragraphs to allocate


    RETURN VALUE:


        0       - Not enough free memory available
        !0      - The segment address of the allocated memory


    DESCRIPTION:

          The "alloc_seg" function allocates a 'segment' of memory from DOS.
       The size is given in 16 byte "paragraphs".  The allocated memory will
       be outside of the data memory available to the MICRO-C  program,  and
       therefore must be accessed via assembly language functions,  or  with
       the "peek", "poke" or "copy_seg" library functions.


    EXAMPLES:

        if(!(aseg = alloc_seg(4096)))   /* Get a 64K data segment */
            abort("Not enough memory!!!");
        set_es(aseg);               /* Set up extra segment */
        function();                 /* Invoke assembler function */
        free_seg(aseg);             /* Release the memory */
    BEEP                                                               BEEP



    PROTOTYPE:

        beep(unsigned freq, unsigned length)


    ARGUMENTS:

        freq    - frequency (in hertz) of tone to generate
        length  - Length (in milliseconds) of tone


    RETURN VALUE:

        None


    DESCRIPTION:

          This function generates a tone of the specified frequency, for the
       specified duration. It is useful for giving an audible signal.


    EXAMPLES:

        beep(1000, 1000);   /* 1000Hz tone for 1000ms (1 second) */
    COPY_SEG                                                       COPY_SEG



    PROTOTYPE:

        copy_seg(int dseg, int doffset, int sseg, int soffset, int size)


    ARGUMENTS:

        dseg    - Destination segment
        doffset - Destination offset
        sseg    - Source segment
        soffset - Source offset
        size    - Number of bytes to copy


    RETURN VALUE:

        None


    DESCRIPTION:

          This function  perform  a  copy  between  80X86  processor  memory
       segments. A number of bytes equal to "size" is copied from the source
       segment and offset to the destination segment and offset.


    EXAMPLES:

        /* Save the video display contents */
        copy_seg(get_ds(), buffer, _V_BASE, 0, (25*80)*2);
    DELAY                                                             DELAY
    SLEEP                                                             SLEEP



    PROTOTYPE:

        delay(int msec)
        sleep(int msec)


    ARGUMENTS:

        msec    - Number of milliseconds to wait


    RETURN VALUE:

        None


    DESCRIPTION:

          Pauses for the specified number of milliseconds.  This function is
       limited to the accuracy of the BIOS clock,  which  operates  at  18.2
       ticks per second.


    EXAMPLES:

        delay(1000);        /* Wait one second */
    EXEC                                                               EXEC



    PROTOTYPE:

        int exec(char *exefile, char *args)


    ARGUMENTS:

        exefile - Full pathname of a '.COM' or '.EXE' file
        args    - Command tail containing arguments


    RETURN VALUE:

        0 if successful, otherwise an MS-DOS error code


    DESCRIPTION:

          The "exec"  function causes MS-DOS to suspend the execution of the
       MICRO-C program,  and then to execute the indicated '.EXE'  or '.COM'
       program file.  When that program terminates, execution of the MICRO-C
       program will resume.

          This is a low level interface to the MS-DOS 'EXEC'  function,  and
       as such, it does not search your PATH, does not process '.BAT' files,
       nor provide any I/O redirection facilities.  If you want to make  use
       of these features  (which are provided  by  'COMMAND.COM'),  use  the
       higher level 'SYSTEM' function.


    EXAMPLES:

        printf("Type 'EXIT' to return to the MICRO-C program\n");
        exec("C:\\COMMAND.COM", "");    /* Start up a sub-shell */
    FREE_SEG                                                       FREE_SEG



    PROTOTYPE:

        int free_seg(int segment)


    ARGUMENTS:

        segment - A previously allocated segment of memory


    RETURN VALUE:

        0       - The segment was released
        !0      - DOS error code


    DESCRIPTION:

          The  "free_seg"  function releases a segment of memory  previously
       allocated by  "alloc_seg",  and returns it to the  operating  system.
       This should be used whenever your program has finished with a segment
       of extra memory which it has allocated.


    EXAMPLES:

        aseg = alloc_seg(4096);         /* Allocate a 64K segment */
        set_es(aseg);                   /* Set up extra segment */
        function();                     /* Call assembler function */
        free_seg(aseg);                 /* Release the memory */
    GET_DATE                                                       GET_DATE



    PROTOTYPE:

        get_date(int &day, int &month, int &year)


    ARGUMENTS:

        &day    - Address of integer to receive day (1-31)
        &month  - Address of integer to receive month (1-12)
        &year   - Address of integer to receive year (1980-2099)


    RETURN VALUE:

        Day of week (0=Sun ... 6=Sat)


    DESCRIPTION:

          This function gets the current system  date  in  day,  month,  and
       year.


    EXAMPLES:

        get_date(&day, &month, &year);
        printf("%s %u, %u", months[month], day, year);
    GET_DRIVE                                                     GET_DRIVE



    PROTOTYPE:

        int get_drive()


    ARGUMENTS:

        None


    RETURN VALUE:

        The currently active (default) disk drive (0=A, 1=B, 2=C, ...)


    DESCRIPTION:

          The  "get_drive"  function returns the drive index  (0-n)  of  the
       currently active or "default" MS-DOS disk drive.


    EXAMPLES:

        old_drive = get_drive();
        set_drive(new_drive);
    GET_TIME                                                       GET_TIME



    PROTOTYPE:

        get_time(int &hour, int &minute, int &second)


    ARGUMENTS:

        &hour   - Address of integer to receive hour (0-23)
        &minute - Address of integer to receive minute (0-59)
        &second - Address of integer to receive second (0-59)


    RETURN VALUE:

        None


    DESCRIPTION:

          This function gets the current system time in hours,  minutes  and
       seconds.


    EXAMPLES:

        get_time(&hour, &minute, &second);
        printf("%02:%02:%02", hour, minute, second);
    KEYBOARD                                                       KEYBOARD



    PROTOTYPES:

        int kbget()
        int kbhit()
        int kbtst()

    ARGUMENTS:

        None


    RETURN VALUE:

        0   - No keycode available
        !0  - Keycode received from keyboard


    DESCRIPTION:

          Function to provide direct access to the BIOS keyboard handler.

          kbget()  waits for a key to be pressed,  then removes it from  the
       keyboard buffer and returns the ASCII  code  for  that  key  (0-127).
       Extended NON-ASCII keys will result in the  keyboard  scancode  being
       returned (>256).

          kbhit()  tests for a key being available,  and if  one  is  found,
       returns the keyboard scancode for that key WITHOUT removing  it  from
       the keyboard buffer.  If no key is available, zero is returned.  Note
       that kbhit() returns a scancode even for ASCII keys.

          kbtst() is a combination of the above two.  If a key is available,
       It behaves like kbget(), removing it and returning the ASCII code. If
       no key is available, it behaves like kbhit() and returns zero.

          The CONTROL-BREAK key combination which generates a BIOS  scancode
       of 0 is translated to -1 (0xFFFF) by these functions.


    EXAMPLES:

        if(kbtst == 0x1B)
            break;      /* Break out of loop if ESCAPE pressed */
    RESIZE_SEG                                                   RESIZE_SEG



    PROTOTYPE:

        int resize_seg(int segment, int size)


    ARGUMENTS:

        segment - A previously allocated segment of memory
        size    - Desired size (in 16 byte paragraphs)


    RETURN VALUE:

        0       - The segments size has been adjusted
        !0      - DOS error code


    DESCRIPTION:

          The  "resize_seg"  function provides a method of changing the size
       of a segment of memory previously allocated via  "alloc_seg".  If not
       enough memory is available,  the function will fail with  a  non-zero
       return value.

          This function may also be used to adjust the memory allocation  of
       the programs image, by passing it the segment address of the programs
       own PSP. This value is available in the external variable "PSP".

          MICRO-C normally allocates 64K for programs compiled in  the  TINY
       model,  and (64K + (256 byte PSP)  +  (size of executable code))  for
       programs compiled in the SMALL model. This allocation should NEVER be
       reduced,  however you may enlarge it if your program wishes to access
       additional data immediately following its own DATA/STACK segment.


    EXAMPLES:

        extern int PSP;

        main()
        {
            if(resize_seg(PSP, 8192))   /* Append 64K buffer */
                abort("Not enough memory!!!");
            ...     /* Remainder of program */
        }
    SET_DRIVE                                                     SET_DRIVE



    PROTOTYPE:

        int set_drive(int drive)


    ARGUMENTS:

        Drive   - New drive index (0=A, 1=B, 2=C ...)


    RETURN VALUE:

        The total number of "logical" disk drives in the system


    DESCRIPTION:

          The  "set_drive"  function sets the disk drive  indicated  by  the
       "drive" index  (0-x)  to be the currently active or "default"  MS-DOS
       disk drive.


    EXAMPLES:

        old_drive = get_drive();
        set_drive(new_drive);
    VCLEOL                                                           VCLEOL



    PROTOTYPE:

        Vcleol()


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          This function clears the IBM PC  video  screen  from  the  current
       cursor position to the end of a line.

          You must "#include video.h",  and execute  "VOPEN"  prior to using
       this function.


    EXAMPLES:

        Vprintf("Input> ");     /* Display a prompt */
        Vcleol();               /* Clear remainder of input line */
    VCLEOS                                                           VCLEOS



    PROTOTYPE:

        Vcleos()


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          This function clears the IBM PC  video  screen  from  the  current
       cursor position to the end of a screen.

          "VOPEN" MUST be called prior to using this function.


    EXAMPLES:

        Vgotoxy(0, 10);         /* position at line 11 */
        Vcleos();               /* Clear lower part of screen */
    VCLSCR                                                           VCLSCR



    PROTOTYPE:

        Vclscr()


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          This function clears the entire IBM PC video screen and resets the
       cursor position to the top left hand corner.

          "VOPEN" MUST be called prior to using this function.


    EXAMPLES:

        if(c = 0x1b) {          /* Escape command */
            Vclscr();       /* Clear the screen */
            Vprintf("%s has terminated\n", argv[0]);
            exit(-1); }
    VCOLOR                                                           VCOLOR



    PROTOTYPR:

        void Vcolor(unsigned char color)


    ARGUMENTS:

        color   - Color to write to screen


    RETURN VALUE:

        None


    DESCRIPTION:

          This function sets the video color given  to  character  cells  in
       subsequent Vxxx() video write functions.


    EXAMPLES:

        Vcolor(0x70);   // Set REVERSE video
    VGETC                                                             VGETC
    VGETK                                                             VGETK



    PROTOTYPE:

        int Vgetc()
        int Vgetk()



    ARGUMENTS:

        None


    RETURN VALUE:

        0-127   - ASCII value of key pressed
        < 0     - Special function key as defined in "video.h"


    DESCRIPTION:

          The VGETC function waits until a key  is  pressed  on  the  system
       console, and returns its value.

          Note that due to the  buffering  of  the  IBM-PC  keyboard,  every
       keypress will be reported, even if the VGETC function is called after
       a key is pressed and released.

          VGETK performs the same function except that the keypad keys which
       are reported with different codes under Win64 are  translated  to  me
       the same as the standard keyboard keys.


    EXAMPLES:

        switch(Vgetc()) {       /* Handle input keys
                . . .
        }
    VGETS                                                             VGETS



    PROTOTYPE:

        int Vgets(int x, int y, char *prompt, char *field, int width)


    ARGUMENTS:

        x       - COLUMN of top left corner of input box
        y       - ROW of top left corner of input box
        prompt  - String to prompt with
        field   - String to receive the data
        width   - Width in characters of input field


    RETURN VALUE:

        0   - Selection was made and ENTER pressed.
        !0  - Input was aborted via ESCAPE key.


    DESCRIPTION:

          The VGETS function  draws  a  box  on  the  video  screen  at  the
       specified X and Y coordinates, then prompts for and receives an input
       string in the box.  The box is drawn  large  enough  to  contain  the
       prompt and  the  specified  width  of  input  field.  The  prompt  is
       displayed at the left hand  side  of  the  box,  and  the  cursor  is
       positioned immediately following it, at the start of the input field.

          The  "field"  parameter is the address of  a  character  array  to
       receive the input string.  The previous value of the "field" array is
       inserted into the input box when VGETS is invoked. If you do not want
       to display an old value,  you should set the first character  pointed
       to by field to zero, before calling VGETS.

          When entering the string,  the user may use the following  special
       keys to edit the input field:

                Right Arrow - Move forward one character
                Left  Arrow - Move backward one character
                Delete      - Delete the character under the cursor
                Backspace   - Move backward one character and delete.
                Home        - Move to beginning of string
                End         - Move to end of string
                PgUp        - Clear (erase) entire string
                PgDn        - Clear from cursor to end of string
                Enter       - Accept (enter) the string
                ESC         - Abort the input request

          All data entered in the input box is inserted into any data  which
       is already present.



    EXAMPLES:

        name[0] = 0;
        if(vgets(10, 10, "Your name?", name, 30))
            return;     /* Aborted, exit to higher level */
    VGOTOXY                                                         VGOTOXY



    PROTOTYPE:

        Vgotoxy(int x, int y)


    ARGUMENTS:

        x       - New COLUMN (0-79)
        y       - New ROW    (0-24)


    RETURN VALUE:

        None


    DESCRIPTION:

          The VGOTOXY function positions the  cursor  on  the  IBM-PC  video
       screen.  Any further display output will occur at  the  new  ROW  and
       COLUMN on the screen.

          The extern "int" variable "V_XY"  may be referenced to read or set
       the  current  X/Y  position.  The  higher  8  bits  contain  the  'Y'
       coordinate, and the lower 8 bits contain the 'X' coordinate.  If this
       variable is used to set  (restore)  the cursor position,  "vupdatexy"
       must then be called to position the physical cursor.

          VOPEN MUST be called prior to using this function.


    EXAMPLES:

        for(i=0; i<24; ++i) {   /* Draw a diagonal line of 'X's */
            Vgotoxy(i, i);
            Vputc('X'); }
    VOPEN                                                             VOPEN



    PROTOTYPE:

        Vopen(char color)


    ARGUMENTS:

        color       - color atribute for video output


    RETURN VALUE:

        None


    DESCRIPTION:

          This function initializes the IBM-PC video display adapter for use
       with the MICRO-C video library functions.  It determines the  adapter
       type  (COLOR  or  MONOCHROME),  sets  up  internal   variables   with
       information required by the other video  functions,  and  clears  the
       video screen.

          This function MUST  be  called  before  any  of  the  other  video
       functions in the library are used.
          Any program using the video library  functions  must  include  the
       "video.h" header file.


    EXAMPLES:

        vopen();
    VPRINTF                                                         VPRINTF



    PROTOTYPE:

        register int Vprintf(char *format, arg, ...)


    ARGUMENTS:

        format  - Pointer to format string
        arg     - Argument as determined by format string
        ...     - Additional arguments may be required


    RETURN VALUE:

        Length of output string


    DESCRIPTION:

          This function performs exactly as the  "PRINTF"  function  in  the
       standard function library,  except that it outputs  directly  to  the
       video screen using the video interface library routines.

          This function should be used in preference to "PRINTF"  when using
       the video function library since  "PRINTF"  will not move  the  video
       librarys cursor.

          NOTE: This function uses a variable number of arguments,  and must
       be declared as "register" (See "video.h").

          VOPEN MUST be called prior to using this function.


    EXAMPLES:

        Vgotoxy(0, 0);
        Vprintf("Screen %u", screen);
    VPUTC                                                             VPUTC



    PROTOTYPE:

        Vputc(char chr)


    ARGUMENTS:

        chr     - Character to display


    RETURN VALUE:

        None


    DESCRIPTION:

          This function displays a character on  the  video  screen  at  the
       current cursor position.

          Characters are output in  "tty"  fashion,  with proper handling of
       control codes such as CARRIAGE-RETURN, LINE-FEED and BELL. The screen
       will scroll upwards when a NEWLINE is printed on the bottom  line  of
       the screen, or when the bottom line wraps around to the next.

          Although only the lower 8 bits of a passed value are used, "vputc"
       will not perform ANY output translations if any of the upper  8  bits
       are set.  This provides a method of displaying the  video  characters
       represented by control codes such as NEWLINE, and BACKSPACE.

          VOPEN MUST be called prior to using this function.


    EXAMPLES:

        Vputc(0x0A);            /* Line-feed, advance cursor */
    VPUTS                                                             VPUTS



    PROTOTYPE:

        Vputs(char *string)


    ARGUMENTS:

        string  - Pointer to character string


    RETURN VALUE:

        None


    DESCRIPTION:

          The VPUTS function outputs a character string to the IBM-PC  video
       screen using the video library functions.

          VOPEN MUST be called prior to using this function.


    EXAMPLES:

        Vputs(message);
    MICRO-C PC Library                                               Page: 9


    4. DVM LIBRARY DIFFERENCES

        The DEMO version of DVM runs under Windows64 which does not allow user
    programs to access hardware directly, and is also built with a toolset
    which has limitations on performing some other system related functions.

        This prevented me from moving over some functions from my standard
    PC86/DOS/Win32 library, and in a few cases I have added or changed functions
    to be more useful under DVM.

        For these reasons the following functions from my PC86/DOS library
    are NOT included in the DVM library.

        alloca      cbreak      Cclose      Cflags      Cgetc
        clearerr    close       Copen       cpu         Cputc
        create      Csignals    Ctestc      disable     dup
        dup2        enable      ferror      get_attr    get_cs
        get_ds      get_es      get_vector  hrg_arc     hrg_box
        hrg_circle  hrg_close   hrg_delay   hrg_fbox
        hrg_fcircle hrg_fill    hrg_getpal  hrg_hline   hrg_line
        hrg_open    hrg_plot    hrg_polygon hrg_printf
        hrg_putc    hrg_puts    hrg_retrace hrg_scale
        hrg_setpal  hrg_vline   in          int86       intr
        inw         IOB_size    isacon      isadev      isatty
        joystick    lgetc       lgets       lprintf     lputc
        lputs       lrewind     lrg_arc     lrg_blit    lrg_box
        lrg_circle  lrg_close   lrg_delay   lrg_draw    lrg_erase
        lrg_fbox    lrg_fcircle lrg_fill    lrg_getpal
        lrg_hline   lrg_line    lrg_open    lrg_plot
        lrg_polygon lrg_printf  lrg_putc    lrg_puts
        lrg_retrace lrg_scale   lrg_setpal  lrg_vline   lscanf
        lseek       ltell       open        out         outw
        read        restore_video           save_video  setbuf
        set_attr    set_date    set_drive   set_es      set_time
        set_vector  sound       sound_off   tsr         vclear_box
        vcleol      vcleos      vclscr      vcursor_block
        vcursor_line            vcursor_off vdraw_box   version
        vgetc       vgets       vgotoxy     vmenu       vmessage
        vopen       vprintf     vputc       vputf       vputs
        vtstc       vupdatexy   wcleol      wcleow      wclose
        wclwin      wcursor_block           wcursor_line
        wcursor_off wform       wgetc       wgets       wgotoxy
        wmenu       wmessage    wopen       wprintf     wputc
        wputf       wputs       write       wtstc       wupdatexy
        w_cleol     w_cleow     w_close     w_clwin     w_getc
        w_gotoxy    W_OPEN      W_PAGE      w_printf    w_putc
        w_puts      W_ROWS      w_tstc      w_updatexy

          And the following functions  are  provided  in  the  DVM  library,
       although they are not available in the PC86/DOS libaray:

        Vcleol      Vcleos      Vclscr      Vcursor     Vopen
        Vclose      Vgetc       Vgetk       Vgets       Vputc
        Vputs       Vprintf     Vcolor      VFcolor     VBcolor
        RDsetup     halt        find_close  Vgotoxy
        MemReadCode1            MemReadCode2            setCapture
        sleep.p
