Telnet NAWS: Telnet window size option
How a Telnet client tells the server how many columns and rows its window has.
Waitzman, D., "Telnet window size option", RFC 1073, DOI 10.17487/RFC1073, October 1988, <https://www.rfc-editor.org/info/rfc1073>.
@misc{rfc1073,
series = {Request for Comments},
number = 1073,
howpublished = {RFC 1073},
publisher = {RFC Editor},
doi = {10.17487/RFC1073},
url = {https://www.rfc-editor.org/info/rfc1073},
author = {D. Waitzman},
title = {{Telnet window size option}},
pagetotal = 4,
year = 1988,
month = oct,
} RFC text
Contents
Network Working Group D. Waitzman
Request For Comments: 1073 BBN STC
October 1988
Telnet Window Size Option
Status of this Memo
This RFC describes a proposed Telnet option to allow a client to
convey window size to a Telnet server. Distribution of this memo is
unlimited.
1. Command Name and Option Code
Name = NAWS (Negotiate About Window Size)
Code = 31
2. Command Meanings
IAC WILL NAWS
Sent by the Telnet client to suggest that NAWS be used.
IAC WON'T NAWS
Sent by the Telnet client to refuse to use NAWS.
IAC DO NAWS
Sent by the Telnet server to suggest that NAWS be used.
IAC DON'T NAWS
Sent by the Telnet server to refuse to use NAWS.
IAC SB NAWS <16-bit value> <16-bit value> IAC SE
Sent by the Telnet client to inform the Telnet server of the
window width and height.
The window size information is conveyed via this option from the
Telnet client to the Telnet server. The information is advisory.
The server may accept the option, but not use the information that is
sent.
The client and server negotiate sending the window size information
using the standard Telnet WILL/DO/DON'T/WON'T mechanism. If the
client and server agree, the client may then send a subnegotiation to
convey the window size. If the client's window size is later changed
(for instance, the window size is altered by the user), the client
may again send the subnegotiation. Because certain operating
systems, on which a server may be executing, may not allow the window
size information to be updated, the server may send a DON'T NAWS to
the client to forbid further subnegotiation after it was initially
accepted. A negotiation loop will not form following these rules.
The subnegotiation consists of two values, the width and the height
of the window in characters. The values are each sent as two bytes,
in the Internet standard byte and bit order. This allows a maximum
window width or height of 65535 characters. A value equal to zero is
acceptable for the width (or height), and means that no character
width (or height) is being sent. In this case, the width (or height)
that will be assumed by the Telnet server is operating system
specific (it will probably be based upon the terminal type
information that may have been sent using the TERMINAL TYPE Telnet
option).
The syntax for the subnegotiation is:
IAC SB NAWS WIDTH[1] WIDTH[0] HEIGHT[1] HEIGHT[0] IAC SE
As required by the Telnet protocol, any occurrence of 255 in the
subnegotiation must be doubled to distinguish it from the IAC
character (which has a value of 255).
3. Default Specification
WON'T NAWS
DON'T NAWS
This option does not assume any default window size information.
Often the terminal type, passed with the TERMINAL TYPE Telnet option,
may imply a window size, but that is not necessary for this option.
4. Motivation
With the increasing popularity of windowing systems, a Telnet client
is often run inside a variable-sized window, and the Telnet server
needs to know the window size for proper cursor control. The window
may also have its size changed during the Telnet session and the
updated window size needs to be conveyed to the server. This memo
specifies an option to send the window height and width in characters
from a client to a server.
The Telnet options Negotiate Output Line Width (NAOL) and Negotiate
Output Page Size (NAOP) do not have the correct semantics for this
purpose, and they are not in common use [see RFC-1011 "Official
Internet Protocols", and the "Defense Protocol Handbook"]. The NAOL
and NAOP options are bidirectional (i.e., the server might control
the client's line width or page size), and are limited to 253
characters in each axis.
This option is a better model of the normal window negotiation
process. The client has total control over the size of its window
and simply tells the server what the current window size is.
Furthermore, the 253 character height and width limitation is too low
so the new option has a limit of 65535 characters. Finally, this
option sends the window height and width concurrently because they
are typically changed simultaneously and many operating systems and
windowing applications prefer to think in terms of simultaneous
changes in height and width.
5. Description and Implementation Notes
A typical user of this option might be a Telnet client running under
X. After a user resizes the client's window, this must be
communicated to the Telnet client. In 4.3 BSD Unix, the signal
SIGWINCH (window changed) might be caught by the Telnet process and a
new NAWS subnegotiation sent to the server. Upon receipt of a NAWS
subnegotiation, the server might do the appropriate ioctl to handle
the new information, and then could send a SIGWINCH to its child,
probably a shell.
6. Examples
In the following examples all numbers in the data stream are in
decimal.
1. Server suggest and client agrees to use NAWS.
(server sends) IAC DO NAWS
(client sends) IAC WILL NAWS
(client sends) IAC SB NAWS 0 80 0 24 IAC SE
[A window 80 characters wide, 24 characters high]
[some time occurs and the user changes the window size]
(client sends) IAC SB NAWS 0 80 0 64 IAC SE
[A window 80 characters wide, 64 characters high]
In all numeric form:
(server sends) 255 253 31
(client sends) 255 251 31
(client sends) 255 250 31 0 80 0 24 255 240
(client sends) 255 250 31 0 80 0 64 255 240
2. Client suggests and server agrees to used NAWS.
(client sends) IAC WILL NAWS
(server sends) IAC DO NAWS
(client sends) IAC SB NAWS 1 44 0 24 IAC SE
[A window 300 characters wide, 24 characters high]
3. Client suggest and server refuses to use NAWS.
(client sends) IAC WILL NAWS
(server sends) IAC DON'T NAWS
4. Server suggests and client refuses to use NAWS.
(server sends) IAC DO NAWS
(client sends) IAC WON'T NAWS
7. Acknowledgments
A more elaborate, X window system specific, version of this option
has been implemented at Carnegie-Mellon University by Glenn Marcy and
the author. It is widely used in the Carnegie-Mellon University
Computer Science Department. Mr. Marcy helped write an early draft
of this memo documenting the more elaborate option.
AI ELI5
On this page
§1Why Report the Window Size
With windowing systems, a Telnet client is often run inside a variable-sized window. The server needs to know the window size for proper cursor control, and the size may change during the session. NAWS (Negotiate About Window Size) lets the client send the height and width in characters to the server.
The RFC says the older options for output line width (NAOL) and page size (NAOP) do not have the right semantics. They are bidirectional, so the server might control the client's size, and they are limited to 253 characters per axis. NAWS lets the client keep total control of its window and raises the limit to 65535.
Your window can change size, and the computer on the other end needs to know so it draws things in the right place. This option is how the client tells it.
§2Negotiating the Option
The option name is NAWS and its code is 31. The client sends IAC WILL NAWS or the server sends IAC DO NAWS to suggest using it, and either side can refuse with WON'T or DON'T. The default is WON'T NAWS and DON'T NAWS, so no window size is assumed.
If both sides agree, the client may send a subnegotiation, and may send it again if the user changes the window size. Some server operating systems cannot take updates, so the server may send DON'T NAWS to forbid further subnegotiation. The RFC notes that a negotiation loop will not form under these rules.
First the two computers ask each other if they want to talk about window size. If both say yes, the client can send the size, and again whenever it changes.
§3The Size Subnegotiation
The subnegotiation is IAC SB NAWS WIDTH[1] WIDTH[0] HEIGHT[1] HEIGHT[0] IAC SE. Width and height are each two bytes in the Internet standard byte and bit order, so the maximum is 65535 characters. Any 255 in the data must be doubled to tell it apart from the IAC character.
A value of zero means that no width (or height) is being sent. The server then assumes a value that is operating system specific, probably based on the terminal type if one was sent with the TERMINAL TYPE option. The information is advisory, and a server may accept the option but not use the size.
The size is sent as two numbers, width then height. A zero means the client is not saying, so the server makes its own guess.
| Field | Name | Size | Value | Description |
|---|---|---|---|---|
WIDTH-HI | WIDTH[1] | 1 byte | High byte of the window width in characters. | |
WIDTH-LO | WIDTH[0] | 1 byte | Low byte of the width. | |
HEIGHT-HI | HEIGHT[1] | 1 byte | High byte of the window height in characters. | |
HEIGHT-LO | HEIGHT[0] | 1 byte | Low byte of the height. |
§4Examples
In the RFC's first example, the server sends IAC DO NAWS and the client answers IAC WILL NAWS. The client then sends IAC SB NAWS 0 80 0 24 IAC SE, a window 80 characters wide and 24 high. Later it sends IAC SB NAWS 0 80 0 64 IAC SE after the user changes the height to 64.
The RFC also shows the client suggesting and the server agreeing (a width of 300 sent as 1 44), and refusals from either side. For implementers, it suggests a BSD client could catch the SIGWINCH signal and send a new subnegotiation, and the server could pass a SIGWINCH on to its child, probably a shell.
Say the window is 80 wide and 24 tall: the client sends 80 and 24. Make it taller and it sends 80 and 64.