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 October 20, 2018 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 CdHLPpx 25.Op Fl b Ar color 26.Op Fl c Ar appearance 27.Op Fl E Ar emulator 28.Oo 29.Fl f 30.Oo 31.Op Ar size 32.Ar file 33.Oc 34.Oc 35.Op Fl g Ar geometry 36.Op Fl h Ar size 37.Op Fl i Cm active | adapter | mode 38.Op Fl l Ar screen_map 39.Op Fl M Ar char 40.Op Fl m Cm on | off 41.Op Fl r Ar foreground Ar background 42.Op Fl S Cm on | off 43.Op Fl s Ar number 44.Op Fl T Cm xterm | cons25 45.Op Fl t Ar N | Cm off 46.Op Ar mode 47.Op Ar foreground Op Ar background 48.Op Cm show 49.Sh DESCRIPTION 50The 51.Nm 52utility is used to set various options for the 53.Xr syscons 4 54or 55.Xr vt 4 56console driver, 57such as video mode, colors, cursor shape, screen output map, font, and screen 58saver timeout. 59Only a small subset of options is supported by 60.Xr vt 4 . 61Unsupported options lead to error messages, typically including 62the text "Inappropriate ioctl for device". 63.Pp 64The following command line options are supported: 65.Bl -tag -width indent 66.It Ar mode 67Select a new video mode. 68The modes currently recognized are: 69.Ar 80x25 , 70.Ar 80x30 , 71.Ar 80x43 , 72.Ar 80x50 , 73.Ar 80x60 , 74.Ar 132x25 , 75.Ar 132x30 , 76.Ar 132x43 , 77.Ar 132x50 , 78.Ar 132x60 , 79.Ar VGA_40x25 , 80.Ar VGA_80x25 , 81.Ar VGA_80x30 , 82.Ar VGA_80x50 , 83.Ar VGA_80x60 , 84.Ar VGA_90x25 , 85.Ar VGA_90x30 , 86.Ar VGA_90x43 , 87.Ar VGA_90x50 , 88.Ar VGA_90x60 , 89.Ar EGA_80x25 , 90.Ar EGA_80x43 , 91.Ar VESA_132x25 , 92.Ar VESA_132x43 , 93.Ar VESA_132x50 , 94.Ar VESA_132x60 . 95.\"The graphic mode 96.\".Ar VGA_320x200 97.\"and 98The raster text mode 99.Ar VESA_800x600 100can also be chosen. 101Alternatively, a mode can be specified with its number by using a mode name of 102the form 103.Li MODE_ Ns Aq Ar NUMBER . 104A list of valid mode numbers can be obtained with the 105.Fl i Cm mode 106option. 107See 108.Sx Video Mode Support 109below. 110.It Ar foreground Op Ar background 111Change colors when displaying text. 112Specify the foreground color 113(e.g., 114.Dq vidcontrol white ) , 115or both a foreground and background colors 116(e.g., 117.Dq vidcontrol yellow blue ) . 118Use the 119.Cm show 120command below to see available colors. 121.It Cm show 122See the supported colors on a given platform. 123.It Fl b Ar color 124Set border color to 125.Ar color . 126This option may not be always supported by the video driver. 127.It Fl C 128Clear the history buffer. 129.It Fl c Ar setting Ns Op , Ns Ar setting ... 130Change the cursor appearance. 131The change is specified by a non-empty comma-separated list of 132.Ar setting Ns s . 133Each 134.Ar setting 135overrides or modifies previous ones in left to right order. 136.Pp 137The following override 138.Ar setting Ns s 139are available: 140.Bl -tag -width indent 141.It Cm normal 142Set to a block covering 1 character cell, 143with a configuration-dependent coloring 144that should be at worst inverse video. 145.It Cm destructive 146Set to a blinking sub-block with 147.Cm height 148scanlines starting at 149.Cm base . 150The name 151.Dq destructive 152is bad for backwards compatibility. 153This 154.Ar setting 155should not force destructiveness, 156and it now only gives destructiveness in some 157configurations (typically for hardware cursors 158in text mode). 159Blinking limits destructiveness. 160This 161.Ar setting 162should now be spelled 163.Cm normal , Ns Cm blink , Ns Cm noblock . 164A non-blinking destructive cursor would be unusable, 165so old versions of 166.Nm 167did not support it, 168and this version does not have an override for it. 169.It Cm base Ns = Ns Ar value , Cm height Ns = Ns Ar value 170Set the specified scanline parameters. 171These parameters are only active in 172.Cm noblock 173mode. 174.Cm value 175is an integer in any base supported by 176.Xr strtol 3 . 177Setting 178.Cm height 179to 0 turns off the cursor in 180.Cm noblock 181mode. 182Negative 183.Ar value Ns s 184are silently ignored. 185Positive 186.Ar value Ns s 187are clamped to fit in the character cell when the cursor is drawn. 188.El 189.Pp 190The following modifier 191.Ar setting Ns s 192are available: 193.Bl -tag -width indent 194.It Cm blink , noblink 195Set or clear the blinking attribute. 196This is not quite backwards compatible. 197In old versions of 198.Nm , Cm blink 199was an override to a blinking block. 200.It Cm block , noblock 201Set or clear the 202.Cm block 203attribute. 204This attribute is the inverse of the flag 205.Dv CONS_CHAR_CURSOR 206in the implementation. 207It deactivates the scanline parameters, 208and expresses a preference for using a 209simpler method of implementation. 210Its inverse does the opposite. 211When the scanline parameters give a full block, 212this attribute reduces to a method selection bit. 213The 214.Cm block 215method tends to give better coloring. 216.It Cm hidden , nohidden 217Set or clear the hidden attribute. 218.El 219.Pp 220The following (non-sticky) flags control application of the 221.Ar setting Ns s : 222.Bl -tag -width indent 223.It Cm charcolors 224Apply 225.Cm base 226and 227.Cm height 228to the (character) cursor's list of preferred colors instead of its shape. 229Beware that the color numbers are raw VGA palette indexes, 230not ANSI color numbers. 231The indexes are reduced mod 8, 16 or 256, 232or ignored, 233depending on the video mode and renderer. 234.It Cm mousecolors 235Colors for the mouse cursor in graphics mode. 236Like 237.Cm charcolors , 238except there is no preference or sequence; 239.Cm base 240gives the mouse border color and 241.Cm height 242gives the mouse interior color. 243Together with 244.Cm charcolors , 245this gives 2 selection bits which select between 246only 3 of 4 sub-destinations of the 4 destinations selected by 247.Cm default 248and 249.Cm local 250(by ignoring 251.Cm mousecolors 252if 253.Cm charcolors 254is also set). 255.It Cm default 256Apply the changes to the default settings and then to the active settings, 257instead of only to the active settings. 258Together with 259.Cm local , 260this gives 2 selection bits which select between 4 destinations. 261.It Cm shapeonly 262Ignore any changes to the 263.Cm block 264and 265.Cm hidden 266attributes. 267.It Cm local 268Apply the changes to the current vty. 269The default is to apply them to a global place 270and copy from there to all vtys. 271.It Cm reset 272Reset everything. 273The default is to not reset. 274When the 275.Cm local 276parameter is specified, the current local settings are reset 277to default local settings. 278Otherwise, the current global settings are reset to default 279global settings and then copied to the current and default 280settings for all vtys. 281.It Cm show 282Show the current changes. 283.El 284.It Fl d 285Print out current output screen map. 286.It Fl E Ar emulator 287Set the terminal emulator to 288.Ar emulator . 289.It Fl e 290Show the active and available terminal emulators. 291.It Xo 292.Fl f 293.Oo 294.Op Ar size 295.Ar file 296.Oc 297.Xc 298Load font 299.Ar file 300for 301.Ar size 302(currently, only 303.Cm 8x8 , 304.Cm 8x14 305or 306.Cm 8x16 ) . 307The font file can be either uuencoded or in raw binary format. 308You can also use the menu-driven 309.Xr vidfont 1 310command to load the font of your choice. 311.Pp 312.Ar Size 313may be omitted, in this case 314.Nm 315will try to guess it from the size of font file. 316.Pp 317When using 318.Xr vt 4 319both 320.Ar size 321and 322.Ar file 323can be omitted, and the default font will be loaded. 324.Pp 325Note that older video cards, such as MDA and CGA, do not support 326software font. 327See also 328.Sx Video Mode Support 329and 330.Sx EXAMPLES 331below and the man page for either 332.Xr syscons 4 333or 334.Xr vt 4 335(depending on which driver you use). 336.It Fl g Ar geometry 337Set the 338.Ar geometry 339of the text mode for the modes with selectable 340geometry. 341Currently only raster modes, such as 342.Ar VESA_800x600 , 343support this option. 344See also 345.Sx Video Mode Support 346and 347.Sx EXAMPLES 348below. 349.It Fl h Ar size 350Set the size of the history (scrollback) buffer to 351.Ar size 352lines. 353.It Fl i Cm active 354Shows the active vty number. 355.It Fl i Cm adapter 356Shows info about the current video adapter. 357.It Fl i Cm mode 358Shows the possible video modes with the current video hardware. 359.It Fl l Ar screen_map 360Install screen output map file from 361.Ar screen_map . 362See also 363.Xr syscons 4 364or 365.Xr vt 4 366(depending on which driver you use). 367.It Fl L 368Install default screen output map. 369.It Fl M Ar char 370Sets the base character used to render the mouse pointer to 371.Ar char . 372.It Fl m Cm on | off 373Switch the mouse pointer 374.Cm on 375or 376.Cm off . 377Used together with the 378.Xr moused 8 379daemon for text mode cut & paste functionality. 380.It Fl p 381Capture the current contents of the video buffer corresponding 382to the terminal device referred to by standard input. 383The 384.Nm 385utility writes contents of the video buffer to the standard 386output in a raw binary format. 387For details about that 388format see 389.Sx Format of Video Buffer Dump 390below. 391.It Fl P 392Same as 393.Fl p , 394but dump contents of the video buffer in a plain text format 395ignoring nonprintable characters and information about text 396attributes. 397.It Fl H 398When used with 399.Fl p 400or 401.Fl P , 402it instructs 403.Nm 404to dump full history buffer instead of visible portion of 405the video buffer only. 406.It Fl r Ar foreground background 407Change reverse mode colors to 408.Ar foreground 409and 410.Ar background . 411.It Fl S Cm on | off 412Turn vty switching on or off. 413When vty switching is off, 414attempts to switch to a different virtual terminal will fail. 415(The default is to permit vty switching.) 416This protection can be easily bypassed when the kernel is compiled with 417the 418.Dv DDB 419option. 420However, you probably should not compile the kernel debugger on a box which 421is supposed to be physically secure. 422.It Fl s Ar number 423Set the active vty to 424.Ar number . 425.It Fl T Cm xterm | cons25 426Switch between xterm and cons25 style terminal emulation. 427.It Fl t Ar N | Cm off 428Set the screensaver timeout to 429.Ar N 430seconds, or turns it 431.Cm off . 432.It Fl x 433Use hexadecimal digits for output. 434.El 435.Ss Video Mode Support 436Note that not all modes listed above may be supported by the video 437hardware. 438You can verify which mode is supported by the video hardware, using the 439.Fl i Cm mode 440option. 441.Pp 442The VESA BIOS support must be linked to the kernel 443or loaded as a KLD module if you wish to use VESA video modes 444or 132 column modes 445(see 446.Xr vga 4 ) . 447.Pp 448You need to compile your kernel with the 449.Ar VGA_WIDTH90 450option if you wish to use VGA 90 column modes 451(see 452.Xr vga 4 ) . 453.Pp 454Video modes other than 25 and 30 line modes may require specific size of font. 455Use 456.Fl f 457option above to load a font file to the kernel. 458If the required size of font has not been loaded to the kernel, 459.Nm 460will fail if the user attempts to set a new video mode. 461.Pp 462.Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact 463.Sy Modes Ta Sy Font size 464.No 25 line modes Ta 8x16 (VGA), 8x14 (EGA) 465.No 30 line modes Ta 8x16 466.No 43 line modes Ta 8x8 467.No 50 line modes Ta 8x8 468.No 60 line modes Ta 8x8 469.El 470.Pp 471It is better to always load all three sizes (8x8, 8x14 and 8x16) 472of the same font. 473.Pp 474You may set variables in 475.Pa /etc/rc.conf 476or 477.Pa /etc/rc.conf.local 478so that desired font files will be automatically loaded 479when the system starts up. 480See below. 481.Pp 482If you want to use any of the raster text modes you need to recompile your 483kernel with the 484.Dv SC_PIXEL_MODE 485option. 486See 487.Xr syscons 4 488or 489.Xr vt 4 490(depending on which driver you use) 491for more details on this kernel option. 492.Ss Format of Video Buffer Dump 493The 494.Nm 495utility uses the 496.Xr syscons 4 497.\" is it supported on vt(4)??? 498or 499.Xr vt 4 500.Dv CONS_SCRSHOT 501.Xr ioctl 2 502to capture the current contents of the video buffer. 503The 504.Nm 505utility writes version and additional information to the standard 506output, followed by the contents of the video buffer. 507.Pp 508VGA video memory is typically arranged in two byte tuples, 509one per character position. 510In each tuple, the first byte will be the character code, 511and the second byte is the character's color attribute. 512.Pp 513The VGA color attribute byte looks like this: 514.Bl -column "X:X" "<00000000>" "width" "bright foreground color" 515.Sy "bits# width meaning" 516.Li "7 <X0000000> 1 character blinking" 517.Li "6:4 <0XXX0000> 3 background color" 518.Li "3 <0000X000> 1 bright foreground color" 519.Li "2:0 <00000XXX> 3 foreground color" 520.El 521.Pp 522Here is a list of the three bit wide base colors: 523.Pp 524.Bl -hang -offset indent -compact 525.It 0 526Black 527.It 1 528Blue 529.It 2 530Green 531.It 3 532Cyan 533.It 4 534Red 535.It 5 536Magenta 537.It 6 538Brown 539.It 7 540Light Grey 541.El 542.Pp 543Base colors with bit 3 (the bright foreground flag) set: 544.Pp 545.Bl -hang -offset indent -compact 546.It 0 547Dark Grey 548.It 1 549Light Blue 550.It 2 551Light Green 552.It 3 553Light Cyan 554.It 4 555Light Red 556.It 5 557Light Magenta 558.It 6 559Yellow 560.It 7 561White 562.El 563.Pp 564For example, the two bytes 565.Pp 566.Dl "65 158" 567.Pp 568specify an uppercase A (character code 65), blinking 569(bit 7 set) in yellow (bits 3:0) on a blue background 570(bits 6:4). 571.Pp 572The 573.Nm 574output contains a small header which includes additional 575information which may be useful to utilities processing 576the output. 577.Pp 578The first 10 bytes are always arranged as follows: 579.Bl -column "Byte range" "Contents" -offset indent 580.It Sy "Byte Range Contents" 581.It "1 - 8 Literal text" Dq Li SCRSHOT_ 582.It "9 File format version number" 583.It "10 Remaining number of bytes in the header" 584.El 585.Pp 586Subsequent bytes depend on the version number. 587.Bl -column "Version" "13 and up" -offset indent 588.It Sy "Version Byte Meaning" 589.It "1 11 Terminal width, in characters" 590.It " 12 Terminal depth, in characters" 591.It " 13 and up The snapshot data" 592.El 593.Pp 594So a dump of an 80x25 screen would start (in hex) 595.Bd -literal -offset indent 59653 43 52 53 48 4f 54 5f 01 02 50 19 597----------------------- -- -- -- -- 598 | | | | ` 25 decimal 599 | | | `--- 80 decimal 600 | | `------ 2 remaining bytes of header data 601 | `--------- File format version 1 602 `------------------------ Literal "SCRSHOT_" 603.Ed 604.Sh VIDEO OUTPUT CONFIGURATION 605.Ss Boot Time Configuration 606You may set the following variables in 607.Pa /etc/rc.conf 608or 609.Pa /etc/rc.conf.local 610in order to configure the video output at boot time. 611.Pp 612.Bl -tag -width foo_bar_var -compact 613.It Ar blanktime 614Sets the timeout value for the 615.Fl t 616option. 617.It Ar font8x16 , font8x14 , font8x8 618Specifies font files for the 619.Fl f 620option. 621.It Ar scrnmap 622Specifies a screen output map file for the 623.Fl l 624option. 625.El 626.Pp 627See 628.Xr rc.conf 5 629for more details. 630.Ss Driver Configuration 631The video card driver may let you change default configuration 632options, such as the default font, so that you do not need to set up 633the options at boot time. 634See video card driver manuals, (e.g., 635.Xr vga 4 ) 636for details. 637.Sh FILES 638.Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact 639.It Pa /usr/share/syscons/fonts/* 640.It Pa /usr/share/vt/fonts/* 641font files. 642.It Pa /usr/share/syscons/scrnmaps/* 643screen output map files (relevant for 644.Xr syscons 4 645only). 646.El 647.Sh EXAMPLES 648If you want to load 649.Pa /usr/share/syscons/fonts/iso-8x16.fnt 650to the kernel, run 651.Nm 652as: 653.Pp 654.Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt 655.Pp 656So long as the font file is in 657.Pa /usr/share/syscons/fonts 658(if using syscons) or 659.Pa /usr/share/vt/fonts 660(if using vt), 661you may abbreviate the file name as 662.Pa iso-8x16 : 663.Pp 664.Dl vidcontrol -f 8x16 iso-8x16 665.Pp 666Furthermore, you can also omit font size 667.Dq Li 8x16 : 668.Pp 669.Dl vidcontrol -f iso-8x16 670.Pp 671Moreover, the suffix specifying the font size can also be omitted; in 672this case, 673.Nm 674will use the size of the currently displayed font to construct the 675suffix: 676.Pp 677.Dl vidcontrol -f iso 678.Pp 679Likewise, you can also abbreviate the screen output map file name for 680the 681.Fl l 682option if the file is found in 683.Pa /usr/share/syscons/scrnmaps . 684.Pp 685.Dl vidcontrol -l iso-8859-1_to_cp437 686.Pp 687The above command will load 688.Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm . 689.Pp 690The following command will set-up a 100x37 raster text mode (useful for 691some LCD models): 692.Pp 693.Dl vidcontrol -g 100x37 VESA_800x600 694.Pp 695The following command will capture the contents of the first virtual 696terminal video buffer, and redirect the output to the 697.Pa shot.scr 698file: 699.Pp 700.Dl vidcontrol -p < /dev/ttyv0 > shot.scr 701.Pp 702The following command will dump contents of the fourth virtual terminal 703video buffer 704to the standard output in the human readable format: 705.Pp 706.Dl vidcontrol -P < /dev/ttyv3 707.Sh SEE ALSO 708.Xr kbdcontrol 1 , 709.Xr vidfont 1 , 710.Xr keyboard 4 , 711.Xr screen 4 , 712.Xr syscons 4 , 713.Xr vga 4 , 714.Xr vt 4 , 715.Xr rc.conf 5 , 716.Xr kldload 8 , 717.Xr moused 8 , 718.Xr watch 8 719.Pp 720The various 721.Pa scr2* 722utilities in the 723.Pa graphics 724and 725.Pa textproc 726categories of the 727.Em "Ports Collection" . 728.Sh AUTHORS 729.An S\(/oren Schmidt Aq Mt sos@FreeBSD.org 730.An Sascha Wildner Aq Mt saw@online.de 731.Sh CONTRIBUTORS 732.An -split 733.An Maxim Sobolev Aq Mt sobomax@FreeBSD.org 734.An Nik Clayton Aq Mt nik@FreeBSD.org 735