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