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 January 19, 2016 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 active | 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 active 202Shows the active vty number. 203.It Fl i Cm adapter 204Shows info about the current video adapter. 205.It Fl i Cm mode 206Shows the possible video modes with the current video hardware. 207.It Fl l Ar screen_map 208Install screen output map file from 209.Ar screen_map . 210See also 211.Xr syscons 4 212or 213.Xr vt 4 214(depending on which driver you use). 215.It Fl L 216Install default screen output map. 217.It Fl M Ar char 218Sets the base character used to render the mouse pointer to 219.Ar char . 220.It Fl m Cm on | off 221Switch the mouse pointer 222.Cm on 223or 224.Cm off . 225Used together with the 226.Xr moused 8 227daemon for text mode cut & paste functionality. 228.It Fl p 229Capture the current contents of the video buffer corresponding 230to the terminal device referred to by standard input. 231The 232.Nm 233utility writes contents of the video buffer to the standard 234output in a raw binary format. 235For details about that 236format see 237.Sx Format of Video Buffer Dump 238below. 239.It Fl P 240Same as 241.Fl p , 242but dump contents of the video buffer in a plain text format 243ignoring nonprintable characters and information about text 244attributes. 245.It Fl H 246When used with 247.Fl p 248or 249.Fl P , 250it instructs 251.Nm 252to dump full history buffer instead of visible portion of 253the video buffer only. 254.It Fl r Ar foreground background 255Change reverse mode colors to 256.Ar foreground 257and 258.Ar background . 259.It Fl S Cm on | off 260Turn vty switching on or off. 261When vty switching is off, 262attempts to switch to a different virtual terminal will fail. 263(The default is to permit vty switching.) 264This protection can be easily bypassed when the kernel is compiled with 265the 266.Dv DDB 267option. 268However, you probably should not compile the kernel debugger on a box which 269is supposed to be physically secure. 270.It Fl s Ar number 271Set the active vty to 272.Ar number . 273.It Fl T Cm xterm | cons25 274Switch between xterm and cons25 style terminal emulation. 275.It Fl t Ar N | Cm off 276Set the screensaver timeout to 277.Ar N 278seconds, or turns it 279.Cm off . 280.It Fl x 281Use hexadecimal digits for output. 282.El 283.Ss Video Mode Support 284Note that not all modes listed above may be supported by the video 285hardware. 286You can verify which mode is supported by the video hardware, using the 287.Fl i Cm mode 288option. 289.Pp 290The VESA BIOS support must be linked to the kernel 291or loaded as a KLD module if you wish to use VESA video modes 292or 132 column modes 293(see 294.Xr vga 4 ) . 295.Pp 296You need to compile your kernel with the 297.Ar VGA_WIDTH90 298option if you wish to use VGA 90 column modes 299(see 300.Xr vga 4 ) . 301.Pp 302Video modes other than 25 and 30 line modes may require specific size of font. 303Use 304.Fl f 305option above to load a font file to the kernel. 306If the required size of font has not been loaded to the kernel, 307.Nm 308will fail if the user attempts to set a new video mode. 309.Pp 310.Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact 311.Sy Modes Ta Sy Font size 312.No 25 line modes Ta 8x16 (VGA), 8x14 (EGA) 313.No 30 line modes Ta 8x16 314.No 43 line modes Ta 8x8 315.No 50 line modes Ta 8x8 316.No 60 line modes Ta 8x8 317.El 318.Pp 319It is better to always load all three sizes (8x8, 8x14 and 8x16) 320of the same font. 321.Pp 322You may set variables in 323.Pa /etc/rc.conf 324or 325.Pa /etc/rc.conf.local 326so that desired font files will be automatically loaded 327when the system starts up. 328See below. 329.Pp 330If you want to use any of the raster text modes you need to recompile your 331kernel with the 332.Dv SC_PIXEL_MODE 333option. 334See 335.Xr syscons 4 336or 337.Xr vt 4 338(depending on which driver you use) 339for more details on this kernel option. 340.Ss Format of Video Buffer Dump 341The 342.Nm 343utility uses the 344.Xr syscons 4 345.\" is it supported on vt(4)??? 346or 347.Xr vt 4 348.Dv CONS_SCRSHOT 349.Xr ioctl 2 350to capture the current contents of the video buffer. 351The 352.Nm 353utility writes version and additional information to the standard 354output, followed by the contents of the video buffer. 355.Pp 356VGA video memory is typically arranged in two byte tuples, 357one per character position. 358In each tuple, the first byte will be the character code, 359and the second byte is the character's color attribute. 360.Pp 361The VGA color attribute byte looks like this: 362.Bl -column "X:X" "<00000000>" "width" "bright foreground color" 363.Sy "bits# width meaning" 364.Li "7 <X0000000> 1 character blinking" 365.Li "6:4 <0XXX0000> 3 background color" 366.Li "3 <0000X000> 1 bright foreground color" 367.Li "2:0 <00000XXX> 3 foreground color" 368.El 369.Pp 370Here is a list of the three bit wide base colors: 371.Pp 372.Bl -hang -offset indent -compact 373.It 0 374Black 375.It 1 376Blue 377.It 2 378Green 379.It 3 380Cyan 381.It 4 382Red 383.It 5 384Magenta 385.It 6 386Brown 387.It 7 388Light Grey 389.El 390.Pp 391Base colors with bit 3 (the bright foreground flag) set: 392.Pp 393.Bl -hang -offset indent -compact 394.It 0 395Dark Grey 396.It 1 397Light Blue 398.It 2 399Light Green 400.It 3 401Light Cyan 402.It 4 403Light Red 404.It 5 405Light Magenta 406.It 6 407Yellow 408.It 7 409White 410.El 411.Pp 412For example, the two bytes 413.Pp 414.Dl "65 158" 415.Pp 416specify an uppercase A (character code 65), blinking 417(bit 7 set) in yellow (bits 3:0) on a blue background 418(bits 6:4). 419.Pp 420The 421.Nm 422output contains a small header which includes additional 423information which may be useful to utilities processing 424the output. 425.Pp 426The first 10 bytes are always arranged as follows: 427.Bl -column "Byte range" "Contents" -offset indent 428.It Sy "Byte Range Contents" 429.It "1 thru 8 Literal text" Dq Li SCRSHOT_ 430.It "9 File format version number" 431.It "10 Remaining number of bytes in the header" 432.El 433.Pp 434Subsequent bytes depend on the version number. 435.Bl -column "Version" "13 and up" -offset indent 436.It Sy "Version Byte Meaning" 437.It "1 11 Terminal width, in characters" 438.It " 12 Terminal depth, in characters" 439.It " 13 and up The snapshot data" 440.El 441.Pp 442So a dump of an 80x25 screen would start (in hex) 443.Bd -literal -offset indent 44453 43 52 53 48 4f 54 5f 01 02 50 19 445----------------------- -- -- -- -- 446 | | | | ` 25 decimal 447 | | | `--- 80 decimal 448 | | `------ 2 remaining bytes of header data 449 | `--------- File format version 1 450 `------------------------ Literal "SCRSHOT_" 451.Ed 452.Sh VIDEO OUTPUT CONFIGURATION 453.Ss Boot Time Configuration 454You may set the following variables in 455.Pa /etc/rc.conf 456or 457.Pa /etc/rc.conf.local 458in order to configure the video output at boot time. 459.Pp 460.Bl -tag -width foo_bar_var -compact 461.It Ar blanktime 462Sets the timeout value for the 463.Fl t 464option. 465.It Ar font8x16 , font8x14 , font8x8 466Specifies font files for the 467.Fl f 468option. 469.It Ar scrnmap 470Specifies a screen output map file for the 471.Fl l 472option. 473.El 474.Pp 475See 476.Xr rc.conf 5 477for more details. 478.Ss Driver Configuration 479The video card driver may let you change default configuration 480options, such as the default font, so that you do not need to set up 481the options at boot time. 482See video card driver manuals, (e.g.\& 483.Xr vga 4 ) 484for details. 485.Sh FILES 486.Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact 487.It Pa /usr/share/syscons/fonts/* 488.It Pa /usr/share/vt/fonts/* 489font files. 490.It Pa /usr/share/syscons/scrnmaps/* 491screen output map files (relevant for 492.Xr syscons 4 493only). 494.El 495.Sh EXAMPLES 496If you want to load 497.Pa /usr/share/syscons/fonts/iso-8x16.fnt 498to the kernel, run 499.Nm 500as: 501.Pp 502.Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt 503.Pp 504So long as the font file is in 505.Pa /usr/share/syscons/fonts 506(if using syscons) or 507.Pa /usr/share/vt/fonts 508(if using vt), 509you may abbreviate the file name as 510.Pa iso-8x16 : 511.Pp 512.Dl vidcontrol -f 8x16 iso-8x16 513.Pp 514Furthermore, you can also omit font size 515.Dq Li 8x16 : 516.Pp 517.Dl vidcontrol -f iso-8x16 518.Pp 519Moreover, the suffix specifying the font size can be also omitted; in 520this case, 521.Nm 522will use the size of the currently displayed font to construct the 523suffix: 524.Pp 525.Dl vidcontrol -f iso 526.Pp 527Likewise, you can also abbreviate the screen output map file name for 528the 529.Fl l 530option if the file is found in 531.Pa /usr/share/syscons/scrnmaps . 532.Pp 533.Dl vidcontrol -l iso-8859-1_to_cp437 534.Pp 535The above command will load 536.Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm . 537.Pp 538The following command will set-up a 100x37 raster text mode (useful for 539some LCD models): 540.Pp 541.Dl vidcontrol -g 100x37 VESA_800x600 542.Pp 543The following command will capture the contents of the first virtual 544terminal video buffer, and redirect the output to the 545.Pa shot.scr 546file: 547.Pp 548.Dl vidcontrol -p < /dev/ttyv0 > shot.scr 549.Pp 550The following command will dump contents of the fourth virtual terminal 551video buffer 552to the standard output in the human readable format: 553.Pp 554.Dl vidcontrol -P < /dev/ttyv3 555.Sh SEE ALSO 556.Xr kbdcontrol 1 , 557.Xr vidfont 1 , 558.Xr keyboard 4 , 559.Xr screen 4 , 560.Xr syscons 4 , 561.Xr vga 4 , 562.Xr vt 4 , 563.Xr rc.conf 5 , 564.Xr kldload 8 , 565.Xr moused 8 , 566.Xr watch 8 567.Pp 568The various 569.Pa scr2* 570utilities in the 571.Pa graphics 572and 573.Pa textproc 574categories of the 575.Em "Ports Collection" . 576.Sh AUTHORS 577.An S\(/oren Schmidt Aq Mt sos@FreeBSD.org 578.An Sascha Wildner Aq Mt saw@online.de 579.Sh CONTRIBUTORS 580.An -split 581.An Maxim Sobolev Aq Mt sobomax@FreeBSD.org 582.An Nik Clayton Aq Mt nik@FreeBSD.org 583