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 June 21, 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_DEFAULT_WIDTH=X" 40.Cd "options VT_FB_DEFAULT_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. 204If not set, the default in the 205.Pa GENERIC 206kernel is 207.Nm . 208.It Va kern.vt.fb.default_mode 209Set this value to a graphic mode to override the default mode picked by the 210.Nm 211backend. 212The mode is applied to all output connectors. 213This is currently only supported by the 214.Cm vt_fb 215backend when it is paired with a KMS video driver. 216.It Va kern.vt.fb.modes. Ns Pa connector_name 217Set this value to a graphic mode to override the default mode picked by the 218.Nm 219backend. 220This mode is applied to the output connector 221.Pa connector_name 222only. 223It has precedence over 224.Va kern.vt.fb.default_mode . 225The names of available connector names can be found in 226.Xr dmesg 8 227after loading the KMS driver. 228It will contain a list of connectors and their associated tunables. 229This is currently only supported by the 230.Cm vt_fb 231backend when it is paired with a KMS video driver. 232.El 233.Sh KEYBOARD SYSCTL TUNABLES 234These settings control whether certain special key combinations are enabled or 235ignored. 236The specific key combinations can be configured by using a 237.Xr keymap 5 238file. 239.Pp 240These settings can be entered at the 241.Xr loader 8 242prompt or in 243.Xr loader.conf 5 244and can also be changed at runtime with the 245.Xr sysctl 8 246command. 247.Bl -tag -width indent 248.It Va kern.vt.kbd_halt 249Enable halt keyboard combination. 250.It Va kern.vt.kbd_poweroff 251Enable power off key combination. 252.It Va kern.vt.kbd_reboot. 253Enable reboot key combination, usually Ctrl+Alt+Del. 254.It Va kern.vt.kbd_debug 255Enable debug request key combination, usually Ctrl+Alt+Esc. 256.It Va kern.vt.kbd_panic 257Enable panic key combination. 258.El 259.Sh OTHER SYSCTL TUNABLES 260These settings can be entered at the 261.Xr loader 8 262prompt, set in 263.Xr loader.conf 5 , 264or changed at runtime with 265.Xr sysctl 8 . 266.Bl -tag -width indent 267.It Va kern.vt.enable_bell 268Enable the terminal bell. 269.El 270.Sh FILES 271.Bl -tag -width /usr/share/vt/keymaps/* -compact 272.It Pa /dev/console 273.It Pa /dev/consolectl 274.It Pa /dev/ttyv* 275virtual terminals 276.It Pa /etc/ttys 277terminal initialization information 278.It Pa /usr/share/vt/fonts/*.fnt 279console fonts 280.It Pa /usr/share/vt/keymaps/*.kbd 281keyboard layouts 282.El 283.Sh EXAMPLES 284This example changes the default color of normal text to green on a 285black background, or black on a green background when reversed. 286Note that white space cannot be used inside the attribute string 287because of the current implementation of 288.Xr config 8 . 289.Pp 290.Dl "options TERMINAL_NORM_ATTR=(FG_GREEN|BG_BLACK)" 291.Pp 292This line changes the default color of kernel messages to be bright red 293on a black background, or black on a bright red background when reversed. 294.Pp 295.Dl "options TERMINAL_KERN_ATTR=(FG_LIGHTRED|BG_BLACK)" 296.Pp 297To set a 1024x768 mode on all output connectors, put the following line in 298.Pa /boot/loader.conf : 299.Pp 300.Dl kern.vt.fb.default_mode="1024x768" 301.Pp 302To set a 800x600 only on a laptop builtin screen, use the following line instead: 303.Pp 304.Dl kern.vt.fb.modes.LVDS-1="800x600" 305.Pp 306The connector name was found in 307.Xr dmesg 8 : 308.Pp 309.Dl info: [drm] Connector LVDS-1: get mode from tunables: 310.Dl info: [drm] - kern.vt.fb.modes.LVDS-1 311.Dl info: [drm] - kern.vt.fb.default_mode 312.Sh SEE ALSO 313.Xr kbdcontrol 1 , 314.Xr login 1 , 315.Xr vidcontrol 1 , 316.Xr atkbd 4 , 317.Xr atkbdc 4 , 318.Xr kbdmux 4 , 319.Xr keyboard 4 , 320.Xr screen 4 , 321.Xr splash 4 , 322.Xr syscons 4 , 323.Xr ukbd 4 , 324.Xr kbdmap 5 , 325.Xr rc.conf 5 , 326.Xr ttys 5 , 327.Xr config 8 , 328.Xr getty 8 , 329.Xr kldload 8 , 330.Xr moused 8 , 331.Xr vtfontcvt 8 332.Sh HISTORY 333The 334.Nm 335driver first appeared in 336.Fx 9.3 . 337.Sh AUTHORS 338.An -nosplit 339The 340.Nm 341device driver was developed by 342.An \&Ed Schouten Aq Mt ed@FreeBSD.org , 343.An \&Ed Maste Aq Mt emaste@FreeBSD.org , 344and 345.An Aleksandr Rybalko Aq Mt ray@FreeBSD.org , 346with sponsorship provided by the 347.Fx 348Foundation. 349This manual page was written by 350.An Warren Block Aq Mt wblock@FreeBSD.org . 351.Sh CAVEATS 352Paste buffer size is limited by the system value 353.Brq Dv MAX_INPUT , 354the number of bytes that can be stored in the terminal 355input queue, usually 1024 bytes 356(see 357.Xr termios 4 ) . 358