sc_readkb(S-osr5)

sc_readkb -- scancode translation functions

Syntax

cc . . . -lsc_s

#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

sc_readkb returns the next input scancode. The application does not need to call sc_init(S-osr5) or sc_mapinit(S-osr5) to use this routine.

sc_readmapcode returns the next input mapcode. The application does not need to call sc_init(S-osr5) or sc_mapinit(S-osr5) to use this routine.

sc_readstr returns a pointer to an ASCII string that contains either one character or, in the case of a function key input, a string of characters. The application must call either sc_init or sc_mapinit before sc_readstr.

sc_readkb, sc_readmapcode, and sc_readstr all maintain the API's internal state variables and do screen switching if the application has set a screen switch mode with sc_setscreenswitch(S-osr5). (The API provides screen-switching capability on the console only.) Therefore, the application should not call sc_receive_kb(S-osr5), sc_kb2mapcode, or sc_mapcode2str 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 sc_readkb.

Not every key generates a unique scancode. For codeset 1, each non-unique key generates a multi-byte scancode sequence, an 0xE0 byte followed by a non-unique scancode. When translating scancodes, we turn these sequences into special codes called mapcodes that were invented for SCO OpenServer. 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.

sc_kb2mapcode and sc_mapcode2str provide a lower level translation interface than sc_readkb, sc_readmapcode, and sc_readstr. Do not use the two sets of routines in combination with each other. An application should use sc_kb2mapcode and sc_mapcode2str if it is not using the API to read scancodes from the terminal.

sc_kb2mapcode 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. sc_kb2mapcode maintains the state of the keyboard and performs a screen switch if the application has set a screen switch mode with sc_setscreenswitch(S-osr5). (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), sc_kb2mapcode updates the internal representation of the keyboard and the LED state. The application does not need to call sc_init or sc_mapinit to use sc_kb2mapcode unless the application is using the API for screen switching.

sc_mapcode2str takes a mapcode as its argument and returns the ASCII string to which that mapcode maps. The input can be expanded to a character string on output if the mapcode maps to a function key. The application must call sc_init or sc_mapinit to use sc_mapcode2str.

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

sc_mapout is an international output mapping function. It takes a character as input and returns a pointer to a string of characters that constitute the mapped output.

sc_str2kb 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 \(K<LeftShift\(K> or \(K<RightShift\(K> should be used to produce a capital letter. In cases where an application expects to use international output mapping, it must call sc_mapout before calling sc_str2kb. sc_str2kb translates only <Space>, <Newline>, <Tab>, and printable ASCII characters.

sc_mapcode2kb 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 sc_str2kb or sc_mapcode2kb, it must call sc_init or sc_mapinit to initialize the translation tables that sc_str2kb and sc_mapcode2kb use.

Diagnostics

sc_readkb and sc_readmapcode return zero on a read error or if there are no characters to read. sc_readstr returns a NULL pointer if neither sc_init nor sc_mapinit is called before sc_readstr. sc_kb2mapcode returns zero for scancodes that do not directly produce mapped output. sc_mapcode2str returns NULL if the input mapcode represents a modifier key that does not directly produce mapped output. sc_mapin returns a NULL character if the input is a dead key or part of a compose sequence. sc_mapout 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

sc_init and sc_mapinit affect only one terminal at a time, and an application using the API affects only the terminal specified for sc_init or sc_mapinit.

Standards conformance

sc_readkb, sc_readmapcode, sc_readstr, sc_kb2mapcode, sc_mapcode2str, sc_mapin, sc_mapout, sc_str2kb, and sc_mapcode2kb 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);
         .
         .
   }