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