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