console(7) console(7)NAME console - keyboard/screen driver DESCRIPTION The keyboard and video screen driver provides access to the system's console keyboard and screen. Running in its de- fault configuration, it provides emulation of an ANSI stan- dard screen and keyboard combination. Various ioctl com- mands allow the user to configure it for use along with the mouse in a more interactive environment. The screen driver is a streams based driver. Before use, a line discipline may have to be pushed onto the device's stream. Under most conditions, this is done automatically by the operating system. When an application opens /dev/console explicitly, and it is not already open, it may be necessary to push such a line discipline. There are three ways to do this. ioctl(fd,I_PUSH,line); Unconditionally pushes a line discip- line. line_push(fd); Pushes a line discipline if one is not already pushed. /etc/line_sane fd Same as previous description, but as an application in a shell script. In the previous examples, fd is a file descriptor of the open device. The last two methods are preferred, as they will only push a line discipline if required and they can be used on nonstreams drivers without adverse effects. When /dev/console is opened with a line discipline pushed on it, it will respond to all the ioctls and modes described in termio(7). Without the line discipline, it will only respond to the flags described under c_cflag in termio(7). Setting the number of bits/character to CS8 will put the screen into reverse video when it is in terminal emulation mode. ANSI Compatible Escape Sequences The terminal emulator responds to the following ANSI escape sequences. '\b' backspace-move 1 column left '\r' carriage return-move to column 1 '\n' linefeed-move to next line April, 1990 1
console(7) console(7)'\t' tab ESC '=' turn on keypad mode ESC '>' turn off keypad mode ESC 'D' line feed ESC 'M' scroll down ESC '7' save cursor position ESC '8' restore cursor position ESC '[' 's' save cursor position ESC '[' 'u' restore cursor position ESC '[' 'H' home cursor ESC '[' 'f' home cursor ESC '[' [n] 'A' up n, if n = 0 go up 1 ESC '[' [n] 'B' down n, if n = 0 go down 1 ESC '[' [n] 'D' left n, if n = 0 go left 1 ESC '[' [n] 'C' right n, if n = 0 go right 1 ESC '[' [n] 'J' 0->erase to end of page 1->erase to beginning of page 2->erase whole page ESC '[' [n] 'K' 0->erase to end of line 1->erase from beginning of line 2->erase whole line ESC '[' n 'L' scroll down n lines ESC '[' n 'M' scroll up n lines ESC '[' n '@' insert n spaces ESC '[' n 'P' delete n characters ESC '[' n 'm' 7->reverse video 0->normal video ESC '[' n 'n' 6-> return cursor position as the string ESC '[' row ';' col 'R' 2 April, 1990
console(7) console(7)ESC '[' n 'Z' tab to n*8 ESC '[' [n1] ';' [n2] 'r' move to column n2, line n1 ESC '[' [n1] ';' [n2] 'f' set scrolling region from row n1 to row n2 ESC '[' [n1] ';' [n2] 'H' set scrolling region from row n1 to row n2 ESC '[' '?' 'b' 'h' enable scrolling region ESC '[' '?' 'b' 'l' disable scrolling region ESC '[' '?' '5' 'h' set to normal video (black on white) ESC '[' '?' '5' 'l' reverse video (white on black) Note: Characters in single quotes (') are literal. ESC is the escape character. Other symbols represent strings of ASCII numbers which represent their decimal equivalent. [n] represents an optional number. If it is not present, 0 is used in its place. When sending row/column numbers to the screen, the upper left corner has address row=1, column=1. If the keyboard is not in ``keypad mode,'' it returns the characters on the keys. If it is in ``keypad mode,'' then the following escape sequences are generated: KEY LEGEND SEQUENCE 0 ESC 'O' 'p' 1 ESC 'O' 'q' 2 ESC 'O' 'r' 3 ESC 'O' 's' 4 ESC 'O' 't' 5 ESC 'O' 'u' 6 ESC 'O' 'v' 7 ESC 'O' 'w' 8 ESC 'O' 'x' 9 ESC 'O' 'y' . ESC 'O' 'n' - ESC 'O' 'm' ENTER ESC 'O' 'M' Function Keys On the Apple(Reg.) Extended keyboard, the extra keys (the function keys and the group of six keys above the arrow April, 1990 3
console(7) console(7)keys) are mapped to the following simple key sequences: KEY LEGEND SEQUENCE F1 SOH '@' CR F2 SOH 'A' CR F3 SOH 'B' CR F4 SOH 'C' CR F5 SOH 'D' CR F6 SOH 'E' CR F7 SOH 'F' CR F8 SOH 'G' CR F9 SOH 'H' CR F10 SOH 'I' CR F11 SOH 'J' CR F12 SOH 'K' CR F13 SOH 'L' CR F14 SOH 'M' CR F15 SOH 'N' CR DEL SOH 'O' CR END SOH 'P' CR PAGE DOWN SOH 'Q' CR HELP SOH 'R' CR HOME SOH 'S' CR PAGE UP SOH 'T' CR where SOH = 1 and CR = 13. Note: These sequences end in a RETURN which makes the A/UX line discipline send the current input line to the current reading process. While doing this (assum- ing normal terminal settings), the RETURN is translat- ed to a newline character. The CONTROL Key The CONTROL key sets the 6th and 5th bits of a character to 0, regardless of the key pressed. Thus, pressing CONTROL and w (octal 167) at the same time yields the same character as pressing CONTROL and W (octal 127) or CONTROL and 7 (oc- tal 067), namely, (octal 027). IOCTLS The display responds to a large number of ioctls which af- fect its behavior in many different ways. It responds to all the ioctls defined in termio(7) in the normal manner. Since it is a streams device, all other ioctls must be called using the streams indirect ioctl call function, I_STR. With this is passed a packet describing the ioctl to be executed. This packet is of type struct strioctl and is described in sys/stropts.h. It has 4 fields. ic_cmd The command (ioctl) requested to be executed. 4 April, 1990
console(7) console(7)ic_dp A pointer to any data to be read/written to by the ioctl (parameters or returned results, for exam- ple). ic_len The size of the data in bytes. ic_timout A timeout (how long to wait for the ioctl to com- plete before returning an error); -1 means no timeout (or wait forever). If s is a data structure of type struct strioctl, then an ioctl call is made using a call of the following form. ioctl(fd, I_STR, &s) Further examples of such calls are given later in this docu- ment. Screen ioctls fall into three main areas: control of the keyboard, control of the video generation hardware, and con- trol of the mouse. All the following ioctls, and the sym- bols defined with them are defined in the include file sys/video.h. Keyboard ioctls The keyboard operates in two modes, either as an ANSI stan- dard keyboard generating characters in the normal manner, or in ``raw'' mode where each keystroke is generated (both up and down) and passed directly without any modification. VIDEO_RAW This ioctl puts the keyboard into ``raw'' mode. The key codes returned are the key codes directly from the keyboard. (Refer to the keyboard documentation for a list of these.) The most significant bit indicates whether the keystroke is up or down. One ex- ception is the mouse escape character (see VIDEO_MOUSE later in this section). VIDEO_ASCII This mode is an emulation of an ANSI standard terminal keyboard (including the keypad). Video ioctls The video screen can be used in two different ways, either as a terminal emulation (in which case the interface is in the normal manner), or as a bit mapped screen, mapped into a process's address space using the phys(2) system call. There is no explicit way to shift from one mode to the oth- er; one simply stops sending characters to the terminal (in- cluding turning off ECHO) and writes to the bitmap. VIDEO_SIZE This ioctl returns the size (in characters) April, 1990 5
console(7) console(7)of the screen when used in terminal emula- tion mode. The result is two longs representing the horizontal and vertical sizes. VIDEO_SETDEF This sets the screen to its default, which is 1 bit per pixel mode, black on white. VIDEO_SETCOLOR Takes a parameter of the type video_color that describes the foreground and background colors to which the screen is set. VIDEO_ADDR This ioctl returns (as a longword) the phy- sical address of the video RAM on the video board (suitable for use in a phys(2) system call). VIDEO_REFRESH This ioctl rewrites the entire screen, in- cluding the borders; it also clears all text from the screen and moves the cursor to the upper left corner. It takes no parameters. It is intended to be used by implementers of utilities that write directly to the screen (via phys(2), for example) when they are ex- iting and wish to set the screen back to a known state. This is the only way to get the kernel to rewrite the screen's borders. VIDEO_PIXSIZE This ioctl returns a parameter of type struct video_size (also defined in <sys/video.h>) in which it places informa- tion about the size of the screen in pixels. The data structure contains three fields. pix_scr_x The width of the visible part of the screen in pixels. pix_scr_y The height of the visible part of the screen in pixels. pix_mem_x The number of pixels (both visi- ble and invisible) between the start of a line and the start of the next line. Mouse ioctls It is possible to attach the mouse to the keyboard device using the VIDEO_MOUSE system call. This can happen only if the mouse is not currently opened in any other way (see mouse(7)). When in mouse mode, changes in the mouse are converted into characters and inserted into the keyboard's input stream. This mode is most useful in conjunction with 6 April, 1990
console(7) console(7)the keyboard mode VIDEO_RAW. The mouse input is always pre- ceded by the character MOUSE_ESCAPE and can take one of two forms depending on whether the display is in VIDEO_M_BUTTON mode or not. If it is, then the next character is a 1 or 0 depending on the state of the mouse button (1 if it is down). In this mode, mouse information is only placed into the input stream when the state of the mouse button changes. In the other mode, the display places 2 bytes into the input stream whenever the mouse moves or the state of the button changes. The 2 bytes have the following format. Byte 0 Bit 7: The state of the mouse button-0 for down. Bits 0-6: Two's complement of the mouse movement in the Y axis since the last entry. Byte 1 Bit 7: Always 1. Bits 0-6: Two's complement of the mouse movement in the X axis since the last entry. The mouse ioctls are VIDEO_MOUSE Put the display into the VIDEO_MOUSE mode as described earlier. This will fail if the mouse is already in use. VIDEO_NOMOUSE Take the display out of VIDEO_MOUSE mode. This is the default when the display is opened for the first time. VIDEO_M_BUTTON Put the display into a mode (described earlier) where changes only in the mouse button find their way into the keyboard input stream. VIDEO_M_ALL This option makes all mouse changes (in- cluding changes in mouse position) to be put into the keyboard's input stream. This is the default when entering VIDEO_MOUSE mode. VIDEO_M_DELTA This call returns the change in mouse po- sition since it was last called (or since the display was put into VIDEO_MOUSE mode). It returns two shorts (horizontal displacement followed by vertical). VIDEO_M_ABS This also works only in VIDEO_MOUSE mode; it returns the absolute mouse position (relative to 0 when the system was boot- ed). It returns two shorts (horizontal April, 1990 7
console(7) console(7)displacement followed by vertical). EXAMPLES The following is an example of streams ioctls. It opens the keyboard and removes any line disciplines (after first sav- ing their states); then it puts the display into VIDEO_RAW and VIDEO_MOUSE modes and reads the input, displaying it to the standard output. When a character code 1 (from the key ``s'') is found, it stops and puts the display back into VIDEO_ASCII and VIDEO_NOMOUSE modes. It then pushes the line discipline back on and restores its state. #include <sys/stropts.h> #include <sys/termio.h> #include <sys/video.h> #include <fcntl.h> main() { struct termio t; char c; short ss; int fd, line; struct strioctl s; fd = open("/dev/console", O_RDWR); /*open the keyboard*/ ioctl(fd,TCGETA,&t); /*save the old tty*/ /*state*/ line = ioctl(fd,I_POP,0); /*remove the line*/ /*discipline and*/ /*remember if there*/ /*was one*/ s.ic_timout = -1; /*set the streams*/ /*timeout to infinity*/ s.ic_len = 0; /*put keyboard into*/ s.ic_cmd = VIDEO_RAW; /*raw mode*/ if (ioctl(fd,I_STR,&s) < 0) goto quit; s.ic_len = 0; /*attach to mouse*/ s.ic_cmd = VIDEO_MOUSE; if (ioctl(fd,I_STR,&s) < 0) goto quit; ioctl(fd,I_FLUSH,FLUSHRW); /*flush input to*/ /*put us in a known*/ /*starting state*/ for(;;) { /*loop reading input*/ if (read(fd,&c,1) < 0) /*and displaying it*/ break; if (c == MOUSE_ESCAPE) { if (read(fd,&ss,s) < 0) break; printf("m = 0x%04x\n",c&0xffff); continue; 8 April, 1990
console(7) console(7)} if (c == 1) /*quit on char.*/ /*code 1*/ break; printf("c = 0x%02x\n",c&0xff); } quit: s.ic_len = 0; /*set the keyboard*/ /*back to*/ s.ic_cmd = VIDEO_NOMOUSE; /*a sane state*/ ioctl(fd,I_STR,&s); s.ic_len = 0; s.ic_cmd = VIDEO_ASCII; ioctl(fd,I_STR,&s); if (line == 0) /*if required*/ ioctl(fd,I_PUSH,"line"); /*push a line*/ /*discipline*/ ioctl(fd,TCSETA,&t); /*restore its modes*/ } FILES /dev/console /dev/mouse /usr/include/sys/video.h /usr/include/sys/stropts.h /usr/include/termio.h SEE ALSO line_sane(1M), ioctl(2), phys(2), line_push(3), mouse(7), termio(7). April, 1990 9