CONSOLE(4S)

NAME
console - console driver and terminal emulator for the Sun workstation

CONFIG
None; included in standard system.

SYNOPSIS
#include <fcntl.h>
#include <sys/termios.h>
open("/dev/console", mode);

DESCRIPTION

console is an indirect driver for the Sun console terminal. On a Sun workstation, this driver refers to the workstation console driver, which implements a standard UNIX system terminal. On a Sun server without a keyboard or a frame buffer, this driver refers to the CPU serial port driver (zs(4S)); a terminal is normally connected to this port.

The workstation console does not support any of the termio(4) device control functions specified by flags in the c_cflag word of the termios structure or by the IGNBRK, IGNPAR, PARMRK, or INPCK flags in the c_iflag word of the termios structure, as these functions apply only to asynchronous serial ports. All other termio(4) functions must be performed by STREAMS modules pushed atop the driver; when a slave device is opened, the ldterm(4M) and ttcompat(4M) STREAMS modules are automatically pushed on top of the stream, providing the standard termio(4) interface.

The workstation console driver calls the PROM resident monitor to output data to the console frame buffer. Keystrokes from the CPU serial port to which the keyboard is connected are routed through the keyboard STREAMS module (kb(4M)) and treated as input.

When the Sun window system win(4S) is active, console input is directed through the window system rather than being treated as input by the workstation console driver.

IOCTLS

An ioctl TIOCCONS can be applied to pseudo-terminals (pty(4)) to route output that would normally appear on the console to the pseudo-terminal instead. Thus, the window system does a TIOCCONS on a pseudo-terminal so that the system will route console output to the window to which that pseudo-terminal is connected, rather than routing output through the PROM monitor to the screen, since routing output through the PROM monitor destroys the integrity of the screen. Note: when you use TIOCCONS in this way, the console input is routed from the pseudo-terminal as well.

If a TIOCCONS is performed on /dev/console, or the pseudo-terminal to which console output is being routed is closed, output to the console will again be routed to the workstation console driver.

ANSI STANDARD TERMINAL EMULATION

The Sun Workstation's PROM monitor provides routines that emulates a standard ANSI X3.64 terminal.

Note: the VT100 also follows the ANSI X3.64 standard but both the Sun and the VT100 have nonstandard extensions to the ANSI X3.64 standard. The Sun terminal emulator and the VT100 are not compatible in any true sense.

The Sun console displays 34 lines of 80 ASCII characters per line, with scrolling, (x, y) cursor addressability, and a number of other control functions.

The Sun console displays a non-blinking block cursor which marks the current line and character position on the screen. ASCII characters between 0x20 (space) and 0x7E (tilde) inclusive are printing characters — when one is written to the Sun console (and is not part of an escape sequence), it is displayed at the current cursor position and the cursor moves one position to the right on the current line. If the cursor is already at the right edge of the screen, it moves to the first character position on the next line. If the cursor is already at the right edge of the screen on the bottom line, the Line-feed function is performed (see CTRL-J below), which scrolls the screen up by one or more lines or wraps around, before moving the cursor to the first character position on the next line.

Control Sequence Syntax

The Sun console defines a number of control sequences which may occur in its input. When such a sequence is written to the Sun console, it is not displayed on the screen, but effects some control function as described below, for example, moves the cursor or sets a display mode.

Some of the control sequences consist of a single character. The notation
    CTRL-X
for some character X , represents a control character.

Other ANSI control sequences are of the form
    ESC [ paramschar"

Spaces are included only for readability; these characters must occur in the given sequence without the intervening spaces.

ESC represents the ASCII escape character (ESC, CTRL-[, 0x1B).
[   The next character is a left square bracket `[' (0x5B).
params
    are a sequence of zero or more decimal numbers made up of digits between 0 and 9, separated by semicolons.
char
    represents a function character, which is different for each control sequence.

Some examples of syntactically valid escape sequences are (again, ESC represent the single ASCII character `Escape'):
    ESC[m	select graphic rendition with default parameter
    ESC[7m	select graphic rendition with reverse image
    ESC[33;54H	set cursor position
    ESC[123;456;0;;3;B	move cursor down

Syntactically valid ANSI escape sequences which are not currently interpreted by the Sun console are ignored. Control characters which are not currently interpreted by the Sun console are also ignored.

Each control function requires a specified number of parameters, as noted below. If fewer parameters are supplied, the remaining parameters default to 1, except as noted in the descriptions below.

If more than the required number of parameters is supplied, only the last n are used, where n is the number required by that particular command character. Also, parameters which are omitted or set to zero are reset to the default value of 1 (except as noted below).

Consider, for example, the command character M which requires one parameter. ESC[;M and ESC[0M and ESC[M and ESC[23;15;32;1M are all equivalent to ESC[1M and provide a parameter value of 1. Note: ESC[;5M (interpreted as `ESC[5M') is not equivalent to ESC[5;M (interpreted as `ESC[5;1M') which is ultimately interpreted as `ESC[1M').

In the syntax descriptions below, parameters are represented as `#' or `#1;#2'.

ANSI Control Functions

The following paragraphs specify the ANSI control functions implemented by the Sun console. Each description gives:

    •   the control sequence syntax

    •   the hex equivalent of control characters where applicable

    •   the control function name and ANSI or Sun abbreviation (if any).

    •   description of parameters required, if any

    •   description of the control function

    •   for functions which set a mode, the initial setting of the mode. The initial settings can be restored with the SUNRESET escape sequence.

Control Character Functions

CTRL-G (0x7)	Bell (BEL)
    The Sun Workstation Model 100 and 100U is not equipped with an audible bell. It `rings the bell' by flashing the entire screen. The window system flashes the window.

CTRL-H (0x8)	Backspace (BS)
    The cursor moves one position to the left on the current line. If it is already at the left edge of the screen, nothing happens.

CTRL-I (0x9)	Tab (TAB)
    The cursor moves right on the current line to the next tab stop. The tab stops are fixed at every multiple of 8 columns. If the cursor is already at the right edge of the screen, nothing happens; otherwise the cursor moves right a minimum of one and a maximum of eight character positions.

CTRL-J (0xA)	Line-feed (LF)
    The cursor moves down one line, remaining at the same character position on the line. If the cursor is already at the bottom line, the screen either scrolls up or ``wraps around'' depending on the setting of an internal variable S (initially 1) which can be changed by the ESC[r control sequence. If S is greater than zero, the entire screen (including the cursor) is scrolled up by S lines before executing the line-feed. The top S lines scroll off the screen and are lost. S new blank lines scroll onto the bottom of the screen. After scrolling, the line-feed is executed by moving the cursor down one line.

    If S is zero, `wrap-around' mode is entered. `ESC [ 1 r' exits back to scroll mode. If a line-feed occurs on the bottom line in wrap mode, the cursor goes to the same character position in the top line of the screen. When any line-feed occurs, the line that the cursor moves to is cleared. This means that no scrolling occurs. Wrap-around mode is not implemented in the window system.

    The screen scrolls as fast as possible depending on how much data is backed up waiting to be printed. Whenever a scroll must take place and the console is in normal scroll mode (`ESC [ 1 r'), it scans the rest of the data awaiting printing to see how many line-feeds occur in it. This scan stops when any control character from the set {VT, FF, SO, SI, DLE, DC1, DC2, DC3, DC4, NAK, SYN, ETB, CAN, EM, SUB, ESC, FS, GS, RS, US} is found. At that point, the screen is scrolled by N lines (N ≥ 1) and processing continues. The scanned text is still processed normally to fill in the newly created lines. This results in much faster scrolling with scrolling as long as no escape codes or other control characters are intermixed with the text.

    See also the discussion of the `Set scrolling' (ESC[r) control function below.

CTRL-K (0xB)	Reverse Line-feed
    The cursor moves up one line, remaining at the same character position on the line. If the cursor is already at the top line, nothing happens.

CTRL-L (0xC)	Form-feed (FF)
    The cursor is positioned to the Home position (upper-left corner) and the entire screen is cleared.

CTRL-M (0xD)	Return (CR)
    The cursor moves to the leftmost character position on the current line.

Escape Sequence Functions

CTRL-[ (0x1B)	Escape (ESC)
    This is the escape character. Escape initiates a multi-character control sequence.

ESC[#@	Insert Character (ICH)
    Takes one parameter, # (default 1). Inserts # spaces at the current cursor position. The tail of the current line starting at the current cursor position inclusive is shifted to the right by # character positions to make room for the spaces. The rightmost # character positions shift off the line and are lost. The position of the cursor is unchanged.

ESC[#A	Cursor Up (CUU)
    Takes one parameter, # (default 1). Moves the cursor up # lines. If the cursor is fewer than # lines from the top of the screen, moves the cursor to the topmost line on the screen. The character position of the cursor on the line is unchanged.

ESC[#B	Cursor Down (CUD)
    Takes one parameter, # (default 1). Moves the cursor down # lines. If the cursor is fewer than # lines from the bottom of the screen, move the cursor to the last line on the screen. The character position of the cursor on the line is unchanged.

ESC[#C	Cursor Forward (CUF)
    Takes one parameter, # (default 1). Moves the cursor to the right by # character positions on the current line. If the cursor is fewer than # positions from the right edge of the screen, moves the cursor to the rightmost position on the current line.

ESC[#D	Cursor Backward (CUB)
    Takes one parameter, # (default 1). Moves the cursor to the left by # character positions on the current line. If the cursor is fewer than # positions from the left edge of the screen, moves the cursor to the leftmost position on the current line.

ESC[#E	Cursor Next Line (CNL)
    Takes one parameter, # (default 1). Positions the cursor at the leftmost character position on the #-th line below the current line. If the current line is less than # lines from the bottom of the screen, positions the cursor at the leftmost character position on the bottom line.

ESC[#1;#2f	Horizontal And Vertical Position (HVP)
    or
ESC[#1;#2H	Cursor Position (CUP)
    Takes two parameters, #1 and #2 (default 1, 1). Moves the cursor to the #2-th character position on the #1-th line. Character positions are numbered from 1 at the left edge of the screen; line positions are numbered from 1 at the top of the screen. Hence, if both parameters are omitted, the default action moves the cursor to the home position (upper left corner). If only one parameter is supplied, the cursor moves to column 1 of the specified line.

ESC[J	Erase in Display (ED)
    Takes no parameters. Erases from the current cursor position inclusive to the end of the screen. In other words, erases from the current cursor position inclusive to the end of the current line and all lines below the current line. The cursor position is unchanged.

ESC[K	Erase in Line (EL)
    Takes no parameters. Erases from the current cursor position inclusive to the end of the current line. The cursor position is unchanged.

ESC[#L	Insert Line (IL)
    Takes one parameter, # (default 1). Makes room for # new lines starting at the current line by scrolling down by # lines the portion of the screen from the current line inclusive to the bottom. The # new lines at the cursor are filled with spaces; the bottom # lines shift off the bottom of the screen and are lost. The position of the cursor on the screen is unchanged.

ESC[#M	Delete Line (DL)
    Takes one parameter, # (default 1). Deletes # lines beginning with the current line. The portion of the screen from the current line inclusive to the bottom is scrolled upward by # lines. The # new lines scrolling onto the bottom of the screen are filled with spaces; the # old lines beginning at the cursor line are deleted. The position of the cursor on the screen is unchanged.

ESC[#P	Delete Character (DCH)
    Takes one parameter, # (default 1). Deletes # characters starting with the current cursor position. Shifts to the left by # character positions the tail of the current line from the current cursor position inclusive to the end of the line. Blanks are shifted into the rightmost # character positions. The position of the cursor on the screen is unchanged.

ESC[#m	Select Graphic Rendition (SGR)
    Takes one parameter, # (default 0). Note: unlike most escape sequences, the parameter defaults to zero if omitted. Invokes the graphic rendition specified by the parameter. All following printing characters in the data stream are rendered according to the parameter until the next occurrence of this escape sequence in the data stream. Currently only two graphic renditions are defined:

    0   Normal rendition.

    7   Negative (reverse) image.

    Negative image displays characters as white-on-black if the screen mode is currently black-on white, and vice-versa. Any non-zero value of # is currently equivalent to 7 and selects the negative image rendition.

ESC[p	Black On White (SUNBOW)
    Takes no parameters. Sets the screen mode to black-on-white. If the screen mode is already black-on-white, has no effect. In this mode spaces display as solid white, other characters as black-on-white. The cursor is a solid black block. Characters displayed in negative image rendition (see `Select Graphic Rendition' above) is white-on-black in this mode. This is the initial setting of the screen mode on reset.

ESC[q	White On Black (SUNWOB)
    Takes no parameters. Sets the screen mode to white-on-black. If the screen mode is already white-on-black, has no effect. In this mode spaces display as solid black, other characters as white-on-black. The cursor is a solid white block. Characters displayed in negative image rendition (see `Select Graphic Rendition' above) is black-on-white in this mode. The initial setting of the screen mode on reset is the alternative mode, black on white.

ESC[#r	Set scrolling (SUNSCRL)
    Takes one parameter, # (default 0). Sets to # an internal register which determines how many lines the screen scrolls up when a line-feed function is performed with the cursor on the bottom line. A parameter of 2 or 3 introduces a small amount of ``jump'' when a scroll occurs. A parameter of 34 clears the screen rather than scrolling. The initial setting is 1 on reset.

    A parameter of zero initiates ``wrap mode'' instead of scrolling. In wrap mode, if a linefeed occurs on the bottom line, the cursor goes to the same character position in the top line of the screen. When any linefeed occurs, the line that the cursor moves to is cleared. This means that no scrolling ever occurs. `ESC [ 1 r' exits back to scroll mode.

    For more information, see the description of the Line-feed (CTRL-J) control function above.

ESC[s	Reset terminal emulator (SUNRESET)
    Takes no parameters. Resets all modes to default, restores current font from PROM. Screen and cursor position are unchanged.

4014 TERMINAL EMULATION

The PROM monitor for Sun models 100U and 150U provides the Sun Workstation with the capability to emulate a subset of the Tektronix 4014 terminal. This feature does not exist in other Sun PROMs and will be removed from models 100U and 150U in future Sun releases. tektool(1) provides Tektronix 4014 terminal emulation and should be used instead of relying on the capabilities of the PROM monitor.

FILES
/dev/console

SEE ALSO
tektool(1) kb(4M), ldterm(4M), pty(4), termio(4), ttcompat(4M), win(4S), zs(4S)

ANSI Standard X3.64, ``Additional Controls for Use with ASCII'', Secretariat: CBEMA, 1828 L St., N.W., Washington, D.C. 20036.

BUGS
TIOCCONS should be restricted to the owner of /dev/console.