09/28/88 tty_ Function: The tty_ I/O module supports I/O from/to devices that can be operated in a typewriter-like manner, e.g., the user's terminal. Entry points in the module are not called directly by users; rather, the module is accessed through the I/O system. Syntax for attach description tty_ {device} {-control_args} Arguments device is the channel name of the device to be attached. If a device is not given, the -login_channel control argument must be given. The star convention is allowed. Control arguments -destination DESTINATION this control argument specifies that the attached device is to be called using the address DESTINATION. In the case of telephone auto_call lines, DESTINATION is the telephone number to be dialed. Use of this control argument requires the dialok attribute. -dial_id STR specifies that dial connections are to be accepted on the dial_id STR. Use of this control argument requires the dialok attribute. The dial command is then used to connect a terminal on the dial_id STR. If STR is not a registered dial_id, then the Person_id.Project_id of the process being connected to must be supplied to the dial command. To become a registered server, the process must have rw access to >scl>rcp>dial.STR.acs. -hangup_on_detach causes the detach entrypoint to hang up the device automatically. This is not meaningful for the login channel. -login_channel specifies attachment to the user's primary login channel. If a device is not specified, then the user's login channel is used. This control argument flags this switch for reconnection by the process disconnection facility. If the user's login device should hang up, this switch is automatically closed, detached, attached, and opened on the user's new login channel when the user reconnects, if permission to use this facility is specified in the SAT and PDT for the user. -no_block specifies that the device is to be managed asynchronously. The tty_ module does not block to wait for input to be available or output space to be available (see "Buffering" below). This control argument should not be used on the login channel, because it causes the command listener to loop calling get_line. -no_hangup_on_detach prevents the detach entrypoint from hanging up the device. This is not meaningful for the login channel. -no_suppress_dial_manager enables dial_manager_, and is the default. -resource STR specifies the desired characteristics of a channel. STR (which can be null) consists of reservation attributes separated by commas. The channel used by a dial-out operation must have the characteristics specified in the reservation string. Reservation attributes consist of a keyword and optional argument. Attributes allowed are: baud_rate=BAUD_RATE line_type=LINE_TYPE where BAUD_RATE is a decimal representation of the desired channel line speed and LINE_TYPE is a valid line type, chosen from line_types.incl.pl1 (see "set_line_type", below). -required_access_class STR specifies the access class that must be associated witht he channel. STR is an access class string. The access class specified must be the same as the process's authorization unless the process has the "comm" privilege turned on, in which case the access class specified must be less than or equal to the process's authorization. -suppress_dial_manager prevents tty_ from using dial_manager_ to attach the specified channel. If the channel cannot be attach via a call to hcs_, the attach operation fails. Notes The device specified must be available to the attaching process. The user's login device is always available. Any devices acquired with the dial_manager_ subroutine are also available. If the device is in slave service, and the user has appropriate access to its access control segment (rw to >sc1>rcp>NAME.acs), tty_ attempts to make it available using the privileged_attach mechanism of dial_manager_. If the -destination control argument is specified, the dial_out mechanism is used (the user must have rw access to >sc1>rcp>NAME.acs). If the -dial_id control argument is specified, the allow_dials or registered_server mechanism is used. Opening The opening modes supported are stream_input, stream_output, and stream_input_output. Editing To control editing, use the modes operation. Details on the various modes are given below. Buffering This I/O module blocks to await either the availability of input characters or the availability of output buffer space, unless the -no_block control argument is specified in the attach description. If the -no_block attach description control argument is specified, the behavior of the iox_$put_chars, iox_$get_chars, and iox_$get_line calls changes. If the put_chars entrypoint cannot write all the characters supplied, it returns a nonstandard status code consisting of the negative e of the number of characters actually not written (returns -(number not written)). Any positive status code should be interpreted as a standard system status code. The get_chars and get_line entrypoints will return zero status codes and zero characters read if there is no input available. Interrupted operations When an I/O operation (except detach) being performed on a switch attached by this I/O module is interrupted by a signal, other operations can be performed on the switch during the interruption. If the interrupted operation is get_line, get_chars, or put_chars and another get_line, get_chars, or put_chars operation is performed during the interruption, the "start" control operation should be issued before the interrupted operation is resumed. Get chars operation The get_chars operation reads as many characters as are available, up to, but not exceeding, the number requested by the caller. No error code is returned if the number of characters read is less than the number requested. At least one character is always returned (unless the number requested is zero). The characters read may comprise only a partial input line, or several input lines; no assumptions can be made in this regard. Get line operation The get_line operation is supported. No error code is returned if the read operation occurs with the input buffer length at zero. For further explanation, see the iox_$get_line entry. Put chars operation The put_chars operation is supported (see the iox_$put_chars entry). Control operation The following orders are supported when the I/O switch is open. Except as noted, the info_ptr should be null. The orders are divided into categories. Local orders perform a specific function one time only, global orders change the way the system interfaces with the terminal, and other orders fit in neither category. Control orders are performed through the iox_$control entry. List of local orders abort flushes the input and output buffers. get_chars_timeout performs a get_chars operation, with a timeout specified. The preferred method to using this control order is to use the timed_io_$get_chars subroutine. The info_ptr points to the input_timeout_info structure declared in io_timeout_info.incl.pl1. get_line_timeout performs a get_line operation, with a timeout specified. The preferred method to using this control order is to use the timed_io_$get_line subroutine. The info_pointer points to the same structure as that specified for get_chars_timeout. hangup disconnects the telephone line connection of the terminal, if possible. This makes the terminal unavailable for further use. interrupt sends an out-of-band interrupt signal (quit signal) to the terminal. listen sends a wakeup to the process once the line associated with this device identifier is dialed up. printer_off causes the printer mechanism of the terminal to be temporarily disabled if it is physically possible for the terminal to do so; if it is not, the status code error_table_$action_not_performed is returned (see "Notes" below). position the I/O switch must be open for stream input. The I/O module reads and discards the number of lines specified by the call. printer_on causes the printer mechanism of the terminal to be re-enabled (see "Notes" below). put_chars_timeout performs a put_chars operation, with a timeout specified. The preferred method to using this control order is to use the timed_io_$put_chars subroutine. The info_ptr points to the output_timeout_info structure declared in io_timeout_info.incl.pl1. resetread flushes the input buffer. resetwrite flushes the output buffer. start_xmit_hd causes the channel to remain in a transmitting state at the completion of the next block of output, rather than starting to accept input. The line then remains in a transmitting state until the stop_xmit_hd control operation is issued. This operation is valid only for terminals with line type LINE_ARDS. stop_xmit_hd causes the channel to resume accepting input from the terminal (after the completion of current output, if any). This operation is only valid for ARDS-like terminals and is used only to counteract a preceding start_xmit_hd operation. wru initiates the transmission of the answerback of the device, if it is so equipped. This operation is allowed only for the process that originally attached the device (generally the initializer process). The answerback can subsequently be read by means of the get_chars input/output operation. List of global control orders accept_printer_off causes subsequent printer_off and printer_on orders to be accepted if possible. get_channel_info returns the name of the attached channel and its hardcore device index. The info_ptr must point to the tty_get_channel_info structure defined in tty_get_channel_info.incl.pl1. get_delay is used to find out what delay values are currently in effect. The info_ptr points to the structure described for set_delay (below), which is filled in as a result of the call (except for the version number, which must be supplied by the caller). get_editing_chars is used to find out what input editing characters are in effect. The info_ptr points to the structure described below for set_editing_chars, which is filled in as a result of the call (except for the version number, which must be supplied by the caller). get_framing_chars causes the framing characters currently in use to be returned (see the set_framing_chars order below). If no framing characters have been supplied, NUL characters are returned. The info_ptr must point to a structure like the one described for the set_framing_chars order; this structure is filled in as a result of the call. get_ifc_info causes the characters currently in use for input flow control to be returned (see the input_flow_control_chars order below). The info_ptr must point to a structure like the one described for the input_flow_control_chars order, which is filled in as a result of the call. If no characters are currently set, the count fields are set to 0. get_input_translation, get_output_translation, get_input_conversion, get_output_conversion these orders are used to obtain the current contents of the specified table. The info_ptr points to a structure like the one described for the corresponding "set" order below, which is filled in as a result of the call (except for the version number, which must be supplied by the caller). If the specified table does not exist (no translation or conversion is required), the status code error_table_$no_table is returned. get_ofc_info causes the characters and protocol currently in use for output flow control to be returned (see the output_flow_control_chars order below). The info_ptr must point to a structure like the one described for the output_flow_control_chars order, which is filled in as a result of the call. If no output flow control protocol is currently in use, the count fields are set to 0, and both suspend_resume and block_acknowledge are set to "0"b. get_special is used to obtain the contents of the special_chars table currently in use. The info_ptr points to the get_special_info_struc structure defined in tty_convert.incl.pl1. input_flow_control_chars specifies the character(s) to be used for input flow control for terminals with line speed input capability. The terminal must be in iflow mode for the feature to take effect. The info_ptr must point to the input_flow_control_info structure declared in flow_control_info.incl.pl1. output_flow_control_chars enables either of two output flow control protocols and specifies the characters to be used for output flow control. The terminal must be in oflow mode for the feature to take effect. The info_ptr must point to the output_flow_control_info structure declared in flow_control_info.incl.pl1. refuse_printer_off causes subsequent printer_off and printer_on orders to be rejected, except when in echoplex mode. set_delay sets the number of delay characters associated with the output of carriage-motion characters. The info_ptr points to the delay_struc structure defined in tty_convert.incl.pl1. set_editing_chars changes the characters used for editing input. The info_ptr points to the editing_chars structure declared in tty_editing_chars.incl.pl1. The following rules apply to editing characters: 1. The two editing characters cannot be the same. 2. No carriage-movement character can be used for either of the editing functions. 3. NUL and space cannot be used for either editing function. 4. If the editing character is an ASCII control character, it will not have the desired effect unless ctl_char mode is on (see "Modes Operation" below). set_framing_chars specifies the pair of characters that the terminal generates surrounding input transmitted as a block or "frame." These characters must be specified in the character code used by the terminal. This order must be used for blk_xfer mode (see below) to be effective. The info_ptr must point to a structure with the following format: dcl 1 framing_chars aligned, 2 frame_begin char(1) unaligned, 2 frame_end char(1) unaligned; set_input_conversion provides a table to be used in converting input to identify escape sequences and certain special characters. The info_ptr points to the cv_trans_struc structure defined in tty_convert.incl.pl1. The table is indexed by the ASCII value of each input character (after translation, if any), and the corresponding entry contains one of the following values (mnemonic names for these values are defined in tty_convert.incl.pl1): 0 ordinary character 1 break character 2 escape character 3 character to be thrown away 4 formfeed character (to be thrown away if page length is nonzero) 5 this character and immediately following character to be thrown away set_input_translation provides a table to be used for translation of terminal input to ASCII. The info_ptr points to the cv_trans_struc structure declared in tty_convert.incl.pl1. set_line_type sets the line type associated with the terminal to the value supplied. The info_ptr should point to a fixed binary variable containing the new line type. Line types can be any of the named constants defined in the include file line_types.incl.pl1. This operation is not permitted while the terminal is in use. set_output_conversion provides a table to be used in formatting output to identify certain kinds of special characters. The info_ptr points to a structure like that described for set_input_conversion (above). The table is indexed by each ASCII output character (before translation, if any), and the corresponding entry contains one of the following values. Mnemonic names for these values are defined in tty_convert.incl.pl1. 0 ordinary character. 1 newline. 2 carriage return. 3 horizontal tab. 4 backspace. 5 vertical tab. 6 formfeed. 7 character requiring octal escape. 8 red ribbon shift. 9 black ribbon shift. 10 character does not change the column position. 11 this character together with the following one do not change the column position (used for hardware escape sequences). 12 character is not to be sent to the terminal. 17 or greater a character requiring a special escape sequence. The indicator value is the index into the escape table of the sequence to be used, plus 16. The escape table is part of the special characters table; see the set_special order below. set_output_translation provides a table to be used for translating ASCII characters to the code to be sent to the terminal. The info_ptr points to a structure like that described for set_input_translation. The table is indexed by the value of each ASCII character, and the corresponding entry contains the character to be output. If the info_ptr is null, no translation is to be done. NOTE: For a terminal that expects 6-bit characters and case-shift characters, the 400(8) bit must be turned on in each entry in the table for a character that requires upper shift, and the 200(8) bit must be on in each entry for a character that requires lower shift. set_special provides a table that specifies sequences to be substituted for certain output characters, and characters that are to be interpreted as parts of escape sequences on input. Output sequences are of the following form (defined in tty_convert.incl.pl1): dcl 1 c_chars based aligned, 2 count fixed bin(8) unaligned, 2 chars(15) char(1) unaligned; where: count is the actual length of the sequence in characters (0 <= count <= 15). If count is zero, there is no sequence. chars are the characters that make up the sequence. The info_ptr points to the special_chars_struc structure defined in tty_convert.incl.pl1. set_term_type sets the terminal type associated with the channel to one of the types defined in the terminal type table. The info_ptr should point to the set_term_typ_info structure declared in set_term_type_info.incl.pl1. set_wakeup_table specifies a wakeup table, i.e., a set of wakeup characters that controls the dispatching of input wakeups. The wakeup table operates in conjunction with wake_tbl mode. The wakeup table has no effect until wake_tbl mode is enabled. Once enabled, the standard method of generating input wakeups (normally one wakeup for each line) is suspended. Thereafter, wakeups are only generated when wakeup characters are received or when the buffer gets too full. The wakeup table cannot be changed while wake_tbl mode is enabled. The info_ptr should point to the structure declared in set_wakeup_table_info.incl.pl1. List of miscellaneous control orders copy_meters causes the current cumulative meters associated with the channel to be copied to unwired storage, so that the statistics for the channel can be determined both for the life of the system and for the current dialup. This order can only be issued by the "owning" process (normally the initializer). The info_ptr should be null. get_event_channel returns the identifier of the ipc_ event channel associated with the channel. The info_pointer should point to a fixed bin (71) aligned quantity into which the channel identifier is stored. If the switch is not yet open and the set_event_channel order has not been given, the result is zero. quit_disable causes quit signal processing to be disabled for this device. quit_enable causes quit signal processing to be enabled for this device. (Quit signal processing is initially disabled.) read_status tells whether or not there is any type-ahead input waiting for a process to read. The info_ptr should point to the tty_read_status_info structure defined in tty_read_status_info.incl.pl1. send_initial_string transmits an initialization string to the terminal in raw output (rawo) mode. Due to the use of raw output mode, the string must comprise character codes recognized by the terminal. If the info_ptr is null, the initial string defined for the terminal type is used. Otherwise, the info_ptr should point to the following structure: dcl 1 send_initial_string_info aligned, 2 version fixed bin, 2 initial_string char(512) varying; where: version is the version number of the above structure. It must be 1. initial_string is the initial string to be sent. set_default_modes sets the modes to the default modes for the terminal type. set_event_channel specifies the ipc_ event channel that receives wakeups for this attachment. Wakeups are received for input available, output completed, and state changes such as hangups and quits. The channel can be event wait or event call. If it is event call, the -no_block control argument must be present in the attach description for correct operation. The info_pointer should point to a fixed bin(71) aligned quantity containing a valid ipc_ channel identifier. If this control order is not given before the opening of the switch, tty_ attempts to allocate a fast event channel. Fast event channels cannot be converted to call channels and receive no associated message. If tty_ cannot allocate a fast channel, an ordinary event wait channel is created and used. This control order is accepted while the switch is closed or open. If the switch is open, the new channel replaces the old one. start causes a wakeup to be signalled on the event channel associated with this device. This request is used to restart processing on a device whose wakeups may have been lost or discarded. store_id stores the answerback identifier of the terminal for later use by the process. The info_ptr should point to a char(4) variable that contains the new identifier. terminal_info returns information about the terminal. The info_ptr should point to the terminal_info structure declared in terminal_info.incl.pl1. write_status tells whether or not there is any write-behind output that has not been sent to the terminal. The info_ptr should point to the following structure, which is filled in by the call: dcl 1 info_structure aligned, 2 ev_chan fixed bin(71), 2 output_pending bit(1); where: ev_chan is the event channel used to signal the completion of output. output_pending indicates whether output is pending. "0"b no output "1"b output Modes operation The modes operation is supported when the I/O switch is open. The recognized modes are listed in tty_modes.gi.info. Syntax of control operations from command level io_call control switch_name order_arg Arguments switch_name is the name of the I/O switch. order_arg can be any control order described above under "Control Operation" that can accept a null info_ptr, as well as read_status, write_status, terminal_info, and the following (which must be specified as shown): store_id id where id is the new answerback string. set_term_type type {-control_args} where type is the new terminal type and -control_args can be any of -initial_string (-istr), -modes, and -ignore_line_type. set_line_type line_type where line_type is the new line type. line_length N where N is the new line length. List of active functions The following control orders can be used as active functions. [io_call control switch_name read_status] returns true if input is available; otherwise, false. [io_call control switch_name write_status] returns true if output is pending; otherwise, false. [io_call control switch_name terminal_info terminal_type] returns the current terminal type. [io_call control switch_name terminal_info baud] returns the baud rate. [io_call control switch_name terminal_info id] returns the terminal identifier (answerback). [io_call control switch_name terminal_info line_type] returns the current line type. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved