Telnet Flow Control: Telnet Remote Flow Control Option
How a Telnet host tells the user's Telnet client when to turn terminal flow control off and on, and when output may restart.
Hedrick, C. and D. Borman, "Telnet Remote Flow Control Option", RFC 1372, DOI 10.17487/RFC1372, October 1992, <https://www.rfc-editor.org/info/rfc1372>.
@misc{rfc1372,
series = {Request for Comments},
number = 1372,
howpublished = {RFC 1372},
publisher = {RFC Editor},
doi = {10.17487/RFC1372},
url = {https://www.rfc-editor.org/info/rfc1372},
author = {C. Hedrick and D. Borman},
title = {{Telnet Remote Flow Control Option}},
pagetotal = 6,
year = 1992,
month = oct,
} RFC text
Contents
Network Working Group C. Hedrick Request for Comments: 1372 Rutgers University Obsoletes: RFC 1080 D. Borman Cray Research, Inc. October 1992 Telnet Remote Flow Control Option Status of This Memo This RFC specifies an IAB standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "IAB Official Protocol Standards" for the standardization state and status of this protocol. Distribution of this memo is unlimited. Introduction This document specifies an extended version of the Telnet Remote Flow Control Option, RFC 1080, with the addition of the RESTART-ANY and RESTART-XON suboptions. 1. Command Names and Codes TOGGLE-FLOW-CONTROL 33 OFF 0 ON 1 RESTART-ANY 2 RESTART-XON 3 2. Command Meanings IAC WILL TOGGLE-FLOW-CONTROL Sender is willing to enable and disable flow control upon command. IAC WONT TOGGLE-FLOW-CONTROL Sender refuses to enable and disable flow control. Nothing is implied about whether sender does or does not use flow control. It is simply unwilling to enable and disable it using this protocol. IAC DO TOGGLE-FLOW-CONTROL Sender is willing to send commands to enable and disable flow control. IAC DONT TOGGLE-FLOW-CONTROL Sender refuses to send command to enable and disable flow control. IAC SB TOGGLE-FLOW-CONTROL OFF IAC SE Sender requests receiver to disable flow control. IAC SB TOGGLE-FLOW-CONTROL ON IAC SE Sender requests receiver to enable flow control. IAC SB TOGGLE-FLOW-CONTROL RESTART-ANY IAC SE Sender requests that when flow control is enabled, the receiver allow any character (except another XOFF) to restart output. IAC SB TOGGLE-FLOW-CONTROL RESTART-XON IAC SE Sender requests that when flow control is enabled, the receiver allows only the XON character to restart output. 3. Default Specification The default specification for this option is WONT TOGGLE-FLOW-CONTROL DONT TOGGLE-FLOW-CONTROL meaning flow control information will not be exchanged in either direction. 4. Motivation This memo describes a method of remotely toggling flow control between a user telnet process and the attached terminal. Only flow control of data being transmitted from the telnet process to the terminal is considered. Many systems will also allow flow control of data from the terminal to the telnet process, however there is seldom need to change this behavior repeatedly during the session. There are two common ways of doing flow control: hardware and software. Hardware flow control uses signals on wires dedicated for this purpose. Software flow control uses one or two specific characters sent along the same path as normal input data. Most commonly, XOFF (control-S) and XON (control-Q) are used to stop and start output, respectively. The option described herein is useful primarily where software flow control is being used. (Since hardware flow control does not preempt any characters, there is normally no need to disable it.) It should also be noted that flow control can either be generated automatically by the terminal when its buffers are close to overflowing, or manually by the user, when he/she cannot read the information as fast as it is being displayed, and unread information will start scrolling off the screen. The primary difficulty with software flow control is that it preempts one or two characters. Host software often requires the user to be able to input every possible ASCII character. (Certain editors are notorious for having XOFF and XON as commonly-used commands.) For this reason, operating systems often allow programs to disable flow control. While it is disabled, the characters that normally signal flow control may be read as normal input. In a telnet environment, flow control is normally done by the user telnet process, not by the host computer. In addition, many operating systems, when flow control is enabled, the user may specify whether the XOFF character is the only character that is allowed to re-enable the output of data, or whether any typed character should re-enable the flow of data. Thus this RFC defines a way to propagate flow control status from the host computer to the user telnet process. 5. Description of the Option Use of the option requires two phases. In the first phase, the telnet processes agree that one of them will TOGGLE-FLOW-CONTROL. WILL and DO are used only in this first phase. In general there will be only one exchange of WILL and DO for a session. Subnegotiations must not be issued until DO and WILL have been exchanged. It is permissible for either side to turn off the option by sending a WONT or DONT. Should this happen, no more subnegotiations may be sent, unless the option is re-enabled by another exchange of DO and WILL. Once the hosts have exchanged a WILL and a DO, the sender of the DO TOGGLE-FLOW-CONTROL is free to send subnegotiations to enable and disable flow control in the other process, and to send subnegotiations for recommendations on when to restart output. Normally, the sender of the DO will be a host, and the other end will be a user telnet process, which is connected to a terminal. Thus the protocol is normally asymmetric, however it may be used in both directions without confusion should need for this arise. As soon as the DO and WILL have been exchanged, the sender of the WILL must enable flow control. This allows flow control to begin in a known state. The decision of whether to restart output only when the XON character is received, or when any character received, starts in a system dependent state. (This is to make it consistent with older implementations of the TOGGLE-FLOW-CONTROL option that do not understand the RESTART-ANY and RESTART-XON suboptions.) The sender of the DO should send either a RESTART-ANY or RESTART-XON suboption to put the restart characteristics to a know state. Some clients might not be able to support both of the RESTART-ANY and RESTART-XON modes due to system limitations, and would then choose to ignore these commands. There is no way for the server to be notified of this condition, but a client should make every attempt to honor the state requested by the RESTART-ANY and RESTART-XON modes. Should the option be disabled by exchange of DONT and WONT, flow control may revert to an implementation-defined default state. It is not safe to assume that flow control will remain in the state requested by the most recent subnegotiation. In most implementations of software flow control, when enabled, the XOFF and XON characters are never propagated to the server; they are typically eaten by the terminal driver between the telnet client and the attached terminal. In most implementations that support the RESTART-ANY functionality, the typed character that re-enables the output is not eaten by the terminal driver, unless it is the XON character. Currently, only four command codes are defined for the subnegotiations: flow control off (code 0), flow control on (code 1), restart output on any character (code 2) and restart output only on XON (code 3). None of these codes requires any additional data, however it is possible that additional commands may be added. Thus subnegotiations having command codes other than those defined in this document should be silently ignored. This option does not deal with the issue of allowing the DO side of the connection to inform the WILL side which characters should be used for XON and XOFF. That functionality is already supplied by the LINEMODE [1] option. 6. Example Here is an example of the use of this option: Client Server IAC DO TOGGLE-FLOW-CONTROL IAC WILL TOGGLE-FLOW-CONTROL [ The server is now free to send commands to change flow control. Note that the client must now have enabled flow control, but that whether it is restart on XON only or on any character is client specific. ] IAC SB TOGGLE-FLOW-CONTROL RESTART-ANY IAC SE [ The client should now switch to allowing output to restart when the user types any character, if the client is able to support that functionality. ] IAC SB TOGGLE-FLOW-CONTROL OFF IAC SE IAC SB TOGGLE-FLOW-CONTROL ON IAC SE References [1] Internet Engineering Task Force, Telnet Working Group, D. Borman, Editor, "Telnet Linemode Option", RFC 1184, Cray Research, Inc., October 1990. Acknowledgments The original specification for this option was written by Charles Hedrick, and published as RFC 1080. The RESTART-ANY and RESTART-XON suboptions were defined and added to this version of the document by David Borman. Security Considerations Security issues are not discussed in this memo. Authors' Addresses David Borman Cray Research, Inc. 655F Lone Oak Drive Eagan, MN 55121 Phone: (612) 452-6650 Email: dab@CRAY.COM Charles Hedrick Director, LCSR Computing Facility Rutgers University 227 CORE Building P.O. Box 879 Piscataway, NJ 08855-0879 Phone: (908) 932-3088 Email: hedrick@cs.rutgers.edu Mailing List: telnet-ietf@CRAY.COM
AI ELI5
On this page
§4Why Flow Control Needs a Switch
RFC 1372 is about flow control of data going from the Telnet process to the attached terminal. There are two common kinds. Hardware flow control uses dedicated wires. Software flow control sends special characters on the same path as normal data, most commonly XOFF (control-S) to stop output and XON (control-Q) to start it again.
The option matters mainly for software flow control, because it takes over one or two characters. Host software often needs the user to be able to type every ASCII character, and some editors use XOFF and XON as ordinary commands. Operating systems therefore let programs disable flow control, so those characters arrive as normal input.
In a Telnet session the user Telnet process, not the host, does the flow control. So the host needs a way to pass its flow control status to that process. Many systems also let the user choose whether only XON, or any typed character, restarts output; this RFC carries that choice too.
Two special keys act like a pause button and a play button. Some games need those keys for something else, so the computer far away needs a way to tell your terminal to ignore the buttons for a while.
§1Command Names and Meanings
The option is called TOGGLE-FLOW-CONTROL and has option code 33. It has four subnegotiation commands: OFF (0), ON (1), RESTART-ANY (2) and RESTART-XON (3). None of them carries any extra data.
The usual Telnet negotiation verbs mean the following here:
WILL: the sender is willing to enable and disable flow control on command.WONT: the sender refuses to be toggled this way. This implies nothing about whether it uses flow control.DO: the sender is willing to send commands that enable and disable flow control.DONT: the sender refuses to send such commands.
A subnegotiation takes the form IAC SB TOGGLE-FLOW-CONTROL command IAC SE. OFF and ON ask the receiver to disable or enable flow control. RESTART-ANY asks that, while flow control is enabled, any character except another XOFF restarts output. RESTART-XON asks that only the XON character restarts it.
There are four little messages: 'flow control off', 'flow control on', 'any key restarts', and 'only the go key restarts'. Each one is a tiny note with no extra writing on it.
- 0OFF — Receiver should disable flow control.
- 1ON — Receiver should enable flow control.
- 2RESTART-ANY — Any character except another XOFF restarts output.
- 3RESTART-XON — Only the XON character restarts output.
§5Agreeing to Use the Option
Using the option takes two phases. In the first, the two Telnet processes agree with a WILL and DO exchange that one of them will toggle flow control. Normally there is only one such exchange per session. Subnegotiations must not be sent until DO and WILL have been exchanged.
Either side may turn the option off by sending WONT or DONT. After that no more subnegotiations may be sent unless another DO and WILL exchange re-enables the option. If the option is disabled this way, flow control may revert to an implementation-defined default, so a program must not assume it stays in the state of the last subnegotiation.
The default is WONT TOGGLE-FLOW-CONTROL DONT TOGGLE-FLOW-CONTROL, meaning no flow control information is exchanged in either direction.
First, both sides agree they will use the pause and play notes. Until they agree, nobody sends them. If one side changes its mind, the notes stop until they agree again.
§5Who Controls What
Once the hosts have exchanged WILL and DO, the sender of the DO is free to send the subnegotiations. Normally that is a host, and the other end is a user Telnet process connected to a terminal, so the protocol is normally asymmetric. It may be used in both directions without confusion.
As soon as the exchange completes, the sender of the WILL must enable flow control, so that flow control begins in a known state. Whether output restarts only on XON or on any character starts in a system-dependent state, to stay consistent with older implementations that do not know the restart suboptions. The sender of the DO should send either RESTART-ANY or RESTART-XON to put the restart behaviour into a known state.
Some clients cannot support both restart modes and then ignore these commands. The server is not told, but a client should try to honor the requested state. Subnegotiations with command codes other than the four defined should be silently ignored, because more commands may be added later.
Normally the XOFF and XON characters are not passed on to the server. They are eaten by the terminal driver between the client and the terminal. With RESTART-ANY, the typed character that restarts output is usually not eaten, unless it is the XON character.
The computer far away is usually the boss and your terminal follows. When they first agree, your side turns the pause button on so everyone starts from the same place.
§6An Example Session
The RFC gives one exchange. The server sends IAC DO TOGGLE-FLOW-CONTROL and the client answers IAC WILL TOGGLE-FLOW-CONTROL. The server may now send commands. The client must by now have enabled flow control, but whether restart is on XON only or on any character is client specific.
The server then sends RESTART-ANY, and the client should allow output to restart on any typed character if it can. Finally the server sends OFF followed by ON.
The option does not tell the DO side which characters the WILL side should use for XON and XOFF. The LINEMODE option, defined in RFC 1184, already supplies that.
The server asks, 'Can I control your pause button?' The client says yes. Then the server says 'any key can restart', and later turns the pause button off and on again.
- IAC DO TOGGLE-FLOW-CONTROLServer offers to send flow control commands.
- IAC WILL TOGGLE-FLOW-CONTROLClient agrees and must now have flow control enabled.
- SB ... RESTART-ANY IAC SEAny character should now restart output, if supported.
- SB ... OFF IAC SE
- SB ... ON IAC SE