home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_200 / 259_01 / conio.doc < prev    next >
Text File  |  1988-02-25  |  10KB  |  392 lines
  1.  
  2.  
  3.                        CONIO -- Console I/O Routines for C
  4.  
  5.  
  6.        DISCLAIMER:
  7.  
  8.        This file and all of the files distributed with it were created by 
  9.        Jeff D. Pipkins at Quality Micro Systems, Inc. (QMS) in Mobile, AL. 
  10.        and are hereby released into the public domain on authority of Dr. 
  11.        Don Parker.  Although QMS (R) believes these files to perform as 
  12.        described in the accompanying documentation, QMS assumes absolutely 
  13.        no responsibility for any of these files, since they are now public 
  14.        domain.  Furthermore, QMS is not obligated in any way to maintain 
  15.        or support these files. 
  16.  
  17.  
  18.  
  19.        CONIO FILES:
  20.  
  21.        CONIO.ASM  Source code for putch(), getch(), getche(), ungetch(), 
  22.                   and kbhit(). 
  23.        CONIO.NER  OBJect code for small and compact memory models
  24.        CONIO.FAR  OBJect code for medium, large, and huge memory models.
  25.        CONIO.BAT  Batch file for installing CONIO into your MSC libraries.
  26.        CONIO.DOC  Print this file at 12 cpi (ELITE)
  27.        CONIO.H    NOT INCLUDED HERE -- It is assumed that you have this 
  28.                   file from the Microsoft C distribution discs.  I cannot 
  29.                   include it here because it is copyrighted.  Note that it 
  30.                   contains only function declarations. 
  31.  
  32.  
  33.        STATEMENT OF PURPOSE:
  34.  
  35.        The routines in CONIO.ASM are meant as replacements for the 
  36.        corresponding routines found in the Microsoft (R) C libraries.  The 
  37.        new routines correct problems and offer enhancements.  The source 
  38.        code is included so that the routines may be (easily) adapted to 
  39.        work with other C compilers that run on IBM (R) PC compatibles.  
  40.        The specifications for these routines are offered to The C User's 
  41.        Group as a working standard for machine-independent console I/O. 
  42.  
  43.  
  44.        COMMERCIAL:
  45.  
  46.                                      QMS (R)
  47.                            Where Imagination Leads (TM)
  48.  
  49.        This documentation file would look as good as the pages in the 
  50.        Microsoft (R) C library reference if you printed them on one of 
  51.        QMS' 300 dpi (dots per inch) laser printers!  (You could even print 
  52.        on both sides of the paper!)  QMS is the maker of the KISS (R) 
  53.        laser printer, the first laser printer priced under $2000.  You can 
  54.        call QMS at (205) 633-4300 to inquire about our full range of 
  55.        printers or about any new printers introduced since this the 
  56.        release of this file. 
  57.  
  58.  
  59.  
  60.        putch
  61.  
  62.  
  63.  
  64.        o  Summary
  65.  
  66.        #include <conio.h>      /*  Function declarations only  */
  67.  
  68.        void putch(c);
  69.           int c;          /*  Character to be sent to console  */
  70.  
  71.  
  72.        o  Description
  73.  
  74.        The putch function writes the character (c) directly to the 
  75.        console. 
  76.  
  77.        Redirection of stdout has NO EFFECT on this function.  
  78.        Output is ALWAYS sent specifically to the console device. 
  79.  
  80.        The putch function will automatically preceed any line 
  81.        feeds with a carriage return, so that putch('\n') has the 
  82.        desired effect. 
  83.  
  84.        After displaying the character, putch checks the keyboard 
  85.        for a Ctrl-C (break) or a Ctrl-S (pause), and handles them 
  86.        appropriately. 
  87.  
  88.  
  89.        o  Return Value
  90.  
  91.        There is no return value.
  92.  
  93.  
  94.        o  See Also
  95.  
  96.        putchar, putc, getch, getche, ungetch, kbhit, cprintf, 
  97.        cscanf, cputs, cgets 
  98.  
  99.  
  100.  
  101.        putch (continued)
  102.  
  103.  
  104.  
  105.        o  Example
  106.  
  107.        #include <conio.h>
  108.  
  109.        void prompt()
  110.        {
  111.           putch('\n');
  112.           putch('A');
  113.           putch('>');
  114.        }
  115.  
  116.  
  117.        
  118.        getch
  119.  
  120.  
  121.  
  122.        o  Summary
  123.  
  124.        #include <conio.h>      /*  Function declarations only  */
  125.  
  126.        int getch();
  127.  
  128.  
  129.        o  Description
  130.  
  131.        The getch function reads, without echoing, a single 
  132.        character directly from the console (keyboard). 
  133.  
  134.        If no key has been pressed, and there are no keys in the 
  135.        ungetch buffer, getch will wait for a key to be pressed 
  136.        before returning. 
  137.  
  138.        Redirection of stdin has NO EFFECT on this function.  Input 
  139.        is ALWAYS read specifically from the console (keyboard) 
  140.        device. 
  141.  
  142.        The character read is NOT echoed to the console (screen).
  143.  
  144.        Carriage returns are translated to line feeds so that a 
  145.        program can check for the ENTER (or RETURN) key by 
  146.        comparing the character to '\n', as usual. Line feeds are 
  147.        translated to carriage returns so that a discriminating 
  148.        program can tell the difference. 
  149.  
  150.        If the character to be returned is a Ctrl-C (break) or a 
  151.        Ctrl-S (pause), appropriate action is taken. 
  152.  
  153.  
  154.  
  155.  
  156.        
  157.        getch (continued)
  158.  
  159.  
  160.  
  161.        o  Return Value
  162.  
  163.        The getch function returns the character read.  There is no 
  164.        error return. Note that getch never returns zero, Ctrl-C, 
  165.        or Ctrl-S.  Also, Ctrl-Z is NOT translated to EOF (-1). 
  166.  
  167.        IBM (R) PC compatible keyboards have some special keys that 
  168.        have no ASCII character codes.  The following scheme is 
  169.        employed to accomodate these keys: If the key has an ASCII 
  170.        value, it is returned as an integer.  If the key does not 
  171.        have an ASCII value (e.g. a function key or an arrow key), 
  172.        then the value returned has the low byte zero and the high 
  173.        byte will hold the scan code for the key pressed.  For a 
  174.        complete list of these scan codes, see the IBM Technical 
  175.        Reference (#6025005), "Keyboard Scan Codes", or one of 
  176.        Peter Norton's books on the IBM PC. 
  177.  
  178.  
  179.        o  See Also
  180.  
  181.        getchar, getc, putch, getche, ungetch, kbhit, cprintf, 
  182.        cscanf, cputs, cgets 
  183.  
  184.  
  185.        o  Example
  186.  
  187.        #include <conio.h>
  188.  
  189.        char charcode;
  190.        int i, spec_key;
  191.  
  192.        /*  This example shows how to detect special keys  */
  193.  
  194.        if ((i=getch()) & 0x00FF) {
  195.           spec_key = FALSE;
  196.           charcode = i;
  197.        }else{
  198.           spec_key = TRUE;
  199.           charcode = (unsigned) i >> 8;
  200.        }
  201.  
  202.        
  203.  
  204.        getche
  205.  
  206.  
  207.  
  208.        o  Summary
  209.  
  210.        #include <conio.h>      /*  Function declarations only  */
  211.  
  212.        int getche();
  213.  
  214.  
  215.        o  Description
  216.  
  217.        The getche function behaves exactly like the getch 
  218.        function, with the exception that the character read from 
  219.        the keyboard is echoed to the screen. 
  220.  
  221.        NOTE: The putch function is used to echo the character.  If 
  222.              the character read is not an ASCII character (i.e. a 
  223.              special key with no ASCII code), then no character is 
  224.              echoed. 
  225.  
  226.  
  227.        o  Return Value
  228.  
  229.        Exactly the same as the getch function.
  230.  
  231.  
  232.        o  See Also
  233.  
  234.        getchar, getc, putch, getch, ungetch, kbhit, cprintf, 
  235.        cscanf, cputs, cgets 
  236.  
  237.  
  238.  
  239.        
  240.  
  241.        getche (continued)
  242.  
  243.  
  244.  
  245.        o  Example
  246.  
  247.        #include <conio.h>
  248.  
  249.        /*  Not a very friendly routine; just for illustration.  */
  250.  
  251.        int askYN()
  252.        {
  253.           int reply;
  254.  
  255.           do {
  256.              cprintf("\n(Y)es or (N)o ? ");
  257.              reply = getche();
  258.           }while (reply != 'Y' && reply != 'N');
  259.           if (reply == 'Y')
  260.              return TRUE;
  261.           else
  262.              return FALSE;
  263.        }
  264.  
  265.        
  266.  
  267.        ungetch
  268.  
  269.  
  270.  
  271.        o  Summary
  272.  
  273.        #include <conio.h>      /*  Function declarations only  */
  274.  
  275.        int ungetch(c);
  276.        int c;                  /*  Character to be "pushed"  */
  277.  
  278.  
  279.        o  Description
  280.  
  281.        The ungetch function "pushes" the character (c) back into 
  282.        the keyboard, so that (c) will be the next character read 
  283.        by getch, getche, or kbhit. 
  284.  
  285.        The ungetch function does NOT backspace over the last 
  286.        character that was echoed to the screen, so be careful when 
  287.        using ungetch after getche to be sure that your code 
  288.        performs as intended. 
  289.  
  290.        Redirection of stdin or stdout has NO EFFECT on ungetch. 
  291.  
  292.        The ungetch function does NOT check for Ctrl-C or Ctrl-S. 
  293.  
  294.        The ungetch function has the capability to push back at 
  295.        least one character; some implementations may allow more, 
  296.        but one is typical. 
  297.  
  298.  
  299.        o  Return Value
  300.  
  301.        The ungetch function returns the character (c) if it is 
  302.        successful, or EOF (-1) if it cannot push (c) back to the 
  303.        keyboard. 
  304.  
  305.  
  306.        o  See Also
  307.  
  308.        ungetchar, ungetc, putch, getch, getche, kbhit, cprintf, 
  309.        cscanf, cputs, cgets 
  310.  
  311.  
  312.  
  313.        
  314.  
  315.        ungetch (continued)
  316.  
  317.  
  318.  
  319.        o  Example
  320.  
  321.        #include <conio.h>
  322.  
  323.        void ignore_kbd_spaces()
  324.        {
  325.           int c;
  326.  
  327.           do {} while ( isspace(c = getch()) );
  328.  
  329.           ungetch(c);  /*  OOPS -- one too many.  Put it back.  */
  330.        }
  331.  
  332.  
  333.        
  334.        kbhit
  335.  
  336.  
  337.  
  338.        o  Summary
  339.  
  340.        #include <conio.h>      /*  Function declarations only  */
  341.  
  342.        int kbhit();
  343.  
  344.  
  345.        o  Description
  346.  
  347.        The kbhit function behaves exactly like the getch function, 
  348.        with the exception that it never waits for a key to be 
  349.        pressed.  If there are no keys in the ungetch buffer, and 
  350.        no key has been pressed, a zero is returned immediately 
  351.        without waiting on the keyboard. 
  352.  
  353.        Note that kbhit checks for and handles Ctrl-C and Ctrl-S. 
  354.  
  355.  
  356.        o  Return Value
  357.  
  358.        Exactly the same as the return value for getch, except that 
  359.        a zero is returned (immediately) if no key has been 
  360.        pressed. 
  361.  
  362.  
  363.        o  See Also
  364.  
  365.        putch, getch, getche, ungetch, cprintf, cscanf, cputs, 
  366.        cgets 
  367.  
  368.  
  369.  
  370.  
  371.        
  372.        kbhit (continued)
  373.  
  374.  
  375.  
  376.        o  Example
  377.  
  378.        #include <conio.h>
  379.  
  380.        /*  Routine to call stay_busy() until the ENTER key is 
  381.            pressed.                                             */ 
  382.  
  383.        void stay_busy_until_ENTER()
  384.        {
  385.           do {
  386.              while (!kbhit()) {
  387.                 stay_busy();
  388.              }
  389.           }while (getch() != '\n');
  390.        }
  391.  
  392.