1.\" 2.\" vidcontrol - a utility for manipulating the syscons or vt video driver 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.\" @(#)vidcontrol.1 14.\" $FreeBSD$ 15.\" 16.Dd December 23, 2006 17.Dt VIDCONTROL 1 18.Os 19.Sh NAME 20.Nm vidcontrol 21.Nd system console control and configuration utility 22.Sh SYNOPSIS 23.Nm 24.Op Fl CdLHPpx 25.Op Fl b Ar color 26.Op Fl c Ar appearance 27.Oo 28.Fl f 29.Oo 30.Op Ar size 31.Ar file 32.Oc 33.Oc 34.Op Fl g Ar geometry 35.Op Fl h Ar size 36.Op Fl i Cm adapter | mode 37.Op Fl l Ar screen_map 38.Op Fl M Ar char 39.Op Fl m Cm on | off 40.Op Fl r Ar foreground Ar background 41.Op Fl S Cm on | off 42.Op Fl s Ar number 43.Op Fl T Cm xterm | cons25 44.Op Fl t Ar N | Cm off 45.Op Ar mode 46.Op Ar foreground Op Ar background 47.Op Cm show 48.Sh DESCRIPTION 49The 50.Nm 51utility is used to set various options for the 52.Xr syscons 4 53or 54.Xr vt 4 55console driver, 56such as video mode, colors, cursor shape, screen output map, font and screen 57saver timeout. 58Only a small subset of options is supported by 59.Xr vt 4 . 60Unsupported options lead to error messages, typically including 61the text "Inappropriate ioctl for device". 62.Pp 63The following command line options are supported: 64.Bl -tag -width indent 65.It Ar mode 66Select a new video mode. 67The modes currently recognized are: 68.Ar 80x25 , 69.Ar 80x30 , 70.Ar 80x43 , 71.Ar 80x50 , 72.Ar 80x60 , 73.Ar 132x25 , 74.Ar 132x30 , 75.Ar 132x43 , 76.Ar 132x50 , 77.Ar 132x60 , 78.Ar VGA_40x25 , 79.Ar VGA_80x25 , 80.Ar VGA_80x30 , 81.Ar VGA_80x50 , 82.Ar VGA_80x60 , 83.Ar VGA_90x25 , 84.Ar VGA_90x30 , 85.Ar VGA_90x43 , 86.Ar VGA_90x50 , 87.Ar VGA_90x60 , 88.Ar EGA_80x25 , 89.Ar EGA_80x43 , 90.Ar VESA_132x25 , 91.Ar VESA_132x43 , 92.Ar VESA_132x50 , 93.Ar VESA_132x60 . 94.\"The graphic mode 95.\".Ar VGA_320x200 96.\"and 97The raster text mode 98.Ar VESA_800x600 99can also be chosen. 100Alternatively, a mode can be specified with its number by using a mode name of 101the form 102.Li MODE_ Ns Aq Ar NUMBER . 103A list of valid mode numbers can be obtained with the 104.Fl i Cm mode 105option. 106See 107.Sx Video Mode Support 108below. 109.It Ar foreground Op Ar background 110Change colors when displaying text. 111Specify the foreground color 112(e.g.\& 113.Dq vidcontrol white ) , 114or both a foreground and background colors 115(e.g.\& 116.Dq vidcontrol yellow blue ) . 117Use the 118.Cm show 119command below to see available colors. 120.It Cm show 121See the supported colors on a given platform. 122.It Fl b Ar color 123Set border color to 124.Ar color . 125This option may not be always supported by the video driver. 126.It Fl C 127Clear the history buffer. 128.It Fl c Cm normal | blink | destructive 129Change the cursor appearance. 130The cursor is either an inverting block 131.Pq Cm normal 132that can optionally 133.Cm blink , 134or it can be like the old hardware cursor 135.Pq Cm destructive . 136The latter is actually a simulation. 137.It Fl d 138Print out current output screen map. 139.It Xo 140.Fl f 141.Oo 142.Op Ar size 143.Ar file 144.Oc 145.Xc 146Load font 147.Ar file 148for 149.Ar size 150(currently, only 151.Cm 8x8 , 152.Cm 8x14 153or 154.Cm 8x16 ) . 155The font file can be either uuencoded or in raw binary format. 156You can also use the menu-driven 157.Xr vidfont 1 158command to load the font of your choice. 159.Pp 160.Ar Size 161may be omitted, in this case 162.Nm 163will try to guess it from the size of font file. 164.Pp 165When using 166.Xr vt 4 167both 168.Ar size 169and 170.Ar font 171can be omitted, and the default font will be loaded. 172.Pp 173Note that older video cards, such as MDA and CGA, do not support 174software font. 175See also 176.Sx Video Mode Support 177and 178.Sx EXAMPLES 179below and the man page for either 180.Xr syscons 4 181or 182.Xr vt 4 183(depending on which driver you use). 184.It Fl g Ar geometry 185Set the 186.Ar geometry 187of the text mode for the modes with selectable 188geometry. 189Currently only raster modes, such as 190.Ar VESA_800x600 , 191support this option. 192See also 193.Sx Video Mode Support 194and 195.Sx EXAMPLES 196below. 197.It Fl h Ar size 198Set the size of the history (scrollback) buffer to 199.Ar size 200lines. 201.It Fl i Cm adapter 202Shows info about the current video adapter. 203.It Fl i Cm mode 204Shows the possible video modes with the current video hardware. 205.It Fl l Ar screen_map 206Install screen output map file from 207.Ar screen_map . 208See also 209.Xr syscons 4 210or 211.Xr vt 4 212(depending on which driver you use). 213.It Fl L 214Install default screen output map. 215.It Fl M Ar char 216Sets the base character used to render the mouse pointer to 217.Ar char . 218.It Fl m Cm on | off 219Switch the mouse pointer 220.Cm on 221or 222.Cm off . 223Used together with the 224.Xr moused 8 225daemon for text mode cut & paste functionality. 226.It Fl p 227Capture the current contents of the video buffer corresponding 228to the terminal device referred to by standard input. 229The 230.Nm 231utility writes contents of the video buffer to the standard 232output in a raw binary format. 233For details about that 234format see 235.Sx Format of Video Buffer Dump 236below. 237.It Fl P 238Same as 239.Fl p , 240but dump contents of the video buffer in a plain text format 241ignoring nonprintable characters and information about text 242attributes. 243.It Fl H 244When used with 245.Fl p 246or 247.Fl P , 248it instructs 249.Nm 250to dump full history buffer instead of visible portion of 251the video buffer only. 252.It Fl r Ar foreground background 253Change reverse mode colors to 254.Ar foreground 255and 256.Ar background . 257.It Fl S Cm on | off 258Turn vty switching on or off. 259When vty switching is off, 260attempts to switch to a different virtual terminal will fail. 261(The default is to permit vty switching.) 262This protection can be easily bypassed when the kernel is compiled with 263the 264.Dv DDB 265option. 266However, you probably should not compile the kernel debugger on a box which 267is supposed to be physically secure. 268.It Fl s Ar number 269Set the current vty to 270.Ar number . 271.It Fl T Cm xterm | cons25 272Switch between xterm and cons25 style terminal emulation. 273.It Fl t Ar N | Cm off 274Set the screensaver timeout to 275.Ar N 276seconds, or turns it 277.Cm off . 278.It Fl x 279Use hexadecimal digits for output. 280.El 281.Ss Video Mode Support 282Note that not all modes listed above may be supported by the video 283hardware. 284You can verify which mode is supported by the video hardware, using the 285.Fl i Cm mode 286option. 287.Pp 288The VESA BIOS support must be linked to the kernel 289or loaded as a KLD module if you wish to use VESA video modes 290or 132 column modes 291(see 292.Xr vga 4 ) . 293.Pp 294You need to compile your kernel with the 295.Ar VGA_WIDTH90 296option if you wish to use VGA 90 column modes 297(see 298.Xr vga 4 ) . 299.Pp 300Video modes other than 25 and 30 line modes may require specific size of font. 301Use 302.Fl f 303option above to load a font file to the kernel. 304If the required size of font has not been loaded to the kernel, 305.Nm 306will fail if the user attempts to set a new video mode. 307.Pp 308.Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact 309.Sy Modes Ta Sy Font size 310.No 25 line modes Ta 8x16 (VGA), 8x14 (EGA) 311.No 30 line modes Ta 8x16 312.No 43 line modes Ta 8x8 313.No 50 line modes Ta 8x8 314.No 60 line modes Ta 8x8 315.El 316.Pp 317It is better to always load all three sizes (8x8, 8x14 and 8x16) 318of the same font. 319.Pp 320You may set variables in 321.Pa /etc/rc.conf 322or 323.Pa /etc/rc.conf.local 324so that desired font files will be automatically loaded 325when the system starts up. 326See below. 327.Pp 328If you want to use any of the raster text modes you need to recompile your 329kernel with the 330.Dv SC_PIXEL_MODE 331option. 332See 333.Xr syscons 4 334or 335.Xr vt 4 336(depending on which driver you use) 337for more details on this kernel option. 338.Ss Format of Video Buffer Dump 339The 340.Nm 341utility uses the 342.Xr syscons 4 343.\" is it supported on vt(4)??? 344or 345.Xr vt 4 346.Dv CONS_SCRSHOT 347.Xr ioctl 2 348to capture the current contents of the video buffer. 349The 350.Nm 351utility writes version and additional information to the standard 352output, followed by the contents of the video buffer. 353.Pp 354VGA video memory is typically arranged in two byte tuples, 355one per character position. 356In each tuple, the first byte will be the character code, 357and the second byte is the character's color attribute. 358.Pp 359The VGA color attribute byte looks like this: 360.Bl -column "X:X" "<00000000>" "width" "bright foreground color" 361.Sy "bits# width meaning" 362.Li "7 <X0000000> 1 character blinking" 363.Li "6:4 <0XXX0000> 3 background color" 364.Li "3 <0000X000> 1 bright foreground color" 365.Li "2:0 <00000XXX> 3 foreground color" 366.El 367.Pp 368Here is a list of the three bit wide base colors: 369.Pp 370.Bl -hang -offset indent -compact 371.It 0 372Black 373.It 1 374Blue 375.It 2 376Green 377.It 3 378Cyan 379.It 4 380Red 381.It 5 382Magenta 383.It 6 384Brown 385.It 7 386Light Grey 387.El 388.Pp 389Base colors with bit 3 (the bright foreground flag) set: 390.Pp 391.Bl -hang -offset indent -compact 392.It 0 393Dark Grey 394.It 1 395Light Blue 396.It 2 397Light Green 398.It 3 399Light Cyan 400.It 4 401Light Red 402.It 5 403Light Magenta 404.It 6 405Yellow 406.It 7 407White 408.El 409.Pp 410For example, the two bytes 411.Pp 412.Dl "65 158" 413.Pp 414specify an uppercase A (character code 65), blinking 415(bit 7 set) in yellow (bits 3:0) on a blue background 416(bits 6:4). 417.Pp 418The 419.Nm 420output contains a small header which includes additional 421information which may be useful to utilities processing 422the output. 423.Pp 424The first 10 bytes are always arranged as follows: 425.Bl -column "Byte range" "Contents" -offset indent 426.It Sy "Byte Range Contents" 427.It "1 thru 8 Literal text" Dq Li SCRSHOT_ 428.It "9 File format version number" 429.It "10 Remaining number of bytes in the header" 430.El 431.Pp 432Subsequent bytes depend on the version number. 433.Bl -column "Version" "13 and up" -offset indent 434.It Sy "Version Byte Meaning" 435.It "1 11 Terminal width, in characters" 436.It " 12 Terminal depth, in characters" 437.It " 13 and up The snapshot data" 438.El 439.Pp 440So a dump of an 80x25 screen would start (in hex) 441.Bd -literal -offset indent 44253 43 52 53 48 4f 54 5f 01 02 50 19 443----------------------- -- -- -- -- 444 | | | | ` 25 decimal 445 | | | `--- 80 decimal 446 | | `------ 2 remaining bytes of header data 447 | `--------- File format version 1 448 `------------------------ Literal "SCRSHOT_" 449.Ed 450.Sh VIDEO OUTPUT CONFIGURATION 451.Ss Boot Time Configuration 452You may set the following variables in 453.Pa /etc/rc.conf 454or 455.Pa /etc/rc.conf.local 456in order to configure the video output at boot time. 457.Pp 458.Bl -tag -width foo_bar_var -compact 459.It Ar blanktime 460Sets the timeout value for the 461.Fl t 462option. 463.It Ar font8x16 , font8x14 , font8x8 464Specifies font files for the 465.Fl f 466option. 467.It Ar scrnmap 468Specifies a screen output map file for the 469.Fl l 470option. 471.El 472.Pp 473See 474.Xr rc.conf 5 475for more details. 476.Ss Driver Configuration 477The video card driver may let you change default configuration 478options, such as the default font, so that you do not need to set up 479the options at boot time. 480See video card driver manuals, (e.g.\& 481.Xr vga 4 ) 482for details. 483.Sh FILES 484.Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact 485.It Pa /usr/share/syscons/fonts/* 486.It Pa /usr/share/vt/fonts/* 487font files. 488.It Pa /usr/share/syscons/scrnmaps/* 489screen output map files (relevant for 490.Xr syscons 4 491only). 492.El 493.Sh EXAMPLES 494If you want to load 495.Pa /usr/share/syscons/fonts/iso-8x16.fnt 496to the kernel, run 497.Nm 498as: 499.Pp 500.Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt 501.Pp 502So long as the font file is in 503.Pa /usr/share/syscons/fonts 504(if using syscons) or 505.Pa /usr/share/vt/fonts 506(if using vt), 507you may abbreviate the file name as 508.Pa iso-8x16 : 509.Pp 510.Dl vidcontrol -f 8x16 iso-8x16 511.Pp 512Furthermore, you can also omit font size 513.Dq Li 8x16 : 514.Pp 515.Dl vidcontrol -f iso-8x16 516.Pp 517Moreover, the suffix specifying the font size can be also omitted; in 518this case, 519.Nm 520will use the size of the currently displayed font to construct the 521suffix: 522.Pp 523.Dl vidcontrol -f iso 524.Pp 525Likewise, you can also abbreviate the screen output map file name for 526the 527.Fl l 528option if the file is found in 529.Pa /usr/share/syscons/scrnmaps . 530.Pp 531.Dl vidcontrol -l iso-8859-1_to_cp437 532.Pp 533The above command will load 534.Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm . 535.Pp 536The following command will set-up a 100x37 raster text mode (useful for 537some LCD models): 538.Pp 539.Dl vidcontrol -g 100x37 VESA_800x600 540.Pp 541The following command will capture the contents of the first virtual 542terminal video buffer, and redirect the output to the 543.Pa shot.scr 544file: 545.Pp 546.Dl vidcontrol -p < /dev/ttyv0 > shot.scr 547.Pp 548The following command will dump contents of the fourth virtual terminal 549video buffer 550to the standard output in the human readable format: 551.Pp 552.Dl vidcontrol -P < /dev/ttyv3 553.Sh SEE ALSO 554.Xr kbdcontrol 1 , 555.Xr vidfont 1 , 556.Xr keyboard 4 , 557.Xr screen 4 , 558.Xr syscons 4 , 559.Xr vga 4 , 560.Xr vt 4 , 561.Xr rc.conf 5 , 562.Xr kldload 8 , 563.Xr moused 8 , 564.Xr watch 8 565.Pp 566The various 567.Pa scr2* 568utilities in the 569.Pa graphics 570and 571.Pa textproc 572categories of the 573.Em "Ports Collection" . 574.Sh AUTHORS 575.An S\(/oren Schmidt Aq Mt sos@FreeBSD.org 576.An Sascha Wildner Aq Mt saw@online.de 577.Sh CONTRIBUTORS 578.An -split 579.An Maxim Sobolev Aq Mt sobomax@FreeBSD.org 580.An Nik Clayton Aq Mt nik@FreeBSD.org 581