1.\" Copyright (c) 2014 Warren Block 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd July 19, 2016 28.Dt "VIRTUAL TERMINALS" 4 29.Os 30.Sh NAME 31.Nm vt 32.Nd virtual terminal console driver 33.Sh SYNOPSIS 34.Cd "options TERMINAL_KERN_ATTR=_attribute_" 35.Cd "options TERMINAL_NORM_ATTR=_attribute_" 36.Cd "options VT_MAXWINDOWS=N" 37.Cd "options VT_ALT_TO_ESC_HACK=1" 38.Cd "options VT_TWOBUTTON_MOUSE" 39.Cd "options VT_FB_MAX_WIDTH=X" 40.Cd "options VT_FB_MAX_HEIGHT=Y" 41.Cd "options SC_NO_CUTPASTE" 42.Cd "device vt" 43.Pp 44In 45.Xr loader.conf 5 : 46.Cd hw.vga.textmode=1 47.Cd kern.vty=vt 48.Cd kern.vt.fb.default_mode="<X>x<Y>" 49.Cd kern.vt.fb.modes.<connector>="<X>x<Y>" 50.Pp 51In 52.Xr loader.conf 5 or 53.Xr sysctl.conf 5 : 54.Cd kern.vt.kbd_halt=1 55.Cd kern.vt.kbd_poweroff=1 56.Cd kern.vt.kbd_reboot=1 57.Cd kern.vt.kbd_debug=1 58.Cd kern.vt.kbd_panic=0 59.Cd kern.vt.enable_bell=1 60.Sh DESCRIPTION 61The 62.Nm 63device provides multiple virtual terminals with an extensive feature 64set: 65.Bl -item -offset indent 66.It 67Unicode UTF-8 text with double-width characters. 68.It 69Large font maps in graphics mode, including support for Asian 70character sets. 71.It 72Graphics-mode consoles. 73.It 74Integration with 75KMS 76.Pq Kernel Mode Setting 77video drivers for switching between the 78.Em X Window System 79and virtual terminals. 80.El 81.Ss Virtual Terminals 82Multiple virtual terminals are provided on a single computer. 83Up to sixteen virtual terminals can be defined. 84A single virtual terminal is connected to the screen and keyboard 85at a time. 86Key combinations are used to select a virtual terminal. 87Alt-F1 through Alt-F12 correspond to the first twelve virtual terminals. 88If more than twelve virtual terminals are created, Shift-Alt-F1 through 89Shift-Alt-F4 are used to switch to the additional terminals. 90.Ss Copying and Pasting Text with a Mouse 91Copying and pasting text from the screen with a mouse is supported. 92Press and hold down mouse button 1, usually the left button, while 93moving the mouse to select text. 94Selected text is highlighted with reversed foreground and background 95colors. 96To select more text after releasing mouse button 1, press mouse button 973, usually the right button. 98To paste text that has been selected, press mouse button 2, usually the 99middle button. 100The text is entered as if it were typed at the keyboard. 101The 102.Dv VT_TWOBUTTON_MOUSE 103kernel option can be used with mice that only have two buttons. 104Setting this option makes the second mouse button into the 105paste button. 106See 107.Xr moused 8 108for more information. 109.Ss Scrolling Back 110Output that has scrolled off the screen can be reviewed by pressing the 111Scroll Lock key, then scrolling up and down with the arrow keys. 112The Page Up and Page Down keys scroll up or down a full screen at a 113time. 114The Home and End keys jump to the beginning or end of the scrollback 115buffer. 116When finished reviewing, press the Scroll Lock key again to return to 117normal use. 118.Sh DRIVER CONFIGURATION 119.Ss Kernel Configuration Options 120These kernel options control the 121.Nm 122driver. 123.Bl -tag -width MAXCONS 124.It Dv TERMINAL_NORM_ATTR= Ns Pa attribute 125.It Dv TERMINAL_KERN_ATTR= Ns Pa attribute 126These options change the default colors used for normal and kernel 127text. 128Available colors are defined in 129.In sys/terminal.h . 130See 131.Sx EXAMPLES 132below. 133.It Dv VT_MAXWINDOWS=N 134Set the number of virtual terminals to be created to 135.Fa N . 136The value defaults to 12. 137.It Dv VT_ALT_TO_ESC_HACK=1 138When the Alt key is held down while pressing another key, send an ESC 139sequence instead of the Alt key. 140.It Dv VT_TWOBUTTON_MOUSE 141If defined, swap the functions of mouse buttons 2 and 3. 142In effect, this makes the right-hand mouse button perform a paste. 143These options are checked in the order shown. 144.It Dv SC_NO_CUTPASTE 145Disable mouse support. 146.It VT_FB_DEFAULT_WIDTH=X 147Set the default width to 148.Fa X . 149.It VT_FB_DEFAULT_HEIGHT=Y 150Set the default height to 151.Fa Y . 152.El 153.Sh BACKWARDS COMPATIBILITY 154Several options are provided for compatibility with the previous 155console device, 156.Xr sc 4 . 157These options will be removed in a future 158.Fx 159version. 160.Bl -column -offset indent ".Sy vt VT_TWOBUTTON_MOUSE" ".Sy SC_TWOBUTTON_MOUSE" 161.It Sy vt Option Name Ta Sy sc Option Name 162.It Dv TERMINAL_KERN_ATTR Ta Dv SC_KERNEL_CONS_ATTR 163.It Dv TERMINAL_NORM_ATTR Ta Dv SC_NORM_ATTR 164.It Dv VT_TWOBUTTON_MOUSE Ta Dv SC_TWOBUTTON_MOUSE 165.It Dv VT_MAXWINDOWS Ta Dv MAXCONS 166.It none Ta Dv SC_NO_CUTPASTE 167.El 168.Sh START-UP OPERATION WITH X86 BIOS SYSTEMS 169The computer BIOS starts in text mode, and 170the 171.Fx 172.Xr loader 8 173runs, loading the kernel. 174If 175.Va hw.vga.textmode 176is set, the system remains in text mode. 177Otherwise, 178.Nm 179switches to 640x480x16 VGA mode using 180.Cm vt_vga . 181If a KMS 182.Pq Kernel Mode Setting 183video driver is available, the display is switched to high resolution 184and the KMS driver takes over. 185When a KMS driver is not available, 186.Cm vt_vga 187remains active. 188.Sh LOADER TUNABLES 189These settings can be entered at the 190.Xr loader 8 191prompt or in 192.Xr loader.conf 5 . 193.Bl -tag -width indent 194.It Va hw.vga.textmode 195Set to 1 to use virtual terminals in text mode instead of graphics mode. 196Features that require graphics mode, like loadable fonts, will be 197disabled. 198.It Va kern.vty 199Set this value to 200.Ql vt 201or 202.Ql sc 203to choose a specific system console, overriding the default. 204The 205.Pa GENERIC 206kernel uses 207.Nm 208when this value is not set. 209.It Va kern.vt.fb.default_mode 210Set this value to a graphic mode to override the default mode picked by the 211.Nm 212backend. 213The mode is applied to all output connectors. 214This is currently only supported by the 215.Cm vt_fb 216backend when it is paired with a KMS video driver. 217.It Va kern.vt.fb.modes. Ns Pa connector_name 218Set this value to a graphic mode to override the default mode picked by the 219.Nm 220backend. 221This mode is applied to the output connector 222.Pa connector_name 223only. 224It has precedence over 225.Va kern.vt.fb.default_mode . 226The names of available connector names can be found in 227.Xr dmesg 8 228after loading the KMS driver. 229It will contain a list of connectors and their associated tunables. 230This is currently only supported by the 231.Cm vt_fb 232backend when it is paired with a KMS video driver. 233.El 234.Sh KEYBOARD SYSCTL TUNABLES 235These settings control whether certain special key combinations are enabled or 236ignored. 237The specific key combinations can be configured by using a 238.Xr keymap 5 239file. 240.Pp 241These settings can be entered at the 242.Xr loader 8 243prompt or in 244.Xr loader.conf 5 245and can also be changed at runtime with the 246.Xr sysctl 8 247command. 248.Bl -tag -width indent 249.It Va kern.vt.kbd_halt 250Enable halt keyboard combination. 251.It Va kern.vt.kbd_poweroff 252Enable power off key combination. 253.It Va kern.vt.kbd_reboot. 254Enable reboot key combination, usually Ctrl+Alt+Del. 255.It Va kern.vt.kbd_debug 256Enable debug request key combination, usually Ctrl+Alt+Esc. 257.It Va kern.vt.kbd_panic 258Enable panic key combination. 259.El 260.Sh OTHER SYSCTL TUNABLES 261These settings can be entered at the 262.Xr loader 8 263prompt, set in 264.Xr loader.conf 5 , 265or changed at runtime with 266.Xr sysctl 8 . 267.Bl -tag -width indent 268.It Va kern.vt.enable_bell 269Enable the terminal bell. 270.El 271.Sh FILES 272.Bl -tag -width /usr/share/vt/keymaps/* -compact 273.It Pa /dev/console 274.It Pa /dev/consolectl 275.It Pa /dev/ttyv* 276virtual terminals 277.It Pa /etc/ttys 278terminal initialization information 279.It Pa /usr/share/vt/fonts/*.fnt 280console fonts 281.It Pa /usr/share/vt/keymaps/*.kbd 282keyboard layouts 283.El 284.Sh EXAMPLES 285This example changes the default color of normal text to green on a 286black background, or black on a green background when reversed. 287Note that white space cannot be used inside the attribute string 288because of the current implementation of 289.Xr config 8 . 290.Pp 291.Dl "options TERMINAL_NORM_ATTR=(FG_GREEN|BG_BLACK)" 292.Pp 293This line changes the default color of kernel messages to be bright red 294on a black background, or black on a bright red background when reversed. 295.Pp 296.Dl "options TERMINAL_KERN_ATTR=(FG_LIGHTRED|BG_BLACK)" 297.Pp 298To set a 1024x768 mode on all output connectors, put the following line in 299.Pa /boot/loader.conf : 300.Pp 301.Dl kern.vt.fb.default_mode="1024x768" 302.Pp 303To set a 800x600 only on a laptop builtin screen, use the following line instead: 304.Pp 305.Dl kern.vt.fb.modes.LVDS-1="800x600" 306.Pp 307The connector name was found in 308.Xr dmesg 8 : 309.Pp 310.Dl info: [drm] Connector LVDS-1: get mode from tunables: 311.Dl info: [drm] - kern.vt.fb.modes.LVDS-1 312.Dl info: [drm] - kern.vt.fb.default_mode 313.Sh SEE ALSO 314.Xr kbdcontrol 1 , 315.Xr login 1 , 316.Xr vidcontrol 1 , 317.Xr atkbd 4 , 318.Xr atkbdc 4 , 319.Xr kbdmux 4 , 320.Xr keyboard 4 , 321.Xr screen 4 , 322.Xr splash 4 , 323.Xr syscons 4 , 324.Xr ukbd 4 , 325.Xr kbdmap 5 , 326.Xr rc.conf 5 , 327.Xr ttys 5 , 328.Xr config 8 , 329.Xr getty 8 , 330.Xr kldload 8 , 331.Xr moused 8 , 332.Xr vtfontcvt 8 333.Sh HISTORY 334The 335.Nm 336driver first appeared in 337.Fx 9.3 . 338.Sh AUTHORS 339.An -nosplit 340The 341.Nm 342device driver was developed by 343.An \&Ed Schouten Aq Mt ed@FreeBSD.org , 344.An \&Ed Maste Aq Mt emaste@FreeBSD.org , 345and 346.An Aleksandr Rybalko Aq Mt ray@FreeBSD.org , 347with sponsorship provided by the 348.Fx 349Foundation. 350This manual page was written by 351.An Warren Block Aq Mt wblock@FreeBSD.org . 352.Sh CAVEATS 353Paste buffer size is limited by the system value 354.Brq Dv MAX_INPUT , 355the number of bytes that can be stored in the terminal 356input queue, usually 1024 bytes 357(see 358.Xr termios 4 ) . 359