sc_readkb(S)                   6 January 1993                   sc_readkb(S)


 Name

    sc_readkb - scancode translation functions

 Syntax


    cc  . . .  -lscs


    #include  <scancode.h>

    scancode_t sc_readkb (filedes)
    int filedes;

    mapcode_t sc_readmapcode (filedes)
    int filedes;

    char *sc_readstr (filedes)
    int filedes;

    mapcode_t sc_kb2mapcode (scancode)
    scancode_t scancode;

    char *sc_mapcode2str (mapcode)
    mapcode_t mapcode;

    uchar sc_mapin (c)
    uchar c;

    uchar *sc_mapout (c)
    uchar c;

    scancode_t *sc_str2kb (c)
    char c;

    scancode_t *sc_mapcode2kb (mapcode)
    mapcode_t mapcode;


 Description

    screadkb returns the next input scancode.  The application does not need
    to call scinit(S) or scmapinit(S) to use this routine.

    screadmapcode returns the next input mapcode.  The application does not
    need to call scinit(S) or scmapinit(S) to use this routine.

    screadstr returns a pointer to an ASCII string that contains either one
    character or, in the case of a function key input, a string of charac-
    ters.  The application must call either scinit or scmapinit before
    screadstr.

    screadkb, screadmapcode, and screadstr all maintain the API's internal
    state variables and do screen switching if the application has set a
    screen switch mode with scsetscreenswitch(S).  (The API provides
    screen-switching capability on the console only.)  Therefore, the appli-
    cation should not call screceivekb(S), sckb2mapcode, or scmapcode2str
    in combination with these functions.  For example, if further processing
    of a scancode is required, the application should read the scancode
    itself and not call screadkb.

    Not every key generates a unique scancode.  For codeset 1, each non-
    unique key generates a multi-byte scancode sequence, an 0xE0 byte fol-
    lowed by a non-unique scancode.  When translating scancodes, we turn
    these sequences into SCO-invented codes called mapcodes.  These mapcodes
    have values greater than the normal range of scancodes (see the values
    above 127 in /usr/lib/keyboard/keys).  This allows translation functions
    to look up key functionality on a single linear table.

    sckb2mapcode and scmapcode2str provide a lower level translation inter-
    face than screadkb, screadmapcode, and screadstr.  Do not use the two
    sets of routines in combination with each other.  An application should
    use sckb2mapcode and scmapcode2str if it is not using the API to read
    scancodes from the terminal.

    sckb2mapcode takes a scancode as input and returns a mapcode.  It parses
    multi-byte scancode sequences that map to a single mapcode, returning
    zero for scancodes that do not directly produce mapped output.
    sckb2mapcode maintains the state of the keyboard and performs a screen
    switch if the application has set a screen switch mode with
    scsetscreenswitch(S).  (The API provides screen-switching capability on
    the console only.)  On the first input following a screen switch (that
    is, when you switch to the application), sckb2mapcode updates the inter-
    nal representation of the keyboard and the LED state.  The application
    does not need to call scinit or scmapinit to use sckb2mapcode unless
    the application is using the API for screen switching.

    scmapcode2str takes a mapcode as its argument and returns the ASCII
    string to which that mapcode maps.  The input can be expanded to a char-
    acter string on output if the mapcode maps to a function key.  The appli-
    cation must call scinit or scmapinit to use scmapcode2str.

    scmapin is an international input mapping (mapchan-style) function.  It
    takes a character as input and returns a mapped character.

    scmapout is an international output mapping function.  It takes a char-
    acter as input and returns a pointer to a string of characters that con-
    stitute the mapped output.

    scstr2kb takes a keytop value as input and returns a pointer to a string
    of scancodes that produce that keytop value.  This mapping is non-
    deterministic; for example, there is no way to tell whether LeftShift or
    RightShift should be used to produce a capital letter.  In cases where an
    application expects to use international output mapping, it must call
    scmapout before calling scstr2kb.  scstr2kb translates only <Space>,
    <Newline>, <Tab>, and printable ASCII characters.

    scmapcode2kb takes a mapcode as input and returns a pointer to a string
    that contains a sequence of scancodes.  This sequence, in turn, maps to
    the input mapcode.

    Before an application calls scstr2kb or scmapcode2kb, it must call
    scinit or scmapinit to initialize the translation tables that scstr2kb
    and scmapcode2kb use.

 Diagnostics

    screadkb and screadmapcode return zero on a read error or if there are
    no characters to read.  screadstr returns a NULL pointer if neither
    scinit nor scmapinit is called before screadstr.  sckb2mapcode
    returns zero for scancodes that do not directly produce mapped output.
    scmapcode2str returns NULL if the input mapcode represents a modifier
    key that does not directly produce mapped output.  scmapin returns a
    NULL character if the input is a dead key or part of a compose sequence.
    scmapout returns a NULL pointer if the input character does not result
    in any mapped output.

    If an API function returns failure status, the global variable sc_error
    might contain a number corresponding to an error condition listed in
    scancode.h.

 Notes

    scinit and scmapinit affect only one terminal at a time, and an appli-
    cation using the API affects only the terminal specified for scinit or
    scmapinit.

 See also

    mapchan(M), scinit(S), scmapinit(S), screceivekb(S),
    scsetscreenswitch(S)

 Standards conformance

    screadkb, screadmapcode, screadstr, sckb2mapcode, scmapcode2str,
    scmapin, scmapout, scstr2kb, and scmapcode2kb are extensions of AT&T
    System V provided by the Santa Cruz Operation.

 Examples

    Here are some examples of various ways of using the API routines:

    Scenario 1:  The API switches the tty modes and does screen switching;
    the application wants to receive scancodes.

       sc_init(fd);
       sc_setscreenswitch(mode);
       while (condition) {
          scancode = sc_readkb(fd);
             .
             .
       }
       sc_exit();


    Scenario 2: The application switches tty modes and reads scancodes
    itself, but wants the API to perform screen switches.

       sc_mapinit(fd);
       sc_setscreenswitch(mode);
       while (condition) {
          /* Next line is pseudo-code */
          (obtain scancode)
          sc_receive_kb(scancode);
             .
             .
       }


    Scenario 3: The API switches tty modes and performs screen switches; the
    application obtains scancodes itself and wants them translated to ASCII.

       sc_init(fd);
       sc_setscreenswitch(mode);
       while (condition) {
          /* Next line is pseudo-code */
          (obtain scancode)
          mapcode = sc_kb2mapcode(scancode);
          str_pointer = sc_mapcode2str(mapcode);
             .
             .
       }
       sc_exit();


    Scenario 4: The application just wants scancodes translated to ASCII.

       while (condition) {
          /* Next line is pseudo-code */
          (obtain scancode)
          mapcode = sc_kb2mapcode(scancode);
          str_pointer = sc_mapcode2str(mapcode);
             .
             .
       }


    Scenario 5: The application sets tty modes and wants to read ASCII with
    no screen switches.

       sc_mapinit(fd);
       sc_setscreenswitch(MODE_OFF);
       while (condition) {
          str_pointer = sc_readstr(fd);
             .
             .
       }