1 09/28/88 tty_
2
3 Function: The tty_ I/O module supports I/O from/to devices that can
4 be operated in a typewriter-like manner, e.g., the user's terminal.
5
6 Entry points in the module are not called directly by users; rather,
7 the module is accessed through the I/O system.
8
9
10 Syntax for attach description
11 tty_ device -control_args
12
13
14 Arguments
15 device
16 is the channel name of the device to be attached. If a device is
17 not given, the -login_channel control argument must be given. The
18 star convention is allowed.
19
20
21 Control arguments
22 -destination DESTINATION
23 this control argument specifies that the attached device is to be
24 called using the address DESTINATION. In the case of telephone
25 auto_call lines, DESTINATION is the telephone number to be dialed.
26 Use of this control argument requires the dialok attribute.
27 -dial_id STR
28 specifies that dial connections are to be accepted on the dial_id
29 STR. Use of this control argument requires the dialok attribute.
30 The dial command is then used to connect a terminal on the dial_id
31 STR. If STR is not a registered dial_id, then the
32 Person_id.Project_id of the process being connected to must be
33 supplied to the dial command. To become a registered server, the
34 process must have rw access to >scl>rcp>dial.STR.acs.
35
36
37 -hangup_on_detach
38 causes the detach entrypoint to hang up the device automatically.
39 This is not meaningful for the login channel.
40 -login_channel
41 specifies attachment to the user's primary login channel. If a
42 device is not specified, then the user's login channel is used.
43 This control argument flags this switch for reconnection by the
44 process disconnection facility. If the user's login device should
45 hang up, this switch is automatically closed, detached, attached,
46 and opened on the user's new login channel when the user reconnects,
47 if permission to use this facility is specified in the SAT and PDT
48 for the user.
49
50
51 -no_block
52 specifies that the device is to be managed asynchronously. The tty_
53 module does not block to wait for input to be available or output
54 space to be available see "Buffering" below. This control
55 argument should not be used on the login channel, because it causes
56 the command listener to loop calling get_line.
57 -no_hangup_on_detach
58 prevents the detach entrypoint from hanging up the device. This is
59 not meaningful for the login channel.
60 -no_suppress_dial_manager
61 enables dial_manager_, and is the default.
62
63
64 -resource STR
65 specifies the desired characteristics of a channel. STR which can
66 be null consists of reservation attributes separated by commas.
67 The channel used by a dial-out operation must have the
68 characteristics specified in the reservation string. Reservation
69 attributes consist of a keyword and optional argument. Attributes
70 allowed are:
71 baud_rate=BAUD_RATE
72 line_type=LINE_TYPE
73 where BAUD_RATE is a decimal representation of the desired channel
74 line speed and LINE_TYPE is a valid line type, chosen from
75 line_types.incl.pl1 see "set_line_type" below.
76
77
78 -required_access_class STR
79 specifies the access class that must be associated witht he channel.
80 STR is an access class string. The access class specified must be
81 the same as the process's authorization unless the process has the
82 "comm" privilege turned on, in which case the access class
83 specified must be less than or equal to the process's authorization.
84 -suppress_dial_manager
85 prevents tty_ from using dial_manager_ to attach the specified
86 channel. If the channel cannot be attach via a call to hcs_, the
87 attach operation fails.
88
89
90 Notes
91 The device specified must be available to the attaching process. The
92 user's login device is always available. Any devices acquired with
93 the dial_manager_ subroutine are also available. If the device is in
94 slave service, and the user has appropriate access to its access
95 control segment rw to >sc1>rcp>NAME.acs, tty_ attempts to make it
96 available using the privileged_attach mechanism of dial_manager_. If
97 the -destination control argument is specified, the dial_out mechanism
98 is used the user must have rw access to >sc1>rcp>NAME.acs. If the
99 -dial_id control argument is specified, the allow_dials or
100 registered_server mechanism is used.
101
102
103 Opening
104 The opening modes supported are stream_input, stream_output, and
105 stream_input_output.
106
107
108 Editing
109 To control editing, use the modes operation. Details on the various
110 modes are given below.
111
112
113 Buffering
114 This I/O module blocks to await either the availability of input
115 characters or the availability of output buffer space, unless the
116 -no_block control argument is specified in the attach description. If
117 the -no_block attach description control argument is specified, the
118 behavior of the iox_$put_chars, iox_$get_chars, and iox_$get_line
119 calls changes. If the put_chars entrypoint cannot write all the
120 characters supplied, it returns a nonstandard status code consisting
121 of the negative e of the number of characters actually not written
122 returns -number not written. Any positive status code should be
123 interpreted as a standard system status code. The get_chars and
124 get_line entrypoints will return zero status codes and zero characters
125 read if there is no input available.
126
127
128 Interrupted operations
129 When an I/O operation except detach being performed on a switch
130 attached by this I/O module is interrupted by a signal, other
131 operations can be performed on the switch during the interruption. If
132 the interrupted operation is get_line, get_chars, or put_chars and
133 another get_line, get_chars, or put_chars operation is performed during
134 the interruption, the "start" control operation should be issued before
135 the interrupted operation is resumed.
136
137
138 Get chars operation
139 The get_chars operation reads as many characters as are available, up
140 to, but not exceeding, the number requested by the caller. No error
141 code is returned if the number of characters read is less than the
142 number requested. At least one character is always returned unless
143 the number requested is zero. The characters read may comprise only a
144 partial input line, or several input lines; no assumptions can be made
145 in this regard.
146
147
148 Get line operation
149 The get_line operation is supported. No error code is returned if the
150 read operation occurs with the input buffer length at zero. For
151 further explanation, see the iox_$get_line entry.
152
153
154 Put chars operation
155 The put_chars operation is supported see the iox_$put_chars entry.
156
157
158 Control operation
159 The following orders are supported when the I/O switch is open. Except
160 as noted, the info_ptr should be null. The orders are divided into
161 categories. Local orders perform a specific function one time only,
162 global orders change the way the system interfaces with the terminal,
163 and other orders fit in neither category. Control orders are performed
164 through the iox_$control entry.
165
166
167 List of local orders
168 abort
169 flushes the input and output buffers.
170 get_chars_timeout
171 performs a get_chars operation, with a timeout specified. The
172 preferred method to using this control order is to use the
173 timed_io_$get_chars subroutine. The info_ptr points to the
174 input_timeout_info structure declared in io_timeout_info.incl.pl1.
175 get_line_timeout
176 performs a get_line operation, with a timeout specified. The
177 preferred method to using this control order is to use the
178 timed_io_$get_line subroutine. The info_pointer points to the same
179 structure as that specified for get_chars_timeout.
180
181
182 hangup
183 disconnects the telephone line connection of the terminal, if
184 possible. This makes the terminal unavailable for further use.
185 interrupt
186 sends an out-of-band interrupt signal quit signal to the terminal.
187 listen
188 sends a wakeup to the process once the line associated with this
189 device identifier is dialed up.
190 printer_off
191 causes the printer mechanism of the terminal to be temporarily
192 disabled if it is physically possible for the terminal to do so; if
193 it is not, the status code error_table_$action_not_performed is
194 returned see "Notes" below.
195
196
197 position
198 the I/O switch must be open for stream input. The I/O module reads
199 and discards the number of lines specified by the call.
200 printer_on
201 causes the printer mechanism of the terminal to be re-enabled see
202 "Notes" below.
203 put_chars_timeout
204 performs a put_chars operation, with a timeout specified. The
205 preferred method to using this control order is to use the
206 timed_io_$put_chars subroutine. The info_ptr points to the
207 output_timeout_info structure declared in io_timeout_info.incl.pl1.
208 resetread
209 flushes the input buffer.
210 resetwrite
211 flushes the output buffer.
212
213
214 start_xmit_hd
215 causes the channel to remain in a transmitting state at the
216 completion of the next block of output, rather than starting to
217 accept input. The line then remains in a transmitting state until
218 the stop_xmit_hd control operation is issued. This operation is
219 valid only for terminals with line type LINE_ARDS.
220 stop_xmit_hd
221 causes the channel to resume accepting input from the terminal
222 after the completion of current output if any. This operation is
223 only valid for ARDS-like terminals and is used only to counteract a
224 preceding start_xmit_hd operation.
225
226
227 wru
228 initiates the transmission of the answerback of the device, if it is
229 so equipped. This operation is allowed only for the process that
230 originally attached the device generally the initializer process.
231 The answerback can subsequently be read by means of the get_chars
232 input/output operation.
233
234
235 List of global control orders
236 accept_printer_off
237 causes subsequent printer_off and printer_on orders to be accepted
238 if possible.
239 get_channel_info
240 returns the name of the attached channel and its hardcore device
241 index. The info_ptr must point to the tty_get_channel_info
242 structure defined in tty_get_channel_info.incl.pl1.
243 get_delay
244 is used to find out what delay values are currently in effect. The
245 info_ptr points to the structure described for set_delay below,
246 which is filled in as a result of the call except for the version
247 number which must be supplied by the caller.
248
249
250 get_editing_chars
251 is used to find out what input editing characters are in effect.
252 The info_ptr points to the structure described below for
253 set_editing_chars, which is filled in as a result of the call
254 except for the version number which must be supplied by the
255 caller.
256 get_framing_chars
257 causes the framing characters currently in use to be returned see
258 the set_framing_chars order below. If no framing characters have
259 been supplied, NUL characters are returned. The info_ptr must point
260 to a structure like the one described for the set_framing_chars
261 order; this structure is filled in as a result of the call.
262
263
264 get_ifc_info
265 causes the characters currently in use for input flow control to be
266 returned see the input_flow_control_chars order below. The
267 info_ptr must point to a structure like the one described for the
268 input_flow_control_chars order, which is filled in as a result of
269 the call. If no characters are currently set, the count fields are
270 set to 0.
271
272
273 get_input_translation, get_output_translation,
274 get_input_conversion, get_output_conversion
275 these orders are used to obtain the current contents of the
276 specified table. The info_ptr points to a structure like the one
277 described for the corresponding "set" order below, which is filled
278 in as a result of the call except for the version number which
279 must be supplied by the caller. If the specified table does not
280 exist no translation or conversion is required, the status code
281 error_table_$no_table is returned.
282
283
284 get_ofc_info
285 causes the characters and protocol currently in use for output flow
286 control to be returned see the output_flow_control_chars order
287 below. The info_ptr must point to a structure like the one
288 described for the output_flow_control_chars order, which is filled
289 in as a result of the call. If no output flow control protocol is
290 currently in use, the count fields are set to 0, and both
291 suspend_resume and block_acknowledge are set to "0"b.
292 get_special
293 is used to obtain the contents of the special_chars table currently
294 in use. The info_ptr points to the get_special_info_struc structure
295 defined in tty_convert.incl.pl1.
296
297
298 input_flow_control_chars
299 specifies the characters to be used for input flow control for
300 terminals with line speed input capability. The terminal must be in
301 iflow mode for the feature to take effect. The info_ptr must point
302 to the input_flow_control_info structure declared in
303 flow_control_info.incl.pl1.
304 output_flow_control_chars
305 enables either of two output flow control protocols and specifies
306 the characters to be used for output flow control. The terminal
307 must be in oflow mode for the feature to take effect. The info_ptr
308 must point to the output_flow_control_info structure declared in
309 flow_control_info.incl.pl1.
310 refuse_printer_off
311 causes subsequent printer_off and printer_on orders to be rejected,
312 except when in echoplex mode.
313
314
315 set_delay
316 sets the number of delay characters associated with the output of
317 carriage-motion characters. The info_ptr points to the delay_struc
318 structure defined in tty_convert.incl.pl1.
319 set_editing_chars
320 changes the characters used for editing input. The info_ptr points
321 to the editing_chars structure declared in
322 tty_editing_chars.incl.pl1.
323
324
325 The following rules apply to editing characters:
326 1. The two editing characters cannot be the same.
327 2. No carriage-movement character can be used for either of the
328 editing functions.
329 3. NUL and space cannot be used for either editing function.
330 4. If the editing character is an ASCII control character, it will
331 not have the desired effect unless ctl_char mode is on see
332 "Modes Operation" below.
333
334
335 set_framing_chars
336 specifies the pair of characters that the terminal generates
337 surrounding input transmitted as a block or "frame." These
338 characters must be specified in the character code used by the
339 terminal. This order must be used for blk_xfer mode see below to
340 be effective. The info_ptr must point to a structure with the
341 following format:
342 dcl 1 framing_chars aligned,
343 2 frame_begin char1 unaligned,
344 2 frame_end char1 unaligned;
345
346
347 set_input_conversion
348 provides a table to be used in converting input to identify escape
349 sequences and certain special characters. The info_ptr points to
350 the cv_trans_struc structure defined in tty_convert.incl.pl1.
351 The table is indexed by the ASCII value of each input character
352 after translation if any, and the corresponding entry contains
353 one of the following values mnemonic names for these values are
354 defined in tty_convert.incl.pl1:
355
356
357 0 ordinary character
358 1 break character
359 2 escape character
360 3 character to be thrown away
361 4 formfeed character to be thrown away if page length is
362 nonzero
363 5 this character and immediately following character to be
364 thrown away
365
366
367 set_input_translation
368 provides a table to be used for translation of terminal input to
369 ASCII. The info_ptr points to the cv_trans_struc structure
370 declared in tty_convert.incl.pl1.
371 set_line_type
372 sets the line type associated with the terminal to the value
373 supplied. The info_ptr should point to a fixed binary variable
374 containing the new line type. Line types can be any of the
375 named constants defined in the include file line_types.incl.pl1.
376 This operation is not permitted while the terminal is in use.
377
378
379 set_output_conversion
380 provides a table to be used in formatting output to identify certain
381 kinds of special characters. The info_ptr points to a structure
382 like that described for set_input_conversion above. The table is
383 indexed by each ASCII output character before translation if any,
384 and the corresponding entry contains one of the following values.
385 Mnemonic names for these values are defined in tty_convert.incl.pl1.
386 0 ordinary character.
387 1 newline.
388 2 carriage return.
389 3 horizontal tab.
390 4 backspace.
391 5 vertical tab.
392 6 formfeed.
393 7 character requiring octal escape.
394
395
396 8 red ribbon shift.
397 9 black ribbon shift.
398 10 character does not change the column position.
399 11 this character together with the following one do not change
400 the column position used for hardware escape sequences.
401 12 character is not to be sent to the terminal.
402 17 or greater a character requiring a special escape sequence.
403
404 The indicator value is the index into the escape table of the
405 sequence to be used, plus 16. The escape table is part of the
406 special characters table; see the set_special order below.
407
408
409 set_output_translation
410 provides a table to be used for translating ASCII characters to the
411 code to be sent to the terminal. The info_ptr points to a
412 structure like that described for set_input_translation. The table
413 is indexed by the value of each ASCII character, and the
414 corresponding entry contains the character to be output. If the
415 info_ptr is null, no translation is to be done.
416
417 NOTE: For a terminal that expects 6-bit characters and case-shift
418 characters, the 4008 bit must be turned on in each entry in the
419 table for a character that requires upper shift, and the 2008 bit
420 must be on in each entry for a character that requires lower shift.
421
422
423 set_special
424 provides a table that specifies sequences to be substituted for
425 certain output characters, and characters that are to be interpreted
426 as parts of escape sequences on input. Output sequences are of the
427 following form defined in tty_convert.incl.pl1:
428 dcl 1 c_chars based aligned,
429 2 count fixed bin8 unaligned,
430 2 chars15 char1 unaligned;
431 where:
432 count
433 is the actual length of the sequence in characters
434 0 <= count <= 15. If count is zero, there is no sequence.
435 chars
436 are the characters that make up the sequence.
437
438
439 The info_ptr points to the special_chars_struc structure defined in
440 tty_convert.incl.pl1.
441
442 set_term_type
443 sets the terminal type associated with the channel to one of the
444 types defined in the terminal type table. The info_ptr should point
445 to the set_term_typ_info structure declared in
446 set_term_type_info.incl.pl1.
447
448
449 set_wakeup_table
450 specifies a wakeup table, i.e., a set of wakeup characters that
451 controls the dispatching of input wakeups. The wakeup table
452 operates in conjunction with wake_tbl mode. The wakeup table has no
453 effect until wake_tbl mode is enabled. Once enabled, the standard
454 method of generating input wakeups normally one wakeup for each
455 line is suspended. Thereafter, wakeups are only generated when
456 wakeup characters are received or when the buffer gets too full.
457 The wakeup table cannot be changed while wake_tbl mode is enabled.
458 The info_ptr should point to the structure declared in
459 set_wakeup_table_info.incl.pl1.
460
461
462 List of miscellaneous control orders
463 copy_meters
464 causes the current cumulative meters associated with the channel to
465 be copied to unwired storage, so that the statistics for the channel
466 can be determined both for the life of the system and for the
467 current dialup. This order can only be issued by the "owning"
468 process normally the initializer. The info_ptr should be null.
469 get_event_channel
470 returns the identifier of the ipc_ event channel associated with the
471 channel. The info_pointer should point to a fixed bin 71 aligned
472 quantity into which the channel identifier is stored. If the switch
473 is not yet open and the set_event_channel order has not been given,
474 the result is zero.
475
476
477 quit_disable
478 causes quit signal processing to be disabled for this device.
479 quit_enable
480 causes quit signal processing to be enabled for this device. Quit
481 signal processing is initially disabled.
482 read_status
483 tells whether or not there is any type-ahead input waiting for a
484 process to read. The info_ptr should point to the
485 tty_read_status_info structure defined in
486 tty_read_status_info.incl.pl1.
487
488
489 send_initial_string
490 transmits an initialization string to the terminal in raw output
491 rawo mode. Due to the use of raw output mode, the string must
492 comprise character codes recognized by the terminal. If the
493 info_ptr is null, the initial string defined for the terminal type
494 is used. Otherwise, the info_ptr should point to the following
495 structure:
496 dcl 1 send_initial_string_info aligned,
497 2 version fixed bin,
498 2 initial_string char512 varying;
499 where:
500 version
501 is the version number of the above structure. It must be 1.
502 initial_string
503 is the initial string to be sent.
504
505
506 set_default_modes
507 sets the modes to the default modes for the terminal type.
508 set_event_channel
509 specifies the ipc_ event channel that receives wakeups for this
510 attachment. Wakeups are received for input available, output
511 completed, and state changes such as hangups and quits. The channel
512 can be event wait or event call. If it is event call, the -no_block
513 control argument must be present in the attach description for
514 correct operation. The info_pointer should point to a fixed bin71
515 aligned quantity containing a valid ipc_ channel identifier.
516
517 If this control order is not given before the opening of the switch,
518 tty_ attempts to allocate a fast event channel. Fast event channels
519 cannot be converted to call channels and receive no associated
520 message. If tty_ cannot allocate a fast channel, an ordinary event
521 wait channel is created and used. This control order is accepted
522 while the switch is closed or open. If the switch is open, the new
523 channel replaces the old one.
524
525
526 start
527 causes a wakeup to be signalled on the event channel associated with
528 this device. This request is used to restart processing on a device
529 whose wakeups may have been lost or discarded.
530 store_id
531 stores the answerback identifier of the terminal for later use by
532 the process. The info_ptr should point to a char4 variable that
533 contains the new identifier.
534 terminal_info
535 returns information about the terminal. The info_ptr should point
536 to the terminal_info structure declared in terminal_info.incl.pl1.
537
538
539 write_status
540 tells whether or not there is any write-behind output that has not
541 been sent to the terminal. The info_ptr should point to the
542 following structure, which is filled in by the call:
543 dcl 1 info_structure aligned,
544 2 ev_chan fixed bin71,
545 2 output_pending bit1;
546 where:
547 ev_chan
548 is the event channel used to signal the completion of output.
549 output_pending
550 indicates whether output is pending.
551 "0"b no output
552 "1"b output
553
554
555 Modes operation
556 The modes operation is supported when the I/O switch is open. The
557 recognized modes are listed in tty_modes.gi.info.
558
559
560 Syntax of control operations from command level
561 io_call control switch_name order_arg
562
563
564 Arguments
565 switch_name
566 is the name of the I/O switch.
567 order_arg
568 can be any control order described above under "Control Operation"
569 that can accept a null info_ptr, as well as read_status,
570 write_status, terminal_info, and the following which must be
571 specified as shown:
572 store_id id
573 where id is the new answerback string.
574 set_term_type type -control_args
575 where type is the new terminal type and -control_args can be any
576 of -initial_string -istr, -modes, and -ignore_line_type.
577
578
579 set_line_type line_type
580 where line_type is the new line type.
581 line_length N
582 where N is the new line length.
583
584
585 List of active functions
586 The following control orders can be used as active functions.
587 io_call control switch_name read_status
588 returns true if input is available; otherwise, false.
589 io_call control switch_name write_status
590 returns true if output is pending; otherwise, false.
591 io_call control switch_name terminal_info terminal_type
592 returns the current terminal type.
593 io_call control switch_name terminal_info baud
594 returns the baud rate.
595 io_call control switch_name terminal_info id
596 returns the terminal identifier answerback.
597 io_call control switch_name terminal_info line_type
598 returns the current line type.