console(7) console(7)NAME console - provides access to the console keyboard and screen DESCRIPTION console is a keyboard and video screen driver that provides access to the system's console keyboard and screen. If you run console in its default configuration, it provides emulation of an ANSI standard screen and keyboard combination. Various I/O control (ioctl) commands allow you to configure the keyboard for use along with the mouse in a more interactive environment. The screen driver is a Streams-based driver. Before you use it, a line discipline may have to be pushed onto the device's stream. Under most conditions, the line discipline is pushed onto the stream automatically by the operating system. When an application opens /dev/console explicitly, and it is not already open, you may have to push such a line discipline using one of these commands: ioctl(fd, I_PUSH, line); Unconditionally pushes a line discipline. line_push(fd); Pushes a line discipline if one is not already pushed. /etc/line_sane fd Same as the previous command, but pushes the line discipline as an application in a shell script. In these examples, fd is a file descriptor of the open device. The last two methods are preferred, as they push a line discipline only 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 responds to all the ioctls and modes described in termio(7). Without the line discipline, it responds only to the options described under c_cflag in termio(7). Setting the number of bits per character to CS8 puts the screen into ``inverse'' 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' Line feed-move to next line. January 1992 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 January 1992
console(7) console(7)2->erase whole line. ESC '[' n 'L' Scroll down n lines. ESC '[' n 'M' Scroll up n lines. 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' 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' Inverse video (white on black). Note: Characters in single quotation marks (') are interpreted literally. 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 row and column numbers are sent to the screen, the upper-left corner has January 1992 3
console(7) console(7)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,'' the following escape sequences are generated: KEY 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 Extended keyboard, the extra keys (the function keys and the group of six keys above the arrow keys) are mapped to the following simple key sequences: KEY SEQUENCE F1 SOH '@' CR F2 SOH 'A' CR F3 SOH 'B' CR F4 SOH 'C' CR F5 SOH 'D' CR 4 January 1992
console(7) console(7)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: Each of these sequences ends with a return character which makes the A/UX line discipline send the current input line to the current reading process. During this operation, (assuming normal terminal settings), the (Reg.) is translated to a newline character. The CONTROL Key The CONTROL key sets the sixth and fifth 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 (octal 067), namely, (octal 027). January 1992 5
console(7) console(7)Ioctls The display responds to a large number of ioctls that affect its behavior in many different ways. It responds to all of the ioctls defined in termio(7) in the normal manner. Because 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 four fields: ic_cmd The ioctl to be executed. ic_dp A pointer to any data to be read or written by the ioctl (parameters or returned results, for example). ic_len The size of the data in bytes. ic_timout A timeout (how long to wait for the ioctl to complete before returning an error). A value of -1 means no timeout (or wait forever). For example, if s is a data structure of type struct strioctl, you make an ioctl call by using a call of the following form: ioctl(fd, I_STR, &s) Further examples of such calls are given later in this manual page. Screen ioctls fall into three main categories: those that affect control of the keyboard, control of the video generation hardware, and those that affect control of the mouse. All of the ioctls described in the sections that follow, and the symbols defined with them, are defined in the include file sys/video.h. Keyboard ioctls The keyboard operates in two modes: either as an ANSI standard keyboard generating characters in the normal manner, or in ``raw'' mode where each keystroke is generated (both key-up and key-down events) and passed directly without any modification. VIDEO_ASCII This ioctl puts the keyboard into a mode in which it emulates an ANSI standard terminal keyboard (including the keypad). 6 January 1992
console(7) console(7)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 codes.) The most significant bit indicates whether the keystroke is up or down. One exception is the mouse escape character (see the description of VIDEO_MOUSE in ``Mouse Ioctls'' later in the ``Description'' section). Video ioctls The video screen can be used in two different ways: either as a terminal emulator (in which case the interface is displayed in the normal manner), or as a bitmapped screen, mapped into a process's address space by means of the phys(2) system call. There is no explicit way to shift from one mode to the other; one mode simply stops sending characters to the terminal (including turning off ECHO) and writes to the bitmap. VIDEO_SIZE This ioctl returns the size (in characters) of the screen when used in terminal emulation mode. The result is two longs representing the horizontal and vertical sizes. VIDEO_SETDEF This ioctl sets the screen to its default mode, which is 1 bit per pixel mode, black on white. VIDEO_SETCOLOR This ioctl 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 physical 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, including 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 implementors of utilities that write directly to the screen (by means of phys(2), for example) when they are exiting and want to set the screen back to a known state. Using this ioctl is the only way to get the kernel to rewrite the screen's borders. VIDEO_PIXSIZE January 1992 7
console(7) console(7)This ioctl returns a parameter of type struct video_size (also defined in <sys/video.h>) in which it places information 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 visible and invisible) between the beginning of a line and the beginning of the next line. Mouse ioctls You can attach the mouse to the keyboard device by using the VIDEO_MOUSE system call. You can use this call only if the mouse has not already been opened in some other way (see mouse(7)). When you are in mouse mode, actions performed with the mouse are converted into characters and inserted into the keyboard's input stream. This mode is most useful in conjunction with the keyboard mode VIDEO_RAW. The mouse input is always preceded by the character MOUSE_ESCAPE and can take either of two forms, depending on whether the display is in VIDEO_M_BUTTON mode or not. If it is, 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 placed into the input stream only when the state of the mouse button changes. In the other mode, the display places two bytes into the input stream whenever the mouse moves or the state of the button changes. The two 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. Here is a description of each mouse ioctl: VIDEO_MOUSE 8 January 1992
console(7) console(7)This ioctl puts the display into the VIDEO_MOUSE mode as described earlier. This ioctl will fail if the mouse is already in use. VIDEO_NOMOUSE This ioctl takes the display out of VIDEO_MOUSE mode. This ioctl is the default when the display is opened for the first time. VIDEO_M_BUTTON This ioctl puts the display into a mode (described earlier) where only changes in the state of the mouse button are inserted into the keyboard input stream. VIDEO_M_ALL This ioctl causes all mouse changes (including changes in mouse position) to be put into the keyboard's input stream. This ioctl is the default when you are entering VIDEO_MOUSE mode. VIDEO_M_DELTA This ioctl returns the change in mouse position since it was last called (or since the display was put into VIDEO_MOUSE mode). It returns two shorts (horizontal displacement followed by vertical displacement). VIDEO_M_ABS This ioctl also works only in VIDEO_MOUSE mode; it returns the absolute mouse position (relative to 0 when the system was booted). It returns two shorts (horizontal displacement followed by vertical displacement). EXAMPLES Here is an example of a Streams ioctl. (Note that more error checking should be added to ensure that CommandShell and the Finder won't interfere, as suggested in the ``Warnings'' section later in this manual page.) The code in this example opens the keyboard and removes any line disciplines (after first saving their states), puts the display into VIDEO_RAW and VIDEO_MOUSE modes, reads the input, and displays the input to the standard output. When a character code 1 (from the S key) is found, the example ioctl stops reading and puts the display back into VIDEO_ASCII and VIDEO_NOMOUSE modes. The ioctl 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> #include <mac/devices.h> January 1992 9
console(7) console(7)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; } 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*/ 10 January 1992
console(7) console(7)/*discipline*/ ioctl(fd,TCSETA,&t); /*restore its modes*/ } WARNINGS The ioctls described in this manual page do not work when the Finder or the CommandShell is running, because of video address remapping. FILES /dev/console Device file /dev/mouse Device file /usr/include/sys/console.h Header file /usr/include/sys/stropts.h Header file /usr/include/sys/video.h Header file /usr/include/termio.h Header file SEE ALSO ioctl(2), phys(2), line_push(3), mouse(7), termio(7) line_sane(1M) in A/UX System Administrator's Reference January 1992 11