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