{The S-Lang C Library Reference}: Keyboard Input Functions

Next Previous Contents

## 10. Keyboard Input Functions

## 10.1 SLang_init_tty

Synopsis

  Initialize the terminal keyboard interface

Usage

  `int SLang_init_tty (int intr_ch, int no_flow_ctrl, int opost)`

Description

  `SLang_init_tty` initializes the terminal for single character input. If the first parameter `intr_ch` is in the range 0-255, it will be used as the interrupt character, e.g., under Unix this character will generate a `SIGINT` signal. Otherwise, if it is `-1`, the interrupt character will be left unchanged.

  If the second parameter `no_flow_ctrl` is non-zero, flow control (`XON`/`XOFF`) processing will be enabled.

  If the last parmeter `opost` is non-zero, output processing by the terminal will be enabled. If one intends to use this function in conjunction with the S-Lang screen management routines (`SLsmg`), this paramete shold be set to zero.

  `SLang_init_tty` returns zero upon success, or `-1` upon error.

Notes

  Terminal I/O is a complex subject. The S-Lang interface presents a simplification that the author has found useful in practice. For example, the only special character processing that `SLang_init_tty` enables is that of the `SIGINT` character, and the generation of other signals via the keyboard is disabled. However, generation of the job control signal `SIGTSTP` is possible via the `SLtty_set_suspend_state` function.

  Under Unix, the integer variable `SLang_TT_Read_FD` is used to specify the input descriptor for the terminal. If `SLang_TT_Read_FD` represents a terminal device as determined via the `isatty` system call, then it will be used as the terminal file descriptor. Otherwise, the terminal device `/dev/tty` will used as the input device. The default value of `SLang_TT_Read_FD` is `-1` which causes `/dev/tty` to be used. So, if you prefer to use `stdin` for input, then set `SLang_TT_Read_FD` to `fileno(stdin)` before calling `SLang_init_tty`.

  If the variable `SLang_TT_Baud_Rate` is zero when this function is called, the function will attempt to determine the baud rate by querying the terminal driver and set `SLang_TT_Baud_Rate` to that value.

See Also

  `SLang_reset_tty, SLang_getkey, SLtty_set_suspend_state`

## 10.2 SLang_reset_tty

Synopsis

  Reset the terminal

Usage

  `void SLang_reset_tty (void)`

Description

  `SLang_reset_tty` resets the terminal interface back to the state it was in before `SLang_init_tty` was called.

See Also

  `SLang_init_tty`

## 10.3 SLtty_set_suspend_state

Synopsis

  Enable or disable keyboard suspension

Usage

  `void SLtty_set_suspend_state (int s)`

Description

  The `SLtty_set_suspend_state` function may be used to enable or disable keyboard generation of the `SIGTSTP` job control signal. If `s` is non-zero, generation of this signal via the terminal interface will be enabled, otherwise it will be disabled.

  This function should only be called after the terminal driver has be initialized via `SLang_init_tty`. The `SLang_init_tty` always disables the generation of `SIGTSTP` via the keyboard.

See Also

  `SLang_init_tty`

## 10.4 SLang_getkey

Synopsis

  Read a character from the keyboard

Usage

  `unsigned int SLang_getkey (void);`

Description

  The `SLang_getkey` reads a single character from the terminal and returns it. The terminal must first be initialized via a call to `SLang_init_tty` before this function can be called. Upon success, `SLang_getkey` returns the character read from the terminal, otherwise it returns `SLANG_GETKEY_ERROR`.

See Also

  `SLang_init_tty, SLang_input_pending, SLang_ungetkey`

## 10.5 SLang_ungetkey_string

Synopsis

  Unget a key string

Usage

  `int SLang_ungetkey_string (unsigned char *buf, unsigned int n)`

Description

  The `SLang_ungetkey_string` function may be used to push the `n` characters pointed to by `buf` onto the buffered input stream that `SLgetkey` uses. If there is not enough room for the characters, `-1` is returned and none are buffered. Otherwise, it returns zero.

Notes

  The difference between `SLang_buffer_keystring` and `SLang_ungetkey_string` is that the `SLang_buffer_keystring` appends the characters to the end of the getkey buffer, whereas `SLang_ungetkey_string` inserts the characters at the beginning of the input buffer.

See Also

  `SLang_ungetkey, SLang_getkey`

## 10.6 SLang_buffer_keystring

Synopsis

  Append a keystring to the input buffer

Usage

  `int SLang_buffer_keystring (unsigned char *b, unsigned int len)`

Description

  `SLang_buffer_keystring` places the `len` characters specified by `b` at the end of the buffer that `SLang_getkey` uses. Upon success it returns 0; otherwise, no characters are buffered and it returns `-1`.

Notes

  The difference between `SLang_buffer_keystring` and `SLang_ungetkey_string` is that the `SLang_buffer_keystring` appends the characters to the end of the getkey buffer, whereas `SLang_ungetkey_string` inserts the characters at the beginning of the input buffer.

See Also

  `SLang_getkey, SLang_ungetkey, SLang_ungetkey_string`

## 10.7 SLang_ungetkey

Synopsis

  Push a character back onto the input buffer

Usage

  `int SLang_ungetkey (unsigned char ch)`

Description

  `SLang_ungetkey` pushes the character `ch` back onto the `SLgetkey` input stream. Upon success, it returns zero, otherwise it returns `1`.

Example

  This function is implemented as:

  > `

  >         int SLang_ungetkey (unsigned char ch)
  >         {
  >            return SLang_ungetkey_string(&ch, 1);
  >         }

  > `

See Also

  `SLang_getkey, SLang_ungetkey_string`

## 10.8 SLang_flush_input

Synopsis

  Discard all keyboard input waiting to be read

Usage

  `void SLang_flush_input (void)`

Description

  `SLang_flush_input` discards all input characters waiting to be read by the `SLang_getkey` function.

See Also

  `SLang_getkey`

## 10.9 SLang_input_pending

Synopsis

  Check to see if input is pending

Usage

  `int SLang_input_pending (int tsecs)`

Description

  `SLang_input_pending` may be used to see if an input character is available to be read without causing `SLang_getkey` to block. It will wait up to `tsecs` tenths of a second if no characters are immediately available for reading. If `tsecs` is less than zero, then `SLang_input_pending` will wait `-tsecs` milliseconds for input, otherwise `tsecs` represents `1/10` of a second intervals.

Notes

  Not all systems support millisecond resolution.

See Also

  `SLang_getkey`

## 10.10 SLang_set_abort_signal

Synopsis

  Set the signal to trap SIGINT

Usage

  `void SLang_set_abort_signal (void (*f)(int));`

Description

  `SLang_set_abort_signal` sets the function that gets triggered when the user presses the interrupt key (`SIGINT`) to the function `f`. If `f` is `NULL` the default handler will get installed.

Example

  The default interrupt handler on a Unix system is:

  > `

  >          static void default_sigint (int sig)
  >          {
  >             SLKeyBoard_Quit = 1;
  >             if (SLang_Ignore_User_Abort == 0) SLang_Error = SL_USER_BREAK;
  >             SLsignal_intr (SIGINT, default_sigint);
  >        }

  > `

Notes

  For Unix programmers, the name of this function may appear misleading since it is associated with `SIGINT` and not `SIGABRT`. The origin of the name stems from the original intent of the function: to allow the user to abort the running of a S-Lang interpreter function.

See Also

  `SLang_init_tty, SLsignal_intr`

Next Previous Contents