1\function{SLang_init_tty} 2\synopsis{Initialize the terminal keyboard interface} 3\usage{int SLang_init_tty (int intr_ch, int no_flow_ctrl, int opost)} 4\description 5 \var{SLang_init_tty} initializes the terminal for single character 6 input. If the first parameter \var{intr_ch} is in the range 0-255, 7 it will be used as the interrupt character, e.g., under Unix this 8 character will generate a \var{SIGINT} signal. Otherwise, if it is 9 \exmp{-1}, the interrupt character will be left unchanged. 10 11 If the second parameter \var{no_flow_ctrl} is non-zero, flow control 12 (\var{XON}/\var{XOFF}) processing will be 13 enabled. 14 15 If the last parmeter \var{opost} is non-zero, output processing by the 16 terminal will be enabled. If one intends to use this function in 17 conjunction with the \slang screen management routines 18 (\var{SLsmg}), this paramete shold be set to zero. 19 20 \var{SLang_init_tty} returns zero upon success, or \-1 upon error. 21\notes 22 Terminal I/O is a complex subject. The \slang interface presents a 23 simplification that the author has found useful in practice. For 24 example, the only special character processing that 25 \var{SLang_init_tty} enables is that of the \var{SIGINT} character, 26 and the generation of other signals via the keyboard is disabled. 27 However, generation of the job control signal \var{SIGTSTP} is possible 28 via the \var{SLtty_set_suspend_state} function. 29 30 Under Unix, the integer variable \var{SLang_TT_Read_FD} is used to 31 specify the input descriptor for the terminal. If 32 \var{SLang_TT_Read_FD} represents a terminal device as determined 33 via the \var{isatty} system call, then it will be used as the 34 terminal file descriptor. Otherwise, the terminal device 35 \exmp{/dev/tty} will used as the input device. The default value of 36 \var{SLang_TT_Read_FD} is \-1 which causes \exmp{/dev/tty} to be 37 used. So, if you prefer to use \var{stdin} for input, then set 38 \var{SLang_TT_Read_FD} to \exmp{fileno(stdin)} \em{before} calling 39 \var{SLang_init_tty}. 40 41 If the variable \var{SLang_TT_Baud_Rate} is zero when this function 42 is called, the function will attempt to determine the baud rate by 43 querying the terminal driver and set \var{SLang_TT_Baud_Rate} to 44 that value. 45\seealso{SLang_reset_tty, SLang_getkey, SLtty_set_suspend_state} 46\done 47 48\function{SLang_reset_tty} 49\synopsis{Reset the terminal} 50\usage{void SLang_reset_tty (void)} 51\description 52 \var{SLang_reset_tty} resets the terminal interface back to the 53 state it was in before \var{SLang_init_tty} was called. 54\seealso{SLang_init_tty} 55\done 56 57\function{SLtty_set_suspend_state} 58\synopsis{Enable or disable keyboard suspension} 59\usage{void SLtty_set_suspend_state (int s)} 60\description 61 The \var{SLtty_set_suspend_state} function may be used to enable or 62 disable keyboard generation of the \var{SIGTSTP} job control signal. 63 If \var{s} is non-zero, generation of this signal via the terminal 64 interface will be enabled, otherwise it will be disabled. 65 66 This function should only be called after the terminal driver has be 67 initialized via \var{SLang_init_tty}. The \var{SLang_init_tty} 68 always disables the generation of \var{SIGTSTP} via the keyboard. 69\seealso{SLang_init_tty} 70\done 71 72\function{SLang_getkey} 73\synopsis{Read a character from the keyboard} 74\usage{unsigned int SLang_getkey (void);} 75\description 76 The \var{SLang_getkey} reads a single character from the terminal 77 and returns it. The terminal must first be initialized via a call 78 to \var{SLang_init_tty} before this function can be called. Upon 79 success, \var{SLang_getkey} returns the character read from the 80 terminal, otherwise it returns \var{SLANG_GETKEY_ERROR}. 81\seealso{SLang_init_tty, SLang_input_pending, SLang_ungetkey} 82\done 83 84\function{SLang_ungetkey_string} 85\synopsis{Unget a key string} 86\usage{int SLang_ungetkey_string (unsigned char *buf, unsigned int n)} 87\description 88 The \var{SLang_ungetkey_string} function may be used to push the 89 \var{n} characters pointed to by \var{buf} onto the buffered input 90 stream that \var{SLgetkey} uses. If there is not enough room for 91 the characters, \-1 is returned and none are buffered. Otherwise, 92 it returns zero. 93\notes 94 The difference between \var{SLang_buffer_keystring} and 95 \var{SLang_ungetkey_string} is that the \var{SLang_buffer_keystring} 96 appends the characters to the end of the getkey buffer, whereas 97 \var{SLang_ungetkey_string} inserts the characters at the beginning 98 of the input buffer. 99\seealso{SLang_ungetkey, SLang_getkey} 100\done 101 102\function{SLang_buffer_keystring} 103\synopsis{Append a keystring to the input buffer} 104\usage{int SLang_buffer_keystring (unsigned char *b, unsigned int len)} 105\description 106 \var{SLang_buffer_keystring} places the \var{len} characters 107 specified by \var{b} at the \em{end} of the buffer that 108 \var{SLang_getkey} uses. Upon success it returns 0; otherwise, no 109 characters are buffered and it returns \-1. 110\notes 111 The difference between \var{SLang_buffer_keystring} and 112 \var{SLang_ungetkey_string} is that the \var{SLang_buffer_keystring} 113 appends the characters to the end of the getkey buffer, whereas 114 \var{SLang_ungetkey_string} inserts the characters at the beginning 115 of the input buffer. 116\seealso{SLang_getkey, SLang_ungetkey, SLang_ungetkey_string} 117\done 118 119\function{SLang_ungetkey} 120\synopsis{Push a character back onto the input buffer} 121\usage{int SLang_ungetkey (unsigned char ch)} 122\description 123 \var{SLang_ungetkey} pushes the character \var{ch} back onto the 124 \var{SLgetkey} input stream. Upon success, it returns zero, 125 otherwise it returns \1. 126\example 127 This function is implemented as: 128#v+ 129 int SLang_ungetkey (unsigned char ch) 130 { 131 return SLang_ungetkey_string(&ch, 1); 132 } 133#v- 134\seealso{SLang_getkey, SLang_ungetkey_string} 135\done 136 137\function{SLang_flush_input} 138\synopsis{Discard all keyboard input waiting to be read} 139\usage{void SLang_flush_input (void)} 140\description 141 \var{SLang_flush_input} discards all input characters waiting to be 142 read by the \var{SLang_getkey} function. 143\seealso{SLang_getkey} 144\done 145 146\function{SLang_input_pending} 147\synopsis{Check to see if input is pending} 148\usage{int SLang_input_pending (int tsecs)} 149\description 150 \var{SLang_input_pending} may be used to see if an input character 151 is available to be read without causing \var{SLang_getkey} to block. 152 It will wait up to \var{tsecs} tenths of a second if no characters 153 are immediately available for reading. If \var{tsecs} is less than 154 zero, then \var{SLang_input_pending} will wait \exmp{-tsecs} 155 milliseconds for input, otherwise \var{tsecs} represents \var{1/10} 156 of a second intervals. 157\notes 158 Not all systems support millisecond resolution. 159\seealso{SLang_getkey} 160\done 161 162\function{SLang_set_abort_signal} 163\synopsis{Set the signal to trap SIGINT} 164\usage{void SLang_set_abort_signal (void (*f)(int));} 165\description 166 \var{SLang_set_abort_signal} sets the function that gets 167 triggered when the user presses the interrupt key (\var{SIGINT}) to 168 the function \var{f}. If \var{f} is \var{NULL} the default handler 169 will get installed. 170\example 171 The default interrupt handler on a Unix system is: 172#v+ 173 static void default_sigint (int sig) 174 { 175 SLKeyBoard_Quit = 1; 176 if (SLang_Ignore_User_Abort == 0) SLang_Error = SL_USER_BREAK; 177 SLsignal_intr (SIGINT, default_sigint); 178 } 179#v- 180\notes 181 For Unix programmers, the name of this function may appear 182 misleading since it is associated with \var{SIGINT} and not 183 \var{SIGABRT}. The origin of the name stems from the original intent 184 of the function: to allow the user to abort the running of a \slang 185 interpreter function. 186\seealso{SLang_init_tty, SLsignal_intr} 187\done 188