




          ===========================================================
                DDDDD           DDDDD               SSSS
                 D   Dunfield    D   D             S
                 D   D           D   Development    SSSS 
                 D   D           D   D                  Systems
                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.


                              PC Library Reference


                                  Release 3.22

                               Revised 20-May-01










                          Dunfield Development Systems
                          ----------------------------
                             High quality tools for
                              Embedded Development
                                 at low prices.

                            http://www.dunfield.com


                       Copyright 1988-2002 Dave Dunfield
                              All rights reserved
    MICRO-C PC Library                                               Page: 1


    1. ALPHABETICAL FUNCTION INDEX

    --Flags--
    Documented :  S=Std-lib  P=PC-lib  W=Window-lib  L=LRG-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
    bsearch       SA      Binary search
    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
    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
    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
    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_box       L       Draw an outline BOX
    lrg_circle    L       Draw an outline CIRCLE
    lrg_close     L       Terminate low-res graphics
    lrg_draw      L       Draw a sprite graphic
    lrg_erase     L       Erase a sprite graphic
    lrg_fbox      L       Draw a filled (solid) box
    MICRO-C PC Library                                               Page: 3


    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_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
    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
    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)
    rmdir         S       Delete a directory
    save_video    P       Save video text page
    scanf         SA*     Formatted input from stdin
    setbuf        SA*     Resize file I/O buffer (stream)
    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
    MICRO-C PC Library                                               Page: 4


    set_vector    P       Set interrupt vector
    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
    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
    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
    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
    MICRO-C PC Library                                               Page: 5


    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
    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: 6



                         +----------------------------+
                         |                            |
                         |  ************************  |
                         |  * 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 */
    CLEARERR                                                       CLEARERR



    PROTOTYPE:

        clearerr(FILE *fp)


    ARGUMENTS:

        fp      - File pointer to an open file


    RETURN VALUE:

        None


    DESCRIPTION:

          The  "clearerr"  functions resets the error  indicator  associated
       with a file stream. This is normally used after an error has occurred
       to insure that ferror()  will not continue to report  errors  (unless
       new errors occur).


    EXAMPLES:

        if(ferror(fp)) {
            printf("File I/O error has occurred!\n");
            clearerr(fp); }
    CLOSE                                                             CLOSE



    PROTOTYPE:

        int close(HANDLE fh)


    ARGUMENTS:

        fh      - File handle of 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
       "open".


    EXAMPLES:

        close(fh);
    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));
    CREATE                                                           CREATE



    PROTOTYPE:

        int create(char *pathname, int attrs)



    ARGUMENTS:

        pathname- Name of file to create
        attrs   - Attributes for new file


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          The "create" function creates a new file with the specified system
       attributes.

          The meaning of the individual bits in the "attrs"  value is system
       dependent, and is defined in the "file.h" header file.


    EXAMPLES:

        create("temp", HIDDEN);
    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");
    DUP                                                                 DUP



    PROTOTYPE:

        HANDLE dup(HANDLE fh)


    ARGUMENTS:

        fh      - File handle of an open file


    RETURN VALUE:

        New file handle or zero (0) if failure


    DESCRIPTION:

          The DUP function  duplicates  a  file  handle.  A  new  handle  is
       allocated, which is made to reference the same open file or device.

          Both handles will have the same access  mode,  and  reference  the
       same file pointer.  ie:  Seeks or reads  via  one  handle  will  also
       reposition the other handle.


    EXAMPLES:

        fh1 = open("OUTPUT", F_WRITE);      /* Open output file */
        fh2 = dup(stdout->FILE_handle);     /* Make copy of stdout */
        dup2(fh1, stdout->FILE_handle);     /* Redirect stdout to file */
        system("DIR");                      /* Execute a command */
        dup2(fh2, stdout->FILE_handle);     /* Restore original file */
        close(fh1);
        close(fh2);
    DUP2                                                               DUP2



    PROTOTYPE:

        int dup2(HANDLE oldh, HANDLE newh)


    ARGUMENTS:

        oldh        - File handle of an open file
        newh        - HAndle to redirect to file


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          The DUP2 function duplicates a file handle into  another  specific
       file handle.  The  'newh'  handle is made to reference the same  open
       file or device.  This can be thought  of  as  "redirecting"  the  new
       handle to a specific open file.

          If a file is already open via the new handle, it is closed.

          Both handles will have the same access  mode,  and  reference  the
       same file pointer.  ie:  Seeks or reads  via  one  handle  will  also
       reposition the other handle.


    EXAMPLES:

        fh1 = open("OUTPUT", F_WRITE);      /* Open output file */
        fh2 = dup(stdout->FILE_handle);     /* Make copy of stdout */
        dup2(fh1, stdout->FILE_handle);     /* Redirect stdout to file */
        system("DIR");                      /* Execute a command */
        dup2(fh2, stdout->FILE_handle);     /* Restore original file */
        close(fh1);
        close(fh2);
    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  operating  system.  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 */
    FERROR                                                           FERROR



    PROTOTYPE:

        int ferror(FILE *fp)


    ARGUMENTS:

        fp      - File pointer to an open file


    RETURN VALUE:

        0       - No I/O error has occurred
        !0      - An I/O error has occurred


    DESCRIPTION:

          The  "ferror"  function returns the error flag associated  with  a
       file stream.  This flag is cleared by open(), rewind() or clearerr(),
       and is set whenever the operating  system  reports  an  error  during
       reading or writing the file.


    EXAMPLES:

        while(*ptr)
            putc(*ptr++, fp)
        if(ferror(fp))
            printf("An error occurred during writes to the file!\n");
    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));
    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
        offset  - 16 bit 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
        offset  - Address of int to receive 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);
    IN                                                                   IN



    PROTOTYPE:

        int in(unsigned port)


    ARGUMENTS:

        port    - I/O port address


    RETURN VALUE:

        The 8 bit value read from the given I/O port address


    DESCRIPTION:

          The "in"  function reads and returns a byte  (8 bits)  from an I/O
       port as an integer value between 0 and 255.

          The valid range of values for  "port"  depends on the I/O  address
       space of the processor.

          This function is not provided for processors which do not  support
       a separate I/O address space.


    EXAMPLES:

        while(in(0));   /* Wait for flag to clear */
    INW                                                                 INW



    PROTOTYPE:

        int inw(unsigned port)


    ARGUMENTS:

        port    - I/O port address


    RETURN VALUE:

        The 16 bit value read from the given I/O port address


    DESCRIPTION:

          The "inw" function reads and returns a word (16 bits)  from an I/O
       port as an integer value between 0 and 65535 (-1).

          The valid range of values for  "port"  depends on the I/O  address
       space of the processor.

          This function is not provided for processors which do not  support
       a separate I/O address space.


    EXAMPLES:

        var = inw(0);
    ISACON                                                           ISACON



    PROTOTYPE:

        int isacon(HANDLE fh)


    ARGUMENTS:

        fh      - An open file handle


    RETURN VALUE:

        0       - Handle does not refer to a console device
        !0      - Handle does refer to a console device


    DESCRIPTION:

          The "isacon"  function tests an open file handle,  and return TRUE
       only if that file handle refers to a console device.


    EXAMPLES:

        if(isacon(stdin->FILE_handle))
            abort("This program must have input redirected");
    ISADEV                                                           ISADEV



    PROTOTYPE:

        int isadev(HANDLE fh)


    ARGUMENTS:

        fh      - An open file handle


    RETURN VALUE:

        0       - Handle does not refer to any device
        !0      - Handle does refer to a device


    DESCRIPTION:

          The "isadev"  function tests an open file handle,  and return TRUE
       only if that file handle refers to any type of device.


    EXAMPLES:

        if(isadev(fp->FILE_handle))
            abort("This program must write to a FILE, not a device");
    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");
    ISATTY                                                           ISATTY



    PROTOTYPE:

        int isatty(HANDLE fh)


    ARGUMENTS:

        fh      - An open file handle


    RETURN VALUE:

        0       - Handle does not refer to a tty device
        !0      - Handle does refer to a tty device


    DESCRIPTION:

          The "isatty"  function tests an open file handle,  and return TRUE
       only if that file handle refers to  a  tty  device  (Console,  Serial
       port, Printer etc.).


    EXAMPLES:

        if(!isatty(stdout->FILE_handle))    /* For non-interactive ... */
            setbuf(stdout, 4096);           /* use buffered output     */
    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 */
    LGETC                                                             LGETC



    PROTOTYPE:

        int lgetc(HANDLE fh)


    ARGUMENTS:

        fh      - File handle for 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  using
       LOW LEVEL (unbuffered) I/O, 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 = lgetc(input_file)) == EOF)
            abort("End of file encountered\n");
    LGETS                                                             LGETS



    PROTOTYPE:

        char *lgets(char *buffer, int size, HANDLE fh)


    ARGUMENTS:

        buffer  - Pointer to string to receive line
        size    - Maximum size of line to read
        fh      - File handle of an input file


    RETURN VALUE:

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


    DESCRIPTION:

          The  "lgets"  function reads characters from the  specified  input
       file using LOW  LEVEL  (unbuffered)  I/O,  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" characters are read.

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


    EXAMPLES:

        lgets(input_line, 80, L_stdin);
    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 */
    LONGMATH                                                       LONGMATH



    PROTOTYPES:

        int longadd(char *num1, char *num2);
        int longsub(char *num1, char *num2);
        longmul(char *num1, char *num2);
        longdiv(char *num1, char *num2);
        int longshr(char *num1);
        int longshl(char *num1);
        longcpy(char *num1, char *num2);
        longset(char *num1, unsigned value);
        int longtst(char *num1);
        int longcmp(char *num1, char *num2);
        int atol(char *string, char *num1, int radix)
        char *ltoa(char *num1, char *string, int radix)
        extern char Longreg[];

    ARGUMENTS:

        num1    - First LONG operand, receives result if generated
        num2    - Second LONG operand, is not altered
        value   - 16 bit value to initialize LONG number with
        string  - Character string for conversion to/from long value
        radix   - Number base to perform ASCII<>LONG conversion

    RETURN VALUE:

        longadd - 0 = Ok, 1 = addition overflowed
        longsub - 0 = Ok, 1 = subtraction underflowed
        longshr - Carry out of shift (1/0)
        longshl - Carry out of shift (1/0)
        longtst - 0 = Number is zero, !0 = Number is not zero
        longcmp - 0 = (num1 == num2), 1 = (num1 > num2), -1 = (num1 < num2)
        atol    - Character terminating conversion (non-numeric)
        ltoa    - Pointer to zero terminating destination string


    DESCRIPTION:

          These  routines  performs  basic  arithmetic  functions  on   LONG
       numbers.  As shipped,  a LONG number is 32 bits  (4 bytes)  in  size,
       however this can be changed by altering LONGMATH.ASM  and  LONGRTNS.C
       in the library.

        longadd : num1 += num2          longsub : num1 -= num2
        longshr : num1 >>= 1            longshl : num1 <<= 1
        longcpy : num1 = num2           longset : num1 = (long) value
        longtst : Test (num1 != 0)      longcmp : Compare num1 and num2
        longmul : num1 *= num2 , Longreg = num1 * num2
        longdiv : num1 /= num2 , Longreg = num1 % num2
        atol    : Convert ASCII string to LONG
        ltoa    : Convert LONG to ASCII string

          For a complete example of using  these  functions,  refer  to  the
       LONGCALC.C example program included with the package.
    LPRINTF                                                         LPRINTF



    PROTOTYPE:

        register int lprintf(int handle, char *format, arg, ...)


    ARGUMENTS:

        handle  - DOS file handle of 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
       'fh', using LOW LEVEL (unbuffered) I/O.

          The  'format'  string is written to the file  with  the  arguments
       substituted for special "conversion characters".  See  "fprintf"  for
       more information on format strings and conversions.

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


    EXAMPLES:

        lprintf(fh, "Total errors=%u", error_count);
    LPUTC                                                             LPUTC



    PROTOTYPE:

        lputc(char c, HANDLE fh)


    ARGUMENTS:

        c       - Any character value
        fh      - File handle of an output file


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          This function writes the character  'c'  to the file indicated  by
       'fh' using LOW LEVEL (unbuffered) I/O.  The "newline" (\n)  character
       will be translated into whatever character(s)  are  required  by  the
       operating system to separate records in the file.


    EXAMPLES:

        lputc('*', fh);
        lputc('\n', L_stderr);
    LPUTS                                                             LPUTS



    PROTOTYPE:

        lputs(char *string, HANDLE fh)


    ARGUMENTS:

        string  - Pointer to a character string
        fh      - File handle of an output file


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          The "lputs"  function writes the specified string to the indicated
       output file using LOW LEVEL  (unbuffered)  I/O.  The zero terminating
       the string is NOT written.


    EXAMPLES:

        lputs("Text message", output_fh);
    LREWIND                                                         LREWIND



    PROTOTYPE:

        int lrewind(HANDLE fh)


    ARGUMENTS:

        fh      - File handle of an open file


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          This function resets the operating system internal file handle  so
       than any subsequent read or writes will be at the  beginning  of  the
       file. For use with LOW LEVEL (unbuffered) file I/O only.


    EXAMPLES:

        lrewind(input_fh);
    LSCANF                                                           LSCANF



    PROTOTYPE:

        register int lscanf(int fh, char *format, &arg, ...)


    ARGUMENTS:

        fh      - DOS file handle of 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 using LOW  LEVEL
       (unbuffered)  I/O,  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.

          See "fscanf" for more information on format strings.

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


    EXAMPLES:

        if(lscanf(infile,"%s %s %u", first_name, last_name, &age) != 3)
            abort("Error in user record\n");
    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));
        }
    LSEEK                                                             LSEEK



    PROTOTYPE:

        int lseek(HANDLE fh, int h_offset, unsigned l_offset, int mode)


    ARGUMENTS:

        fh  - File handle of an open file
        h_offset- Highest 16 bits of offset value
        l_offset- Lowest 16 bits of offset value
        offset  - 16 bit 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.

          For use with LOW LEVEL (unbuffered I/O only).


    EXAMPLES:

        lseek(input_fh, 0, 0, 2);   /* Advance to end of file */
    LTELL                                                             LTELL



    PROTOTYPE:

        int ltell(HANDLE fh, int &h_offset, unsigned &l_offset)


    ARGUMENTS:

        fh      - File handle of 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
        offset  - Address of int to receive 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.

          For use with LOW LEVEL (unbuffered I/O only).


    EXAMPLES:

        ltell(fp, &oldh, &oldl);    /* Save file position */
            . . .                   /* Perform some operations on the file */
        lseek(fp, oldh, oldl, 0);   /* Return to previous position */
    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);
    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;
    OPEN                                                               OPEN



    PROTOTYPE:

        HANDLE open(char *filename, int options)


    ARGUMENTS:

        filename- Name of the file to open
        options - Open options (defined in file.h)


    RETURN VALUE:

        File handle for the open file
        Zero (0) if file could not be opened


    DESCRIPTION:

          This function  open  a  file  for  direct  access  via  LOW  LEVEL
       (unbuffered) I/O.

          MICRO-C's  implementation  of  this  function  differs  from  UNIX
       standards in that it returns zero (0) on error instead of -1.


    EXAMPLES:

        if(fh = open("data.img", F_READ)) {
            read(data_buf, 100, fh);
            close(fh); }
        else
            abort("Unable to read data file");
    OUT                                                                 OUT



    PROTOTYPE:

        out(unsigned port, int value)


    ARGUMENTS:

        port    - I/O port address
        value   - Value to write to I/O port


    RETURN VALUE:

        None


    DESCRIPTION:

          The "out" function writes a byte (8 bit) value to an I/O port.

          The valid range of values for  "port"  depends on the I/O  address
       space of the processor.

          This function is not provided for processors which do not  support
       a separate I/O address space.


    EXAMPLES:

        out(0, 0);      /* Output 0 to I/O port 0 */
    OUTW                                                               OUTW



    PROTOTYPE:

        outw(unsigned port, int value)


    ARGUMENTS:

        port    - I/O port address
        value   - Value to write to I/O port


    RETURN VALUE:

        None


    DESCRIPTION:

          The "outw" function writes a word (16 bit) value to an I/O port.

          The valid range of values for  "port"  depends on the I/O  address
       space of the processor.

          This function is not provided for processors which do not  support
       a separate I/O address space.


    EXAMPLES:

        outw(0, 0);     /* Write 0 to I/O ports 0 and 1 */
    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);
    READ                                                               READ



    PROTOTYPE:

        int read(char *buffer, int size, HANDLE fh)


    ARGUMENTS:

        buffer  - Pointer to buffer to receive data
        size    - Number of bytes to read
        fh      - File handle of an input file


    RETURN VALUE:

        Number of bytes read from file


    DESCRIPTION:

          This function reads a block of data from a file  using  LOW  LEVEL
       (unbuffered) I/O, and places it in memory at the address of "buffer".
       Data is read in  "raw"  form,  with no  interpretation  of  "newline"
       characters etc.  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:

        read(block, 512, input_fh);
    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");
    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);
    SETBUF                                                           SETBUF



    PROTOTYPE:

        FILE *setbuf(FILE *fp, int size)


    ARGUMENTS:

        fp      - File pointer to an open file
        size    - Size of new I/O buffer


    RETURN VALUE:

        If successful, a new file pointer is returned, and the old one
        is released. On failure the old file pointer is returned.


    DESCRIPTION:

          The "setbuf"  function will adjust the size of the buffer used for
       I/O operations on the indicated open file.

          This is the ONLY way to set the buffer size for  the  "stdin"  and
       "stdout" streams.  If you change the size of the "stdout" buffer, you
       must remember to "fflush(stdout)"  before terminating,  otherwise the
       last buffer contents may not be written.

          For files opened by  "fopen",  the buffer size  may  be  set  more
       efficiently by setting the value of the external variable  "IOB_size"
       prior to calling "fopen".

          If  "setbuf"  is unable to allocate space for the new  buffer,  it
       will return the old file pointer unchanged.

          MICRO-C's  implementation  of  this  function  differs  from  ANSI
       standards in that it accepts a size,  and  adjusts  it  own  internal
       buffer,  possibly relocating the file pointer if necessary.  This  is
       because MICRO-C's I/O buffers  are  an  integral  part  of  the  file
       structure.


    EXAMPLES:

        stdout = setbuf(stdout, 512);   /* Set stdout to 512 byte buffer */
    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");
    WRITE                                                             WRITE



    PROTOTYPE:

        int write(char *block, int size, HANDLE fh)


    ARGUMENTS:

        block   - Pointer to a block of data to write
        size    - Number of bytes to write
        fh      - File handle of an output file


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          This function writes a block of data to the indicated  file  using
       low level (unbuffered) I/O from memory at the specified address. Data
       is  written  in  "raw"  form,  with  no  translations  of   "newline"
       characters etc.  If the value returned is less than the value of  the
       "size"  parameter,  some error condition has occurred  (Such as  disk
       full).

          MICRO-C's  implementation  of  this  function  differs  from  ANSI
       standards in that it returns an error code  instead  of  a  character
       count.


    EXAMPLES:

        if(write(buffer, 100, fh) < 100)
            abort("File write error\n");
    _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: 7



                      +---------------------------------+
                      |                                 |
                      |  *****************************  |
                      |  * 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.
    ALLOCA                                                           ALLOCA



    PROTOTYPE:

        char *alloca(int size)


    ARGUMENTS:

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


    RETURN VALUE:

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


    DESCRIPTION:

          The  "alloca"  function allocates a  block  of  automatic  (stack)
       memory,  which exists only only until the function  calling  "alloca"
       returns.  When that function returns,  all stack memory including any
       allocated by "alloca" is released.

       NOTE: THE FOLLOWING RESTRICTIONS APPLY TO THE USE OF ALLOCA:

          The function calling  'alloca'  MUST have at least  one  automatic
       (local)  variable,  otherwise MICRO-C will not restore the  stack  on
       exit.

          The 'alloca' function must be used within a simple expression,  at
       a point where there will be no partial results stored on the stack.

          The above conditions can best be met by declaring a local  pointer
       which will hold the memory address, and assigning it the value of the
       'alloca' call in a single statement. The address returned by 'alloca'
       should NOT be assigned to a calculated  address  (such  as  an  array
       element or indirect reference via a pointer),  since this may  result
       in stack activity.

          NOTE:  The size operand to  'alloca'  can be a complex expression,
       since any stack operations it causes will have dissipated by the time
       'alloca' gets called.


    EXAMPLES:

    function(string)
        char *string;
    {
        char *local_memory;

        if(!(local_memory = alloca(strlen(string)+1)))
            abort("Not enough memory for alloca");
        /* ... */
    }
    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) */
    CBREAK                                                           CBREAK



    PROTOTYPE:

        cbreak(int allow)


    ARGUMENTS:

        allow   - 0 = disallow break, 1 = allow breaks, -1 = no change


    RETURN VALUE:

        Current (or new) setting of break flag


    DESCRIPTION:

          Controls the setting of the DOS "break" flag. When set on (allow =
       1),  the keyboard is tested for CONTROL-BREAK  on  any  DOS  function
       call. If set off (allow = 0), CONTROL-C is only recognized during I/O
       to the keyboard and video display.


    EXAMPLES:

        oldb = cbreak(-1);      /* Get current setting */
        cbreak(0);              /* Disable keyboard interrupts */
        function();             /* Perform some function */
        cbreak(oldb);           /* Restore previous setting */
    CCLOSE                                                           CCLOSE



    PROTOTYPE:

        Cclose()


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          This function closes the  communications  port  previously  opened
       using  "Copen".  The system interrupt vectors and all other hooks  to
       the comm port are restored.

          This function must be called  before  any  program  using  "Copen"
       terminates,  otherwise the communications port will  be  left  in  an
       indeterminate state. If this is not done, there will be a possibility
       of system crash if an interrupt is received from the port  after  the
       program has terminated.


    EXAMPLES:

        Cclose();       /* Close comm port */
        exit(0);        /* And terminate */
    CGETC                                                             CGETC



    PROTOTYPE:

        int Cgetc()


    ARGUMENTS:

        None


    RETURN VALUE:

        Character read from the communications port


    DESCRIPTION:

          This function reads a single  character  from  the  communications
       port previously opened with  "Copen".  If no character is  available,
       "Cgetc" will wait for one.


    EXAMPLES:

        /* Get a string from the comm port */
        while((c = Cgetc()) != '\r')
            *ptr++ = c;
        *ptr = 0;
    COPEN                                                             COPEN



    PROTOTYPE:

        int Copen(int port, int speed, int mode, int modem)


    ARGUMENTS:

        port    - Comm port to use (1, 2, 3 or 4)
        speed   - Baudrate divisor to set
        mode    - Communications parameters to set
        modem   - Modem control lines to set

    RETURN VALUE:

        0       - Successful open
        !0      - Requested comm port is not available


    DESCRIPTION:

          The "Copen" function opens a serial communications port on the IBM
       PC for access.  An independent interrupt handler and I/O drivers  are
       installed, which allow high speed full duplex operation of the serial
       port with optional XON/XOFF flow control of both receive and transmit
       streams.

          Only one serial port  may  be  accessed  at  a  time  using  these
       functions, If "Copen" is called more than once, it will automatically
       close the last port before opening the new one.

          The meaning of the "speed",  "mode",  and  "modem"  parameters are
       documented in the "comm.h" header file.  Note that the OUTPUT_2 modem
       control line must be set in order to enable interrupts on the PC  bus
       (Be sure to reset it when you close so that the alternate  (COM1-3 or
       COM2-4) port can be enabled without conflict).

          An external "char" variable "Cflags"  may be accessed to enable or
       disable transparency of the serial  channel.  When  "transparent"  is
       selected, XON/XOFF flow control is disabled, and all data is sent and
       received with no changes.  When operating  in  this  mode,  you  must
       insure that  "Cgetc"  is called frequently enough that the  256  byte
       internal receive buffer will not overflow.

          Since  "Cflags"  is used by  the  interrupt  handler,  you  should
       disable and enable interrupts around any accesses to it.



    EXAMPLES:

        #include comm.h     /* Get comm port definitions */

        extern char Cflags;

        /*
         * Program to read & echo characters on the serial port
         * in transparent mode. (Until ESCAPE char is received)
         */
        main()
        {
            char c;

            if(Copen(1, _2400, PAR_NO|DATA_8|STOP_1, SET_RTS|SET_DTR|OUTPUT_2))
                abort("Cannot access COM1");

            disable();                  /* Disable interrupts */
            Cflags |= TRANSPARENT;      /* Set transparency */
            enable();                   /* Re-enable interrupts */

            while((c = Cgetc()) != 0x1B)    /* Do until ESCAPE */
                Cputc(c);

            Cclose();                   /* Close the serial port */
        }
    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);
    CPU                                                                 CPU



    PROTOTYPE:

        int cpu()


    ARGUMENTS:

        None


    RETURN VALUE:

        0       - CPU is 8088 or 8086
        1       - CPU is 80188 or 80186
        2       - CPU is 80286
        3       - CPU is 80386 or 80486


    DESCRIPTION:

          This function  returns  a  simple  integer  which  identifies  the
       processor type on which the program is currently executing.


    EXAMPLES:

        if(cpu() < 2)
            abort("This program requires at least an 80286");
    CPUTC                                                             CPUTC



    PROTOTYPE:

        Cputc(char c)


    ARGUMENTS:

        c       - Character to write to communication port


    RETURN VALUE:

        None


    DESCRIPTION:

          The  "Cputc"  function  writes  the   given   character   to   the
       communications port previously opened by "Copen".


    EXAMPLES:

        while(*ptr)         /* Write a string to comm port */
            Cputc(*ptr++);
    CSIGNALS                                                       CSIGNALS



    PROTOTYPE:

        int Csignals()


    ARGUMENTS:

        None


    RETURN VALUE:

        The modem input signals read from the open comm port


    DESCRIPTION:

          This function reads the modem input signals (DSR, CD, RI etc) from
       the serial communication  port  previously  opened  by  "Copen",  and
       returns them as an integer value.

          The meaning of the  individual  bits  in  the  value  returned  by
       "Csignals" is documented in the "comm.h" header file.


    EXAMPLES:

        if(!(Csignals() & DSR)) {
            Cclose();
            abort("Modem not ready"); }
    CTESTC                                                           CTESTC



    PROTOTYPE:

        int Ctestc()


    ARGUMENTS:

        None


    RETURN VALUE:

        0-255   - Character read from comm port
        -1      - No character available


    DESCRIPTION:

          This function tests for a character from the  communications  port
       previously opened with "Copen",  and returns that character if one if
       found. If no character is available, "Ctestc" returns -1.


    EXAMPLES:

        if((c = Ctestc()) == -1) {
            Cclose();
            abort("No character available"); }
    DELAY                                                             DELAY



    PROTOTYPE:

        delay(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 */
    DISABLE                                                         DISABLE



    PROTOTYPE:

        disable()


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          The  "disable"  function  disables  the  8086  interrupt   system,
       preventing the  processor  from  servicing  interrupts.  It  is  used
       whenever the execution of an interrupt handler may interfere  with  a
       particular operation.

          When this function is used, the "enable" function should be called
       as soon as possible after "disable". Failure to do this may result in
       loss  of  system  functions  performed  under  interrupts,  such   as
       timekeeping, and serial communications (Via MICRO-C serial drivers).


    EXAMPLES:

        disable();                  /* Disallow interrupts */
        Cflags &= ~TRANSPARENT;     /* Remove transparency */
        enable();                   /* Re-allow interrupts */
    ENABLE                                                           ENABLE



    PROTOTYPE:

        enable()


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          The "enable" function enables the 8086 interrupt system,  allowing
       the processor to service interrupts.  It should be called as soon  as
       possible following the use of the "disable" function.


    EXAMPLES:

        disable();                  /* Disallow interrupts */
        Cflags |= TRANSPARENT;      /* Force  transparency */
        enable();                   /* Re-allow interrupts */
    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_ATTR                                                       GET_ATTR



    PROTOTYPE:

        int get_attr(char *pathname, int &attrs)


    ARGUMENTS:

        pathname- Name of file to get attributes of
        attrs   - Integer to receive attributes


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          This function retrieves the attributes of the specified file.

          The meaning of the individual bits in the "attrs" value is defined
       in the "file.h" header file.


    EXAMPLES:

        get_attr("tempfile", &attributes);
    GET_CS                                                           GET_CS



    PROTOTYPE:

        int get_cs()


    ARGUMENTS:

        None


    RETURN VALUE:

        The current processor CODE segment


    DESCRIPTION:

          This function is available only on the 8086 family of  processors,
       and returns the current processor CODE segment.


    EXAMPLES:

        code_seg = get_cs();
    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_DS                                                           GET_DS



    PROTOTYPE:

        int get_ds()


    ARGUMENTS:

        None


    RETURN VALUE:

        The current processor DATA segment


    DESCRIPTION:

          This function is available only on the 8086 family of  processors,
       and returns the current processor DATA segment.


    EXAMPLES:

        data_seg = get_ds();
    GET_ES                                                           GET_ES



    PROTOTYPE:

        int get_es()


    ARGUMENTS:

        None


    RETURN VALUE:

        The current processor EXTRA segment


    DESCRIPTION:

          This function is available only on the 8086 family of  processors,
       and returns the current processor EXTRA segment.


    EXAMPLES:

        code_seg = get_es();
    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);
    GET_VECTOR                                                   GET_VECTOR



    PROTOTYPE:

        get_vector(int interrupt, int &segment, int &offset);


    ARGUMENTS:

        interrupt   - The interrupt vector to get (0-255)
        segment     - Address of integer to receive segment
        offset      - Address of integer to receive offset


    RETURN VALUE:

        None


    DESCRIPTION:

          This function retrieves the segment:offset from an 8086  interrupt
       vector.


    EXAMPLES:

        get_vector(0x09, &seg, &off);   /* Get old keyboard interrupt */
        set_vector(0x09, get_cs(), &handler);   /* Install new handler */
        /* ... */
        set_vector(0x09, seg, off);     /* Restore old handler */
    INT86                                                             INT86



    PROTOTYPE:

        int int86(int inum)


    ARGUMENTS:

        inum    - The 8086 software interrupt to execute


    RETURN VALUE:

        8086 FLAGS register after interrupt executes.


    DESCRIPTION:

          This  function  performs  an  8086  software   interrupt.   Before
       executing the interrupt,  the processor registers are loaded from the
       external "int" variables: _AX_, _BX_, _CX_, _DX_, _SI_ and _DI_.  The
       DS,  ES and SS segment registers are all set to  point  to  MICRO-C's
       data segment.

          After the interrupt  completes,  the  contents  of  the  processor
       registers are copied to the above named variables.


    EXAMPLES:

        extern int _AX_, _DX_;
        main() {
            _AX_ = 0x0200;  /* MSDOS function 2 - Output character */
            _DX_ = '$';     /* Character to output */
            int86(0x21);    /* Call MSDOS */
        }
    INTR                                                               INTR



    PROTOTYPE:

        intr(int inum, struct REGPACK regs)


    ARGUMENTS:

        inum    - The 8086 software interrupt to execute + options
        regs    - Structure to pass/receive cpu registers


    RETURN VALUE:

        None


    DESCRIPTION:

          This function performs an 8086 software interrupt.  Although  more
       complex than int86(),  it provides the added functionality  that  the
       BP,  DS,  ES and FLAGS registers can be passed to and  received  back
       from the interrupt,  as well as preserving and restoring  SP  and  SS
       (For those interrupts which do not cleanly  exit  with  an  unchanged
       stack).

          Prior to executing the interrupt,  the registers are  loaded  from
       the REGPACK  structure  (defined  in  INTR.H).  After  the  interrupt
       completes, SS and SP are restored,  and the registers are copied back
       into the structure.

          Since 8086 interrupts range from  0-255,  the  high  byte  of  the
       'inum' operands is reserved for special functions. Currently the only
       function implemented is bit 8 (0x0100),  which must be set for intr()
       to load the FLAGS register  prior  to  calling  the  interrupt.  This
       should be done with caution,  as improper setting of FLAGS can result
       in loss of interrupts,  and other improper operations.  In all cases,
       FLAGS  is  copied  to  the  REGPACK  structure  after  the  interrupt
       completes.


    EXAMPLES:

        #include <intr.h>
        main() {
            struct REGPACK regs;
            regs.r_ax = 0x0900;     /* MSDOS function 9 - Output string */
            regs.r_dx = "This is the string to output$";
            regs.r_ds = get_ds();   /* String is in our data segment */
            intr(0x21, regs);       /* Call MSDOS, don't reload flags */
        }
    JOYSTICK                                                       JOYSTICK



    PROTOTYPE:

        int joystick(unsigned position[4], int flags)


    ARGUMENTS:

        position    - Receives position of the four joystick inputs
        flags       - Bits 0,1,2,3 = Disable AX,AY,BX,BY input (1=Disable)

    RETURN VALUE:

        Bits 0,1,2,3 = Error reading AX,AY,BX,BY (1 = Error)
        Bits 4,5,6,7 = Button A1,A2,B1,B2 status (0 = Pressed)


    DESCRIPTION:

          This function  reads  the  PC  joystick  port,  and  returns  that
       position the four analog inputs,  as well as the status of  the  four
       buttons.

          Values placed in  'position'  will range from 0  (or very low)  to
       'n', where 'n' is dependent on the speed of the hardware.  Experiment
       with your system to determine the actual minimum and maximum  values,
       and scale the results to the range of measurements you are taking.

          Joystick inputs which are unconnected will cause this function  to
       operate quite slowly,  and will cause the "error"  bit to be returned
       for the corresponding port.  This can be eliminated  by  setting  the
       "disable" bit for those inputs which you do not use.


    EXAMPLES:

        if(!(joystick(positions, 0x0C) & 0x01)) /* Test button 1 */
            fire(); 
    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 */
        }
    RESTORE_VIDEO                                             RESTORE_VIDEO



    PROTOTYPE:

        restore_video(char buffer[4006]);


    ARGUMENTS:

        buffer  - Video save area.


    RETURN VALUE:

        None


    DESCRIPTION:

          The RESTORE_VIDEO function restores the contents and state of  the
       IBM P.C.  video display to the state it was in when "SAVE_VIDEO"  was
       executed.  At the present time,  the function is effective  only  for
       text modes.  Graphics screens will not be restored,  due to the  high
       memory requirements.

          Although this function is useful in ANY program  (to  restore  the
       DOS screen before termination),  it is most useful  in  "POP-UP"  ram
       resident programs  (See  "TSR"  function),  to save the screen of any
       application which may be running when you pop up.

          The video state is restored from  the  passed  "buffer"  argument,
       which is 4006 bytes  in  size,  and  must  have  been  filled  in  by
       "SAVE_VIDEO". It has the following format:

                  buffer[0]         - Video mode
                    "   [1]         - Video page
                    "   [2]         - 'X' cursor position
                    "   [3]         - 'Y' cursor position
                    "   [4]         - Ending line for cursor
                    "   [5]         - Starting line for cursor
                    "   [6-4005]    - Saved video screen contents


    EXAMPLES:

        popup()
        {
            save_video();
            perform_function();
            restore_video();
        }
    SAVE_VIDEO                                                   SAVE_VIDEO



    PROTOTYPE:

        save_video(char buffer[4006]);


    ARGUMENTS:

        buffer  - Video save area.


    RETURN VALUE:

        None


    DESCRIPTION:

          The SAVE_VIDEO function saves the current contents  and  state  of
       the IBM P.C.  video display.  The screen may be restored at any  time
       using "RESTORE_VIDEO". At the present time, the function is effective
       only for text modes.  Graphics screens will not be saved,  due to the
       high memory requirements.

          Although this function is useful in ANY program  (to  restore  the
       DOS screen before termination),  it is most useful  in  "POP-UP"  ram
       resident programs  (See  "TSR"  function),  to save the screen of any
       application which may be running when you pop up.

          The video state is saved in the passed "buffer" argument, which is
       4006 bytes in size, and has the following format:

                  buffer[0]         - Video mode
                    "   [1]         - Video page
                    "   [2]         - 'X' cursor position
                    "   [3]         - 'Y' cursor position
                    "   [4]         - Ending line for cursor
                    "   [5]         - Starting line for cursor
                    "   [6-4005]    - Saved video screen contents


    EXAMPLES:

        popup()
        {
            save_video();
            perform_function();
            restore_video();
        }
    SET_ATTR                                                       SET_ATTR



    PROTOTYPE:

        int set_attr(char *pathname, int attrs)


    ARGUMENTS:

        pathname- Name of file to get attributes of
        attrs   - New attributes


    RETURN VALUE:

        0 if successful, otherwise an operating system error code


    DESCRIPTION:

          This function sets the system attributes of the specified file.

          The meaning of the individual bits in the "attrs" value is defined
       in the "file.h" header file.


    EXAMPLES:

        set_attr("tempfile", READONLY|HIDDEN);
    SET_DATE                                                       SET_DATE



    PROTOTYPE:

        set_date(int day, int month, int year)


    ARGUMENTS:

        day     - New day (1-31)
        month   - New month (1-12)
        year    - New year (1980-2099)


    RETURN VALUE:

        0       - Success
        -1      - Invalid date given


    DESCRIPTION:

          This function sets the current system  date  to  day,  month,  and
       year.


    EXAMPLES:

        set_date(1, 1, 1980);   /* Set to Jan 1, 1980 */
    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);
    SET_ES                                                           SET_ES



    PROTOTYPE:

        int set_es(int segment)


    ARGUMENTS:

        segment - The 16 bit new segment value


    RETURN VALUE:

        None


    DESCRIPTION:

          This function is available only on the 8086 family of  processors,
       and sets the processors EXTRA segment to the indicated value.


    EXAMPLES:

        set_es(get_ds());       /* Copy DATA to EXTRA segments */
    SET_TIME                                                       SET_TIME



    PROTOTYPE:

        set_time(int hour, int minute, int second)


    ARGUMENTS:

        hour    - New hour (0-23)
        minute  - New minute (0-59)
        second  - New second (0-59)


    RETURN VALUE:

        0       - Success
        -1      - Invalid time given


    DESCRIPTION:

          This function sets the current system time to "hour", "minute" and
       "second".


    EXAMPLES:

        set_time(0, 0, 0);  /* Set to 00:00:00 (midnight) */
    SET_VECTOR                                                   SET_VECTOR



    PROTOTYPE:

        set_vector(int interrupt, int segment, int offset);


    ARGUMENTS:

        interrupt   - The interrupt vector to set (0-255)
        segment     - Segment of new interrupt handler
        offset      - Offset  of new interrupt handler


    RETURN VALUE:

        None


    DESCRIPTION:

          This function sets the segment:offset of the handler for  an  8086
       interrupt vector.


    EXAMPLES:

        get_vector(0x09, &seg, &off);   /* Get old keyboard interrupt */
        set_vector(0x09, get_cs(), &handler);   /* Install new handler */
        /* ... */
        set_vector(0x09, seg, off);     /* Restore old handler */
    SOUND                                                             SOUND



    PROTOTYPE:

        sound(unsigned freq)


    ARGUMENTS:

        freq    - frequency (in hertz) of tone to generate


    RETURN VALUE:

        None


    DESCRIPTION:

          Turns on the IBM PC speaker to generate a tone  at  the  specified
       frequency.  The tone will continue to be generated until either a new
       tone is output, or a call to sound_off() is performed.


    EXAMPLES:

        sound(1000);    /* Generate a 1000hz tone */
        delay(1000);    /* For 1000 ms (1 second) */
        sound_off();    /* Terminate the tone */
    SOUND_OFF                                                     SOUND_OFF



    PROTOTYPE:

        sound_off()


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          This function terminates a tone previously  established  with  the
       sound() function. The PC speaker is silenced.


    EXAMPLES:

        sound(1000);    /* Generate a 1000hz tone */
        delay(1000);    /* For 1000 ms (1 second) */
        sound_off();    /* Terminate the tone */
    TSR                                                                 TSR



    PROTOTYPE:

        tsr(&func, int hotkey, int alloc)


    ARGUMENTS:

        func    - Address of function to execute
        hotkey  - POP-UP activation hotkeys
        alloc   - Memory allocation


    RETURN VALUE:

        Function normally never returns, but if it does, an
        operating system error code is passed back.


    DESCRIPTION:

          The TSR function terminates the MICRO-C  program,  but  leaves  it
       resident in memory. When the specified "HOT KEYS" are detected on the
       IBM PC keyboard, the context of whatever program is running is saved,
       and the specified MICRO-C function  is  called.  When  that  function
       returns, the interrupted program is resumed.

          When activated this way,  THE  "func"  FUNCTION MUST NOT TERMINATE
       WITH "exit"  or one of its related functions  (abort etc.).  THE ONLY
       WAY IT MAY TERMINATE IS TO "return" NORMALLY.

          The meaning of "hotkey" is defined in the "tsr.h" header file.

          The  "alloc"  parameter specifies how much extra memory is  to  be
       retained in the TSR image for use  by  the  MICRO-C  stack  and  heap
       memory allocation functions.  The "func" function(s) must insure that
       the total amount of memory used by the stack and  calls  to  "malloc"
       does not exceed this value.

          NOTE:  "malloc"  will fail if the heap grows to within 1K  of  the
       stack pointer.

          All memory used by  code,  global  variables,  string  space,  and
       "malloc"  calls prior to the use of "tsr"  is automatically retained,
       and should not be included in the "alloc" value.

          TSR programs which perform screen I/O should take care to save and
       restore the screen contents when popping up and down.


    EXAMPLES:

        tsr(&popup_func, ALT+L_SHIFT, 1024);
    VCLEAR_BOX                                                   VCLEAR_BOX



    PROTOTYPE:

        vclear_box(int x, int y, int w, int h)


    ARGUMENTS:

        x       - COLUMN of top left corner of box
        y       - ROW of top left corner of box
        w       - Width of box (columns)
        h       - Height of box (rows)


    RETURN VALUE:

        None


    DESCRIPTION:

          This function clears a box of the specified height and  width,  at
       the indicated 'X'  and  'Y'  coordinates,  on the IBM-PC video screen
       using the block graphics characters.  The entire box  is  cleared  to
       spaces.

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


    EXAMPLES:

        vclear_box(21, 11, 8, 3);   /* Clear a BOX */
    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); }
    VCURSOR_BLOCK                                             VCURSOR_BLOCK



    PROTOTYPE:

        vcursor_block()


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          This function enables (turns on)  display of the cursor on the IBM
       PC video display.  The cursor is shown as flashing  block,  occupying
       the entire character window.

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


    EXAMPLES:

        if(insert)              /* Test insert mode flag */
            vcursor_block();    /* Indicate inserting with block cursor */
        else
            vcursor_line();     /* Indicate overwrite with line cursor */
    VCURSOR_LINE                                               VCURSOR_LINE



    PROTOTYPE:

        vcursor_line()


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          This function enables (turns on)  display of the cursor on the IBM
       PC video display.  The cursor is shown as a single flashing line,  at
       the bottom of the character window.

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


    EXAMPLES:

        vcursor_line();     /* Re-enable the cursor */
        exit(0);            /* And terminate */
    VCURSOR_OFF                                                 VCURSOR_OFF



    PROTOTYPE:

        vcursor_off()


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          This function inhibits  (turns off)  display of the cursor on  the
       IBM PC video display.  This affects the cursor display  only,  screen
       output will continue to be displayed at the correct cursor position.

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


    EXAMPLES:

        vclscr();           /* Clear screen */
        vcursor_off();      /* Inhibit cursor */
        vmenu(10, 10, main_menu, 0, &index);    /* Present main menu */
    VDRAW_BOX                                                     VDRAW_BOX



    PROTOTYPE:

        vdraw_box(int x, int y, int w, int h)


    ARGUMENTS:

        x       - COLUMN of top left corner of box
        y       - ROW of top left corner of box
        w       - Width of box (columns)
        h       - Height of box (rows)


    RETURN VALUE:

        None


    DESCRIPTION:

          This function draws a box of the specified height  and  width,  at
       the indicated 'X'  and  'Y'  coordinates,  on the IBM-PC video screen
       using the block graphics characters.

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


    EXAMPLES:

        vdraw_box(20, 10, 10, 5);   /* Draw a BOX */
    VERSION                                                         VERSION



    PROTOTYPE:

        int version()


    ARGUMENTS:

        None


    RETURN VALUE:

        MS-DOS operating system version number


    DESCRIPTION:

          The "version" function is available only under MS-DOS, and returns
       the version number of the operating system.

          The higher 8 bits  of  the  returned  value  indicates  the  MAJOR
       version number ('3' in DOS 3.1)

          The lower 8 bits of the returned value indicates the MINOR version
       number ('1' in DOS 3.1).


    EXAMPLES:

        if(version() < 0x031E)
            abort("Requires DOS 3.30 or higher\n");
    VGETC                                                             VGETC



    PROTOTYPE:

        int vgetc()


    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.


    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'); }
    VMENU                                                             VMENU



    PROTOTYPE:

        vmenu(int x, int y, char *names[], char erase, int &index)


    ARGUMENTS:

        x       - COLUMN of top left corner of menu box
        y       - ROW of top left corner of menu box
        names   - Array to menu selection text (last entry = 0)
        erase   - 1=Erase BOX after selection is made
        index   - Address of message selection index variable


    RETURN VALUE:

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


    DESCRIPTION:

          The  "vmenu"  function displays a list of menu items enclosed in a
       box on the IBM-PC video  screen  at  the  specified  ROW  and  COLUMN
       address.  The user may use the UP, DOWN,  HOME and END keys to select
       an entry by moving the INVERSE VIDEO selection cursor.

          When the desired selection is under the cursor,  the selection  is
       made by pressing the ENTER key.

          At any time the menu selection may be  canceled  by  pressing  the
       ESCAPE key.

          The  "names"  argument must be a pointer to an array of  character
       strings which are the selections to display. This array MUST end with
       a zero (0) element to indicate the end of the list.

          The "erase"  flag indicates that the menu box should be cleared to
       blanks when the selection is made. If "erase=0", the menu box is left
       on the screen, WITHOUT the selection cursor,  with the selected entry
       marked by '>' and '<'. The menu box is always erased when the menu is
       aborted with the ESCAPE key.

          The  "index"  argument is the address of an  "int"  variable which
       contains the position of the selection cursor.  It controls where the
       selection cursor will appear when the function is first invoked  (0 =
       first entry),  and also is assigned the  position  of  the  selection
       cursor when the selection is made.



    EXAMPLES:

        char *names[] = { "One", "Two", "Three", "Four", "Five", 0 };
            . . .
        index = 0;
        if(vmenu(10, 10, names, 0, &index))
            return;         /* Aborted, exit to higher level */
        switch(index) {     /* Handle selection */
            . . .
        }
    VMESSAGE                                                       VMESSAGE



    PROTOTYPE:

        vmessage(int x, int y, char *string)


    ARGUMENTS:

        x       - COLUMN of top left corner of message box
        y       - ROW of top left corner of message box
        string  - Message to display


    RETURN VALUE:

        None


    DESCRIPTION:

          The  "vmessage"  function displays a text string surrounded  by  a
       BOX,  on the IBM-PC video screen,  at the specified  ROW  and  COLUMN
       address.

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


    EXAMPLES:

        vmessage(20, 20, "Press any KEY to continue");
        get_key();
        vclear_box(20, 20, 26, 2);
    VOPEN                                                             VOPEN



    PROTOTYPE:

        vopen()


    ARGUMENTS:

        None


    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.

          After "vopen" is called, the extern "int" variable "V_BASE" may be
       referenced to determine the memory segment of the video display (B000
       for monochrome, B800 for color).

          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.

          The external "char" variable "V_ATTR" may be used to set the video
       attribute used by  "VPUTC"  to display the character.  This value  is
       written to the attribute location associated with  the  character  on
       the video display hardware.  Its effect is  dependent  on  the  video
       adapter in use. The "video.h" header file contains definitions of the
       attribute bits for use on "standard" monochrome and color displays.


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


    EXAMPLES:

        vputc(0x0A);            /* Line-feed, advance cursor */
        vputc(0x0A | 0xff00);   /* Display 0x0A character code */
    VPUTF                                                             VPUTF



    PROTOTYPE:

        vputf(char *string, int width)


    ARGUMENTS:

        string  - Pointer to character string
        width   - Width of output field


    RETURN VALUE:

        None


    DESCRIPTION:

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

          The string is left justified in a field of the specified width. If
       the string is shorter than "width",  the field is padded with blanks.
       If the string is longer than "width", the output is truncated.

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


    EXAMPLES:

        vputf(message, 10); 
    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);
    VTSTC                                                             VTSTC



    PROTOTYPE:

        int vtstc()


    ARGUMENTS:

        None


    RETURN VALUE:

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


    DESCRIPTION:

          The  "vtstc"  function tests for  a  key  pressed  on  the  system
       console,  and returns  its  value.  A  returned  value  of  zero  (0)
       indicates that no key was found to be pressed.

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


    EXAMPLES:

        if(vtstc() == 0x1B) /* exit loop on ESCAPE key */
            break;
    VUPDATEXY                                                     VUPDATEXY



    PROTOTYPE:

        vupdatexy()


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          This function updates the real X/Y cursor position  on  the  video
       screen to reflect the  "logical"  position where the  next  character
       will be output.

          The MICRO-C video library  uses  a  BIOS  interrupt  (INT  10)  to
       position the cursor,  which is quite slow,  compared to the speed  of
       the library video routines.  To prevent this from  slowing  down  the
       video output,  the cursor is  only  physically  repositioned  when  a
       "vgotoxy" or a "vgetc" is executed.

          This allows the library routines to run at full speed,  and  still
       put the cursor in the right place when  output  stops  and  an  input
       request is made.

          A side effect of this is that the cursor on the  screen  will  not
       appear to move unless  you  call  "vgotoxy"  or  "vgetc".  This  only
       affects the physical cursor on the screen,  MICRO-C maintains its own
       internal cursor location which it uses  to  determine  where  on  the
       screen the next write will occur.

          Some applications which run in  real  time  (Such  as  a  terminal
       emulator)  do not call "vgetc",  but use "vtstc" to poll the keyboard
       on a regular basis.  In this case,  the "vupdatexy" routine should be
       called any time that the visual position of the cursor is important.

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


    EXAMPLES:

        vupdatexy();        /* position the cursor *
        c = vtstc();        /* Test for a character */
    MICRO-C PC Library                                               Page: 8



                     +------------------------------------+
                     |                                    |
                     |  ********************************  |
                     |  * The IBM-PC WINDOWING library *  |
                     |  ********************************  |
                     |                                    |
                     +------------------------------------+










    4. IBM-PC WINDOWING LIBRARY

          The MICRO-C WINDOWING LIBRARY is a set  of  powerful,  very  fast,
       compact,  text based windowing functions for  use  with  the  MICRO-C
       compiler,  on the IBM Personal  Computer.  Features  of  the  library
       include  multiple  open  windows,  overlaid  windows  with  automatic
       save/restore of screen underneath, scrolling within windows, optional
       window borders, menu and form entry functions, and more.

          The library is organized into two parts,  the first is  a  set  of
       assembly language routines  which  provides  the  basic  "low  level"
       functions to open/close windows,  and to output  data  in  them.  The
       second part of the library provides a  set  of  'C'  functions  which
       provide "high level" functions such as menu and form entry, formatted
       printing, etc.
    MICRO-C PC Library                                               Page: 9


          4.0.1 Window Control Block

                Whenever a new window is opened,  the windowing library sets
             up a WINDOW CONTROL  BLOCK  (WCB)  which  contains  information
             needed to access and control the window.  The format of the WCB
             is:

        Offset: 0   - Current video attribute *
                1   - Window flags (High 8 bits of w_open attrs) **
                2   - Absolute 'X' position of top left corner of
                      active region. ***
                3   - Absolute 'Y' position of top left corner of
                      active region. ***
                4   - Width in characters of active region ***
                5   - Height in characters of active region ***
                6   - Current 'X' cursor coordinate
                7   - Current 'Y' cursor coordinate
                8,9 - Pointer to previous window buffer
                10  - Previous cursor ENDING line
                11  - Previous cursor STARTING line
                12  - Previous cursor absolute 'X' position ****
                13  - Previous cursor absolute 'Y' position ****
                14..- Save area for SAVE/RESTORE function

        *       You may dynamically alter the video attribute of data
                written to the window by writing to this byte.

        **      You may dynamically alter the properties of the window by
                setting or clearing the flag bits with these exceptions:
                -DO NOT enable SAVE/RESTORE unless opened with it
                (It is Ok to disable SAVE/RESTORE).
                -DO NOT change the state of the BORDER bits.

        ***     For windows opened with a BORDER, this reflects the size
                of the active region (not including the border). Otherwise,
                this is the size of the entire window.

        ****    For full screen window which does not SAVE/RESTORE, you can
                set these values to zero to home cursor on exit.
    MICRO-C PC Library                                               Page: 10


          4.0.2 External Variables

                In addition to the  functions  described  on  the  following
             pages,  the windowing library provides the  following  external
             variables which are updated after any call to wopen() :

             4.0.2.1 extern int W_BASE

                   This variable contains the  base  address  of  the  video
                screen,  which may be used to determine the type of  display
                present:

                        B000 = Monochrome
                        B800 = Color

             4.0.2.2 extern unsigned char W_COLS

                   This variable contains the number  of  character  columns
                currently configured for the video display system.

             4.0.2.3 extern struct WINDOW *W_OPEN

                   This variable contains a  pointer  to  the  WCB  for  the
                "active" window, and controls which window is manipulated by
                certain library functions.  This  automatically  set  up  by
                "wopen"  to point to the last  window  opened,  but  may  be
                changed at any time with:

                                W_OPEN = window;

                   NOTE:  When the active window is closed,  W_OPEN is reset
                to point to the window which was active at the time that  it
                (the active window)  was opened.  If windows are  closed  in
                other than the reverse order  of  which  they  were  opened,
                W_OPEN may be left pointing to a window  which  has  already
                been closed.  If this happens, YOU MUST NOT USE THE "ACTIVE"
                WINDOW FUNCTIONS WITHOUT RESETTING W_OPEN  TO  POINT  TO  AN
                OPEN WINDOW. It is your (the programmer's) responsibility to
                insure that you know what window will  be  accessed  through
                W_OPEN at all times throughout your program.

             4.0.2.4 extern unsigned char W_PAGE

                   This variable contains the currently active video display
                page.

             4.0.2.5 extern unsigned char W_ROWS

                   This variable  contains  the  number  of  character  rows
                currently configured for the video display system.

          4.0.3 Window Library Functions

                The following pages contain a description of  each  function
             available in the IBM-PC windowing library.
    WCLEOL                                                           WCLEOL
    W_CLEOL                                                         W_CLEOL



    PROTOTYPE:

        wcleol()
        w_cleol(struct WINDOW *window)


    ARGUMENTS:

        window  - Pointer to WCB for an open window


    RETURN VALUE:

        None


    DESCRIPTION:

          The  "wcleol"  function clears the active window from the  current
       cursor position to the end of a line.

          The  "w_cleol"  function clears  the  specified  window  from  the
       current position to the end of the line.


    EXAMPLES:

        wputs("Input> ");       /* Display a prompt */
        wcleol();               /* Clear remainder of input line */
    WCLEOW                                                           WCLEOW
    W_CLEOW                                                         W_CLEOW



    PROTOTYPE:

        wcleow()
        w_cleow(struct WINDOW *window)


    ARGUMENTS:

        window  - Pointer to WCB for an open window


    RETURN VALUE:

        None


    DESCRIPTION:

          The  "wcleow"  function clears the active window from the  current
       position to the end of the window.

          The  "w_cleow"  function clears  the  specified  window  from  the
       current position to the end of the window.


    EXAMPLES:

        wgotoxy(0, 10);         /* position at line 11 */
        wcleos();               /* Clear lower part of screen */
    WCLOSE                                                           WCLOSE
    W_CLOSE                                                         W_CLOSE



    PROTOTYPE:

        wclose()
        w_close(struct WINDOW *window)


    ARGUMENTS:

        window  - Pointer to WCB for an open window

    RETURN VALUE:

        None


    DESCRIPTION:

          The "wclose" function closes the "active" window,  and deactivates
       it.

          The  "w_close"  function  closes   the   specified   window,   and
       deactivates it.

          If the window being closed is the "active"  window,  the  "active"
       window will revert to the window which was "active"  at the time that
       the window being closed was opened.


    EXAMPLES:

        wclose();       /* Close active window */
        w_close(title); /* Close the title window */
    WCLWIN                                                           WCLWIN
    W_CLWIN                                                         W_CLWIN



    PROTOTYPE:

        wclwin()
        w_clwin(struct WINDOW *window)


    ARGUMENTS:

        window  - Pointer to WCB for an open window


    RETURN VALUE:

        None


    DESCRIPTION:

          The  "wclwin"  function clears the entire active window and resets
       the cursor position to the top left hand corner.

          The  "w_clwin"  function clears the entire specified  window,  and
       resets the cursor position to the top left hand corner.


    EXAMPLES:

        if(c = 0x1b) {          /* Escape command */
            wclwin();           /* Clear the screen */
            wputs("Exiting back to main menu");
            return; }
    WCURSOR_BLOCK                                             WCURSOR_BLOCK



    PROTOTYPE:

        wcursor_block()


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          This function enables (turns on)  display of the cursor on the IBM
       PC video display.  The cursor is shown as flashing  block,  occupying
       the entire character window.


    EXAMPLES:

        if(insert)              /* Test insert mode flag */
            wcursor_block();    /* Indicate inserting with block cursor */
        else
            wcursor_line();     /* Indicate overwrite with line cursor */
    WCURSOR_LINE                                               WCURSOR_LINE



    PROTOTYPE:

        wcursor_line()


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          This function enables (turns on)  display of the cursor on the IBM
       PC video display.  The cursor is shown as a single flashing line,  at
       the bottom of the character window.


    EXAMPLES:

        wcursor_line();     /* Re-enable the cursor */
        exit(0);            /* And terminate */
    WCURSOR_OFF                                                 WCURSOR_OFF



    PROTOTYPE:

        wcursor_off()


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          This function inhibits  (turns off)  display of the cursor on  the
       IBM PC video display.  This affects the cursor display  only,  screen
       output will continue to be displayed at the correct cursor position.


    EXAMPLES:

        wclscr();           /* Clear screen */
        wcursor_off();      /* Inhibit cursor */
        wmenu(10, 10, 0x6007, main_menu, &index); /* Present main menu */
    WFORM                                                             WFORM



    PROTOTYPE:

        register int wform(int x, int y, int attrs, char *prompts[],
                       char *strings,  ...)


    ARGUMENTS:

        x       - Absolute COLUMN of upper left corner of form window
        y       - Absolute ROW    of upper left corner of form window
        attrs   - Attributes for form window (See WOPEN)
        prompts - Prompt string for form entries
        strings - Destination string to receive form data
        ...     - Additional arguments may be required


    RETURN VALUE:

        0       = Form was exited with ENTER (at last field)
        !0      = Form was exited with ESCAPE


    DESCRIPTION:

          The  "wform"  function opens a window,  which  contains  a  "form"
       consisting of prompts and data areas.  Each data area is shown beside
       its corresponding prompt,  and may be edited using the keys supported
       by WGETS.  the UP and DOWN ARROW keys may be used to move the editing
       cursor between the various fields in the input form.*

          The "attrs" argument contains the open attributes (see WOPEN)  for
       the menu window,  and may be  used  to  control  the  color,  border,
       clearing, etc.

          The "prompts"  argument is an array of pointers to strings,  which
       define the prompts and input  fields  in  the  form.  The  first  two
       characters of each string define the 'X'  and 'Y'  coordinates within
       the window of the prompt string.  The third  character  contains  the
       length of the destination string,  and the remainder  of  the  string
       contains the text prompt. The destination string is positioned in the
       window directly following the prompt string.  This  list  of  prompts
       must end with a NULL (0) element.

          The first  (0)  element of "prompts" does not actually point to an
       input definition, but contains the X and Y sizes for the window to be
       opened (High byte = X, Low byte = Y).

          Following the  "prompts"  argument,  there must be one destination
       "string"  argument for each prompt defined.  The strings must be long
       enough to contain the number of characters  specified  in  the  third
       byte of the corresponding "prompt" string.
          Only the lower seven bits of the field length are used  (length  =
       1-127),  the high bit indicates that the field is to contain  numbers
       only.  In this case, the corresponding argument is NOT a pointer to a
       string, but must be a pointer to an "int" variable.

          The form is exited by pressing the ESCAPE key.



    EXAMPLES:

        /* Sample input form */
            char *form[] = {
                50<<8|6,        /* Place in 50 by 6 window */
                "\x01\x00\x20Software  :",
                "\x01\x01\x20Author    :",
                "\x01\x02\x20Directory :",
                "\x01\x03\x20Filename  :",
                0 };

        /* Data areas for input form */
            char software[0x21] = "MICRO-C",
                author[0x21]    = "Dave Dunfield",
                direct[0x21]    = "C:\\MC",
                filename[0x21]  = "MC*.*";

        /* Simple main program to display the form */
        main()
        {
            wform(15, 9, 0xE007, form, software, author, direct, filename);
        }
    WGETC                                                             WGETC
    W_GETC                                                           W_GETC



    PROTOTYPE:

        int wgetc()
        int w_getc(struct WINDOW *window)


    ARGUMENTS:

        window  - Pointer to WCB for an open window


    RETURN VALUE:

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


    DESCRIPTION:

          The  "wgetc"  function waits until a key is pressed on the  system
       console, and returns its value. The cursor is updated to be placed at
       the current cursor position in the active window.

          The  "w_getc"  function waits until a key is pressed on the system
       console, and returns its value. The cursor is updated to be placed at
       the current cursor position in the specified window.

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


    EXAMPLES:

        switch(wgetc()) {       /* Handle input keys
                . . .
        }
    WGETS                                                             WGETS



    PROTOTYPE:

        int wgets(int x, int y, char *string, int length)


    ARGUMENTS:

        x       - COLUMN position for input
        y       - ROW    position for input
        string  - Destination string
        length  - Length of string (High bit set = Numbers only)


    RETURN VALUE:

        Character causing exit


    DESCRIPTION:

          The "wgets" function positions the cursor at the specified X and Y
       coordinates,  and displays the contents of  "string"  (in a field  of
       "length" characters), and waits for input,  which may be used to edit
       the string.

          Any normal ASCII characters which are input will be  entered  into
       the string, The following function keys are recognized:

            LEFT ARROW          - Position cursor one space to the left
            RIGHT ARROW         - Position cursor one space to the right
            BACKSPACE           - Backup cursor & delete previous character
            DELETE              - Delete character under cursor
            INSERT              - Toggle between INSERT/OVERWRITE
            HOME                - Position cursor at start of string
            END                 - Position cursor at end of string
            PAGE UP             - Clear entire field
            PAGE DOWN           - Clear from cursor to end of field

          Any other special function keys will cause  "wgets"  to terminate,
       and return the value of the offending key.  (See  "window.h"  for key
       definitions).

          When INSERT mode is enabled,  all entered text  will  be  inserted
       into the string,  with the remainder of the string  shifting  to  the
       right. This mode is indicated by a flashing BLOCK cursor.

          When OVERWRITE mode is enabled,  all entered text  will  overwrite
       the existing string.  This mode  is  indicated  by  a  flashing  LINE
       cursor.


    EXAMPLES:

        wgets(2, 5, name, 25);
    WGOTOXY                                                         WGOTOXY
    W_GOTOXY                                                       W_GOTOXY



    PROTOTYPE:

        wgotoxy(int x, int y)
        w_gotoxy(int x, int y, struct WINDOW *window)


    ARGUMENTS:

        x       - New COLUMN
        y       - New ROW
        window  - Pointer to WCB for an open window


    RETURN VALUE:

        None


    DESCRIPTION:

          The  "wgotoxy"  function positions the cursor  within  the  active
       window.  Any further display output to that window will occur at  the
       new ROW and COLUMN positions.

          The "w_gotoxy"  function positions the cursor within the specified
       window.  Any further display output to that window will occur at  the
       new ROW and COLUMN positions.


    EXAMPLES:

        for(i=0; i<10; ++i) {   /* Draw a diagonal line of 'X's */
            wgotoxy(i, i);
            wputc('X'); }
    WMENU                                                             WMENU



    PROTOTYPE:

        int wmenu(int x, int y, int attrs, char *names[], int &index)


    ARGUMENTS:

        x       - Absolute COLUMN of top left corner of menu window
        y       - Absolute ROW    of top left corner of menu window
        attrs   - Attributes for menu window (see WOPEN)
        names   - Array to menu selection text (last entry = 0)
        index   - Address of message selection index variable


    RETURN VALUE:

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


    DESCRIPTION:

          The  "wmenu"  function opens a window containing a  list  of  menu
       items at the specified ROW and COLUMN address.  The user may use  the
       UP, DOWN,  HOME and END keys to select an entry by moving the INVERSE
       VIDEO selection cursor.  Pressing an alphanumeric key  will  position
       the  selection  bar  to  the  first  entry  which  begins  with  that
       character.

          When the desired selection is under the cursor,  the selection  is
       made by pressing the ENTER key.

          At any time the menu selection may be  canceled  by  pressing  the
       ESCAPE key.

          The "attrs" argument contains the open attributes (see WOPEN)  for
       the menu window,  and may be  used  to  control  the  color,  border,
       clearing, etc.

          The  "names"  argument must be a pointer to an array of  character
       strings which are the selections to display. This array MUST end with
       a NULL (0) element to indicate the end of the list.

          The  "index"  argument is the address of an  "int"  variable which
       contains the position of the selection cursor.  It controls where the
       selection cursor will appear when the function is first invoked  (0 =
       first entry),  and also is assigned the  position  of  the  selection
       cursor when the selection is made.

          Once a selection is made,  the first character of  that  selection
       will be hilighted in reverse video.




    EXAMPLES:

        char *names[] = { "One", "Two", "Three", "Four", "Five", 0 };
            . . .
        index = 0;
        if(wmenu(10, 10, 0xE007, names, &index))
            return;         /* Aborted, exit to higher level */
        switch(index) {     /* Handle selection */
            . . .
        }
    WMESSAGE                                                       WMESSAGE



    PROTOTYPE:

        int wmessage([char *keys,] int options, int attrs, char *text)


    ARGUMENTS:

        keys        - String of key characters to accept (optional)
        options     - Positioning/control information (see below)
        attrs       - Window open attributes (see wopen)
        text        - Text to display in message box


    RETURN VALUE:

        The key code pressed to exit the window.


    DESCRIPTION:

          This function displays a message  in  a  separate  window  on  the
       screen.  The message may contain multiple lines separated by  newline
       ('\n') characters, the window will be automatically sized to just fit
       the entire message.

          The 'options' value has the following bit format: CxxxxxxxKyyyyyyy

            C       - Center window on screen (ignore xxxxxxx/yyyyyyy)
            xxxxxxx - X position of window (if 'C' not set)
            K       - Optional list of 'keys' is provided
            yyyyyyy - Y position of window (if 'C' not set)

          If the  'K'  bit is set,  an optional first argument is  expected,
       which contains a null terminated  list  of  all  keycodes  which  are
       accepted to terminate  the  message  box.  Any  other  keys  will  be
       ignored.  If the 'K'  bit is not set,  any keycode will terminate the
       window.

       Note:  To center the message,  wmessage()  uses the W_ROWS and W_COLS
       values established by a previous wopen().  If wmessage()  is executed
       without any prior wopen(), screen dimensions of 80 x 25 are assumed.


    EXAMPLES:

        wmessage("QqSs", WMSG_CENTER|WMSG_KEY, WSAVE|WCOPEN|WBOX2|REVERSE,
            "Press 'Q' to quit\nor 'S' to save");
    WOPEN                                                             WOPEN



    PROTOTYPE:

        struct WINDOW *wopen(int x, int y, int width, int height, int attrs)


    ARGUMENTS:

        x       - Absolute COLUMN of top left corner of window
        y       - Absolute ROW    of top left corner of window
        width   - The width of the window in characters
        height  - The height of the window in characters
        attrs   - The window attributes, BIT definitions:
                    15 - Enable SAVE/RESTORE screen under window
                *   14 - Enable SINGLE line BORDER
                *   13 - Enable DOUBLE line BORDER
                    12 - Enable CLEAR on OPEN
                **  11 - Enable CLEAR on CLOSE
                *** 10 - Disable NEWLINE (LF only)
                     9 - Enable SCROLLING in window
                     8 - Enable LINE WRAP in window
                   7-0 - Video attributes for window

            *   When BORDER is selected, window will include an enclosing
                BOX. In this case, the effective height and width of the
                active region (where text data can be written) will be
                reduced by 2.

            **  Has no visual effect when SAVE/RESTORE is enabled.

            *** If this BIT is set, CTRL-J will behave as LINEFEED only,
                and will not return the cursor to the left margin.

    RETURN VALUE:

        A pointer to the WCB for the newly opened window
        0 if the window could not be opened


    DESCRIPTION:

          The "wopen"  function creates a new window on the PC video screen.
       This newly created window is also made the "active" window,  which is
       automatically accessed by many of the windowing functions.

          If  "wopen"  is unable to allocate enough memory  for  the  window
       control block (WCB), it will fail and return a value of zero (0).


    EXAMPLES:

        /* Create a title window at top of screen */
        titlewin = wopen(0, 0, 80, 3, 0x6047);
    WPRINTF                                                         WPRINTF
    W_PRINTF                                                       W_PRINTF



    PROTOTYPE:

        register int wprintf(char *format, arg, ...)
        register int w_printf(struct WINDOW *window, char *format, arg, ...)


    ARGUMENTS:

        window  - Pointer to WCB for an open window
        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 "wprintf"  function performs exactly as the "PRINTF"  function
       in the standard function library,  except that it outputs directly to
       the active window using the low level windowing library functions.

          The "w_printf" function behaves similar to "wprintf",  except that
       the window to receive the output is specified as the first parameter.

          These functions should be used  in  preference  to  "PRINTF"  when
       using the windowing function library since "PRINTF" will not move the
       windowing librarys cursor,  will not use the attributes from the WCB,
       and will not respect the boundary's of the window.

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


    EXAMPLES:

        wgotoxy(0, 0);
        wprintf("Window %u", screen);
    WPUTC                                                             WPUTC
    W_PUTC                                                           W_PUTC



    PROTOTYPE:

        wputc(int c)
        w_putc(int c, struct WINDOW *window)


    ARGUMENTS:

        c       - Character to be written to window


    RETURN VALUE:

        None


    DESCRIPTION:

          This "wputc" function displays a character in the active window at
       the current cursor position.

          The "w_putc" function displays a character in the specified window
       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
       (Assuming those options are enabled in the window).

          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.

          The first byte of the window control block  (WCB)  for the  window
       contains the attributes which will be used to display the  character.
       This value is written to the attribute location associated  with  the
       character on the video display hardware.  Its effect is dependent  on
       the video  adapter  in  use.  The  "window.h"  header  file  contains
       definitions of the attribute bits for use  on  "standard"  monochrome
       and color displays.


    EXAMPLES:

        w_putc(0x0A, window1);      /* Line-feed, advance cursor */
        wputc(0x0A | 0xff00);       /* Display 0x0A character code */
    WPUTF                                                             WPUTF



    PROTOTYPE:

        wputf(char *string, int width)


    ARGUMENTS:

        string  - Pointer to character string
        width   - Width of output field


    RETURN VALUE:

        None


    DESCRIPTION:

          The  "wputf"  function outputs a character string  to  the  active
       window screen using the video library functions.

          The string is left justified in a field of the specified width. If
       the string is shorter than "width",  the field is padded with blanks.
       If the string is longer than "width", the output is truncated.


    EXAMPLES:

        wputf(message, 10); 
    WPUTS                                                             WPUTS
    W_PUTS                                                           W_PUTS



    PROTOTYPE:

        wputs(char *string)
        w_puts(char *string, struct WINDOW *window)


    ARGUMENTS:

        string  - Pointer to character string
        window  - Pointer to WCB for an open window


    RETURN VALUE:

        None


    DESCRIPTION:

          The  "wputs"  function outputs a character string  to  the  active
       window.

          The  "w_puts"  function output a character string to the specified
       window.


    EXAMPLES:

        wputs(message);
        w_puts(message, window1);
    WTSTC                                                             WTSTC
    W_TSTC                                                           W_TSTC



    PROTOTYPE:

        int wtstc()
        int w_tstc(struct WINDOW *window)


    ARGUMENTS:

        window  - Pointer to WCB for an open window


    RETURN VALUE:

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


    DESCRIPTION:

          The  "wtstc"  function tests for  a  key  pressed  on  the  system
       console, and returns its value.  If a character is found,  the cursor
       is updated in the active window.

          The  "w_tstc"  function tests for a  key  pressed  on  the  system
       console, and returns its value.  If a character is found,  the cursor
       is updated in the specified window.

          A returned value of zero (0) indicates that no key was found to be
       pressed.

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


    EXAMPLES:

        if(wtstc() == 0x1B) /* exit loop on ESCAPE key */
            break;
    WUPDATEXY                                                     WUPDATEXY
    W_UPDATEXY                                                   W_UPDATEXY



    PROTOTYPE:

        wupdatexy()
        w_updatexy(struct WINDOW *window)


    ARGUMENTS:

        window  - Pointer to WCB for an open window


    RETURN VALUE:

        None


    DESCRIPTION:

          The  "wupdatexy"  function updates the real X/Y cursor position on
       the video screen to reflect the  "logical"  position where  the  next
       character will be output in the active window.

          The "w_updatexy"  function updates the real X/Y cursor position on
       the video screen to reflect the  "logical"  position where  the  next
       character will be output in the specified window.

          The MICRO-C Windowing library uses a BIOS interrupt  (INT  10)  to
       position the cursor,  which is quite slow,  compared to the speed  of
       the library video routines.  To prevent this from  slowing  down  the
       video output,  the cursor is  only  physically  repositioned  when  a
       "wgotoxy" or a "wgetc" is executed.

          This allows the library routines to run at full speed,  and  still
       put the cursor in the right place when  output  stops  and  an  input
       request is made.

          A side effect of this is that the cursor on the  screen  will  not
       appear to move unless  you  call  "wgotoxy"  or  "wgetc".  This  only
       affects the physical cursor on the screen,  MICRO-C maintains its own
       internal cursor location which it uses  to  determine  where  on  the
       screen the next write will occur.

          Some applications which run in  real  time  (Such  as  a  terminal
       emulator)  do not call "wgetc",  but use "wtstc" to poll the keyboard
       on a regular basis.  In this case,  the "wupdatexy" routine should be
       called any time that the visual position of the cursor is important.


    EXAMPLES:

        wupdatexy();        /* position the cursor *
        c = wtstc();        /* Test for a character */
    MICRO-C PC Library                                               Page: 11



                 +-------------------------------------------+
                 |                                           |
                 |  ***************************************  |
                 |  * The IBM-PC low-res graphics library *  |
                 |  ***************************************  |
                 |                                           |
                 +-------------------------------------------+










    5. IBM-PC LOW-RES GRAPHICS LIBRARY

          The MICRO-C LOW-RES GRAPHICS LIBRARY is a set of fast compact  low
       resolution graphics routines suitable for  games  and  other  low-res
       applications. The routines require a VGA display adapter, and operate
       at a resolution of 320 by 200 in 256 colors.  Features of the library
       include fast hand crafted assembly functions for:  plot  pixel,  fill
       screen,  vertical and horizontal lines,  and sprite draw  and  erase.
       Additional functions are provided for drawing character data,  lines,
       boxes, circles, and arc's.

          The library is organized into two parts,  the first is  a  set  of
       assembly language routines  which  provides  the  basic  "low  level"
       functions to access the video buffer.  The second part of the library
       provides a set of 'C' functions which provide "high level"  functions
       drawing circles and boxes.

          A utility program SPRITED is supplied with MICRO-C  which  can  be
       used to create and edit sprite images for use with the library sprite
       functions.
    LRG_ARC                                                         LRG_ARC



    PROTOTYPE:

        lrg_arc(int x, int y, int r, int s_angle, int e_angle, int color)


    ARGUMENTS:

        x       - X coordinate for center of arc
        y       - Y coordinate for center of arc
        r       - radius of arc
        s_angle - Angle to start of arc (0-255)
        e_angle - Angle to end of arc (0-255)
        color   - Color to set arc

    RETURN VALUE:

        None


    DESCRIPTION:

          The  "lrg_arc"  function draws an arc on the screen.  The  arc  is
       drawn clockwise, beginning at s_angle, and ending at e_angle.  Angles
       are described with a value in the range of 0-255, where 0 is straight
       up, 64 is straight right,  128 is straight down,  and 192 is straight
       left.

          Note that  due  to  aspect  ratio  correction,  the  radius  value
       represents  the  number  of  pixels  between  the  center,  and   the
       horizontal limits of the arc. The number of pixels between the center
       and the vertical limits is 4/5's of the radius.


    EXAMPLES:

        lrg_arc(100, 100, 50, 192, 64, WHITE);  /* Draw a dome shape */
    LRG_BLIT                                                       LRG_BLIT



    PROTOTYPE:

        lrg_blit(int x, int y, int width, int height, char *image)


    ARGUMENTS:

        x       - X coordinate to draw image
        y       - Y coordinate to draw image
        width   - Width of image
        height  - Height of image
        image   - Image data

    RETURN VALUE:

        None


    DESCRIPTION:

          The "lrg_blit" function performs a high-speed block image transfer
       from local memory to the video screen.  The image is  transferred  to
       the screen at the specified coordinates. Image data consists of color
       values  (bytes),  arranged row by row.  The video content replaced by
       the image is not saved.

          Image data can be easily created using the SPRITED  sprite  editor
       supplied with the Micro-C/PC package. Simply drop the first two bytes
       from the saved sprite (the height and width)  before using the sprite
       data as a binary image for "lrg_blit".


    EXAMPLES:

        for(x=0; x < 320; x += 20)
            for(y=0; y < 200; y += 20)
                lrg_blit(x, y, 20, 20, background);
    LRG_BOX                                                         LRG_BOX
    LRG_FBOX                                                       LRG_FBOX



    PROTOTYPE:

        lrg_box(int x, int y, int width, int height, int color)
        lrg_fbox(int x, int y, int width, int height, int color)


    ARGUMENTS:

        x       - X coordinate for top left corner of box
        y       - Y coordinate for top left corner of box
        width   - Width of box
        height  - Height of box
        color   - Color to set box

    RETURN VALUE:

        None


    DESCRIPTION:

          The "lrg_box" function draws a box outline on the screen.
          The "lrg_fbox" functions draws a filled (solid) box on the screen.


    EXAMPLES:

        lrg_box(0, 0, 320, 200, WHITE); /* Draw box/border around screen */
        lrg_fbox(0, 0, 320, 200, WHITE);/* Equivalent to lrg_fill(7) */
    LRG_CIRCLE                                                   LRG_CIRCLE
    LRG_FCIRCLE                                                 LRG_FCIRCLE



    PROTOTYPE:

        lrg_circle(int x, int y, int radius, int color)
        lrg_fcircle(int x, int y, int radius, int color)


    ARGUMENTS:

        x       - X coordinate for center of circle
        y       - Y coordinate for center of circle
        radius  - Radius of circle
        color   - Color to set circle

    RETURN VALUE:

        None


    DESCRIPTION:

          The "lrg_circle" function draws a circle on the screen.
          The "lrg_fcircle"  function draws a filled  (solid)  circle on the
       screen.

          Note that  due  to  aspect  ratio  correction,  the  radius  value
       represents  the  number  of  pixels  between  the  center,  and   the
       horizontal limits of the circle.  The number of  pixels  between  the
       center and the vertical limits is 4/5's of the radius.


    EXAMPLES:

        lrg_circle(100, 100, 50, WHITE);    /* Draw circle outline */
        lrg_fcircle(220, 100, 50, WHITE);   /* Draw solid circle */
    LRG_CLOSE                                                     LRG_CLOSE



    PROTOTYPE:

        lrg_close()


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          The "lrg_close" function resets the VGA display to text mode.  You
       should call this  function  when  you  are  finished  with  graphical
       output, and wish to resume a standard display.


    EXAMPLES:

        lrg_close();            /* Reset the display */
        exit(0);                /* and terminate */
    LRG_DELAY                                                     LRG_DELAY



    PROTOTYPE:

        lrg_delay(unsigned frames)


    ARGUMENTS:

        frames  - Number of video frames to wait


    RETURN VALUE:

        None


    DESCRIPTION:

          The  "lrg_delay"  function waits for the specified number of video
       frames to occur before continuing.  Video frames are drawn by the VGA
       hardware at a rate of 70 frames per  second,  which  the  delay  time
       specify a multiple of 1/70th second.

          This function always  exits  at  the  beginning  of  the  vertical
       retrace interval, which is the ideal time to perform video updates.


    EXAMPLES:

        for(i=0; i < 100; ++i) {    /* Move a sprite along the screen */
            lrg_draw(i, i, sprite_data, save_area);
            lrg_delay(5);
            lrg_erase(i, i, sprite_data, save_area); }
    LRG_DRAW                                                       LRG_DRAW
    LRG_ERASE                                                     LRG_ERASE



    PROTOTYPE:

        lrg_draw(int x, int y, char *sprite, char *save)
        lrg_erase(int x, int y, char *sprite, char *save)


    ARGUMENTS:

        x       - X coordinate to draw/erase sprite
        y       - Y coordinate to draw/erase sprite
        sprite  - Sprite data
        save    - Save area for screen data

    RETURN VALUE:

        None


    DESCRIPTION:

          The "lrg_draw" function draws a sprite graphic on the video screen
       at the specified coordinates.  The first two characters of the sprite
       data must contain the X and Y dimensions of the sprite. The remaining
       bytes of data are color values,  which represent the sprite,  row  by
       row.  Color 0 is a special case,  and represents "transparent" color.
       Any pixels of the sprite which contain color 0  will  not  be  drawn,
       allowing the original screen to show through.

          The save area will be written with the old content of  any  pixels
       which are overwritten by the sprite. This area must have at least one
       byte of memory for every non-zero pixel in the sprite.

          The  "lrg_erase"  function  erases  a  sprite  from  the   screen,
       restoring the original video data.

          Sprite data can be easily created using the SPRITED sprite  editor
       supplied with the Micro-C/PC package.


    EXAMPLES:

        for(x=0; x < 300; ++x) {        /* Move sprite across screen */
            lrg_draw(x, 190, sprite, save);
            delay(50);
            lrg_erase(x, 190, sprite, save); }
    LRG_FILL                                                       LRG_FILL



    PROTOTYPE:

        lrg_fill(int color)


    ARGUMENTS:

        color   - Color to set in video buffer

    RETURN VALUE:

        None


    DESCRIPTION:

          The "lrg_fill"  function clears the video display buffer,  filling
       all pixels with the specified color.


    EXAMPLES:

        lrg_fill(BLACK);        /* Clear the screen to BLACK */
    LRG_GETPAL                                                   LRG_GETPAL
    LRG_SETPAL                                                   LRG_SETPAL



    PROTOTYPE:

        lrg_getpal(int index, unsigned char palette[3])
        lrg_setpal(int index, unsigned char palette[3])


    ARGUMENTS:

        index   - Color index (0-255)
        palette - Red/Green/Blue entries for color

    RETURN VALUE:

        None


    DESCRIPTION:

          The  "lrg_getpal"  function gets the palette entry for any one  of
       the 256 colors available on the display.  The palette array  will  be
       filled in with the Red,  Green and Blue intensity  settings  for  the
       specified color index.

          The  "lrg_setpal"  function sets the palette entry for any one  of
       the 256 colors available on  the  display.  The  palette  array  must
       contain the desired Red,  Green and Blue intensity settings  the  the
       specified color index.  By varying these intensities, you can control
       the mix of these primary colors,  and create any one of over  262,144
       distinct hue's.


    EXAMPLES:

        static unsigned char array[] = { 63, 0, 0 };
        lrg_setpal(50, array);      /* Set color #50 to bright red */
        lrg_fill(50);               /* Set entire screen bright red */
    LRG_HLINE                                                     LRG_HLINE
    LRG_VLINE                                                     LRG_VLINE



    PROTOTYPE:

        lrg_hline(int x, int y, int length, int color)
        lrg_vline(int x, int y, int length, int color)


    ARGUMENTS:

        x       - X coordinate for start of line
        y       - Y coordinate for start of line
        color   - Color to set line

    RETURN VALUE:

        None


    DESCRIPTION:

          The  "lrg_hline"  function draws a horizontal line at high  speed.
       The X and Y parameters specify the leftmost point of the line. A line
       of "length" pixels is drawn to the right from this point.

          The "lrg_vline" function draws a vertical line at high speed.  The
       X and Y parameters specify the highest point of the line.  A line  of
       "length" pixels is drawn downward from this point.


    EXAMPLES:

        lrg_hline(0, 0, 320, WHITE);
        lrg_hline(0, 199, 320, WHITE);
        lrg_vline(0, 0, 200, WHITE);
        lrg_vline(319, 0, 200, WHITE);
    LRG_LINE                                                       LRG_LINE



    PROTOTYPE:

        lrg_line(int x1, int y1, int x2, int y2, int color)


    ARGUMENTS:

        x1      - X coordinate for first end of line
        y1      - Y coordinate for first end of line
        x2      - X coordinate for second end of line
        y2      - Y coordinate for second end of line
        color   - Color to set line

    RETURN VALUE:

        None


    DESCRIPTION:

          The "lrg_line"  function draws a line between two arbitrary points
       on the screen.


    EXAMPLES:

        lrg_line(10, 10, 310, 190, WHITE);  /* Draw line across screen */
    LRG_OPEN                                                       LRG_OPEN



    PROTOTYPE:

        int lrg_open()


    ARGUMENTS:

        None


    RETURN VALUE:

        0 on success, !0 if VGA mode unsupported.


    DESCRIPTION:

          The "lrg_open" function switches the VGA display into mode 13, 320
       by 200 256 color graphics.  You must call this function before  using
       any other routines in the LRG library.


    EXAMPLES:

        if(lrg_open())
            abort("VGA required!");
    LRG_PLOT                                                       LRG_PLOT



    PROTOTYPE:

        lrg_plot(int x, int y, int color)


    ARGUMENTS:

        x       - X coordinate for pixel (0-319)
        y       - Y coordinate for pixel (0-199)
        color   - Color to set pixel

    RETURN VALUE:

        None


    DESCRIPTION:

          The  "lrg_plot"  function sets an individual pixel  on  the  video
       screen to the specified color.


    EXAMPLES:

        for(i=0; i < 100; ++i)
            lrg_plot(i, i, WHITE);  /* Draw a diagonal line in white */
    LRG_PRINTF                                                   LRG_PRINTF



    PROTOTYPE:

        register int lrg_printf(int x, int y, int c, char *format, arg, ...)


    ARGUMENTS:

        x       - X coordinate for output string
        Y       - Y coordinate for output string
        C       - Color of output string: (background << 8) + foreground
        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  "lrg_printf"  function  performs  exactly  as  the   "PRINTF"
       function in the standard function library,  except  that  it  outputs
       directly to the video screen using the LRG library functions.

          These functions should be used  in  preference  to  "printf"  when
       using the LRG library since "printf" outputs via dos, and may corrupt
       the graphics screen.

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


    EXAMPLES:

        lrg_printf(308, 0, (RED<<8)|WHITE, "SCORE %u", score);
    LRG_PUTC                                                       LRG_PUTC
    LRG_PUTS                                                       LRG_PUTS



    PROTOTYPE:

        lrg_putc(int x, int y, int color, char c)
        lrg_putc(int x, int y, int color, char *s)


    ARGUMENTS:

        x       - X coordinate for character/string
        y       - Y coordinate for character/string
        color   - Color of character(s): (background <<8) + foreground
        c       - Character to display
        s       - String to display

    RETURN VALUE:

        None


    DESCRIPTION:

          The "lrg_putc" function draws a single character on the screen.
          The  "lrg_puts"  function draws a  string  of  characters  on  the
       screen.

          The lower 8 bits of the color argument is used for the  foreground
       color,  and the higher 8 bits of the color argument is used  for  the
       background color.

          The characters are drawn using the 8x8 character set from  the  PC
       BIOS ROM.


    EXAMPLES:

        lrg_putc(100, 50, (BLUE<<8)|RED, '$');  /* '$' - red on blue  */
        lrg_puts(100, 100, WHITE, "Hello"); /* "Hello" - white on black */
    LRG_RETRACE                                                 LRG_RETRACE



    PROTOTYPE:

        lrg_retrace()


    ARGUMENTS:

        None


    RETURN VALUE:

        None


    DESCRIPTION:

          The  "lrg_retrace"  function waits until the video hardware is  at
       the beginning of it's vertical retrace interval.  During the vertical
       retrace  interval,  the  screen  may  be  updated  without  noise  or
       "glitches"  caused by conflicts between the program access  to  video
       memory, and the VGA hardware access to video memory.


    EXAMPLES:

        lrg_retrace();
        draw(x, y, sprite_data, save_area);



                               MICRO-C PC Library

                               TABLE OF CONTENTS


                                                                         Page

     1. ALPHABETICAL FUNCTION INDEX                                         1


     2. STANDARD LIBRARY                                                    6


     3. IBM-PC/MS-DOS LIBRARY                                               7


     4. IBM-PC WINDOWING LIBRARY                                            8


     5. IBM-PC LOW-RES GRAPHICS LIBRARY                                    11

