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 April 6, 2022 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. 391Supported only with 392.Xr syscons 4 . 393.It Fl P 394Same as 395.Fl p , 396but dump contents of the video buffer in a plain text format 397ignoring nonprintable characters and information about text 398attributes. 399Supported only with 400.Xr syscons 4 . 401.It Fl H 402When used with 403.Fl p 404or 405.Fl P , 406it instructs 407.Nm 408to dump full history buffer instead of visible portion of 409the video buffer only. 410.It Fl r Ar foreground background 411Change reverse mode colors to 412.Ar foreground 413and 414.Ar background . 415.It Fl S Cm on | off 416Turn vty switching on or off. 417When vty switching is off, 418attempts to switch to a different virtual terminal will fail. 419(The default is to permit vty switching.) 420This protection can be easily bypassed when the kernel is compiled with 421the 422.Dv DDB 423option. 424However, you probably should not compile the kernel debugger on a box which 425is supposed to be physically secure. 426.It Fl s Ar number 427Set the active vty to 428.Ar number . 429.It Fl T Cm xterm | cons25 430Switch between xterm and cons25 style terminal emulation. 431.It Fl t Ar N | Cm off 432Set the screensaver timeout to 433.Ar N 434seconds, or turns it 435.Cm off . 436.It Fl x 437Use hexadecimal digits for output. 438.El 439.Ss Video Mode Support 440Note that not all modes listed above may be supported by the video 441hardware. 442You can verify which mode is supported by the video hardware, using the 443.Fl i Cm mode 444option. 445.Pp 446The VESA BIOS support must be linked to the kernel 447or loaded as a KLD module if you wish to use VESA video modes 448or 132 column modes 449(see 450.Xr vga 4 ) . 451.Pp 452You need to compile your kernel with the 453.Ar VGA_WIDTH90 454option if you wish to use VGA 90 column modes 455(see 456.Xr vga 4 ) . 457.Pp 458Video modes other than 25 and 30 line modes may require specific size of font. 459Use 460.Fl f 461option above to load a font file to the kernel. 462If the required size of font has not been loaded to the kernel, 463.Nm 464will fail if the user attempts to set a new video mode. 465.Pp 466.Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact 467.Sy Modes Ta Sy Font size 468.No 25 line modes Ta 8x16 (VGA), 8x14 (EGA) 469.No 30 line modes Ta 8x16 470.No 43 line modes Ta 8x8 471.No 50 line modes Ta 8x8 472.No 60 line modes Ta 8x8 473.El 474.Pp 475It is better to always load all three sizes (8x8, 8x14 and 8x16) 476of the same font. 477.Pp 478You may set variables in 479.Pa /etc/rc.conf 480or 481.Pa /etc/rc.conf.local 482so that desired font files will be automatically loaded 483when the system starts up. 484See below. 485.Pp 486If you want to use any of the raster text modes you need to recompile your 487kernel with the 488.Dv SC_PIXEL_MODE 489option. 490See 491.Xr syscons 4 492or 493.Xr vt 4 494(depending on which driver you use) 495for more details on this kernel option. 496.Ss Format of Video Buffer Dump 497The 498.Nm 499utility uses the 500.Xr syscons 4 501.\" is it supported on vt(4)??? 502or 503.Xr vt 4 504.Dv CONS_SCRSHOT 505.Xr ioctl 2 506to capture the current contents of the video buffer. 507The 508.Nm 509utility writes version and additional information to the standard 510output, followed by the contents of the video buffer. 511.Pp 512VGA video memory is typically arranged in two byte tuples, 513one per character position. 514In each tuple, the first byte will be the character code, 515and the second byte is the character's color attribute. 516.Pp 517The VGA color attribute byte looks like this: 518.Bl -column "X:X" "<00000000>" "width" "bright foreground color" 519.Sy "bits# width meaning" 520.Li "7 <X0000000> 1 character blinking" 521.Li "6:4 <0XXX0000> 3 background color" 522.Li "3 <0000X000> 1 bright foreground color" 523.Li "2:0 <00000XXX> 3 foreground color" 524.El 525.Pp 526Here is a list of the three bit wide base colors: 527.Pp 528.Bl -hang -offset indent -compact 529.It 0 530Black 531.It 1 532Blue 533.It 2 534Green 535.It 3 536Cyan 537.It 4 538Red 539.It 5 540Magenta 541.It 6 542Brown 543.It 7 544Light Grey 545.El 546.Pp 547Base colors with bit 3 (the bright foreground flag) set: 548.Pp 549.Bl -hang -offset indent -compact 550.It 0 551Dark Grey 552.It 1 553Light Blue 554.It 2 555Light Green 556.It 3 557Light Cyan 558.It 4 559Light Red 560.It 5 561Light Magenta 562.It 6 563Yellow 564.It 7 565White 566.El 567.Pp 568For example, the two bytes 569.Pp 570.Dl "65 158" 571.Pp 572specify an uppercase A (character code 65), blinking 573(bit 7 set) in yellow (bits 3:0) on a blue background 574(bits 6:4). 575.Pp 576The 577.Nm 578output contains a small header which includes additional 579information which may be useful to utilities processing 580the output. 581.Pp 582The first 10 bytes are always arranged as follows: 583.Bl -column "Byte range" "Contents" -offset indent 584.It Sy "Byte Range Contents" 585.It "1 - 8 Literal text" Dq Li SCRSHOT_ 586.It "9 File format version number" 587.It "10 Remaining number of bytes in the header" 588.El 589.Pp 590Subsequent bytes depend on the version number. 591.Bl -column "Version" "13 and up" -offset indent 592.It Sy "Version Byte Meaning" 593.It "1 11 Terminal width, in characters" 594.It " 12 Terminal depth, in characters" 595.It " 13 and up The snapshot data" 596.El 597.Pp 598So a dump of an 80x25 screen would start (in hex) 599.Bd -literal -offset indent 60053 43 52 53 48 4f 54 5f 01 02 50 19 601----------------------- -- -- -- -- 602 | | | | ` 25 decimal 603 | | | `--- 80 decimal 604 | | `------ 2 remaining bytes of header data 605 | `--------- File format version 1 606 `------------------------ Literal "SCRSHOT_" 607.Ed 608.Sh VIDEO OUTPUT CONFIGURATION 609.Ss Boot Time Configuration 610You may set the following variables in 611.Pa /etc/rc.conf 612or 613.Pa /etc/rc.conf.local 614in order to configure the video output at boot time. 615.Pp 616.Bl -tag -width foo_bar_var -compact 617.It Ar blanktime 618Sets the timeout value for the 619.Fl t 620option. 621.It Ar font8x16 , font8x14 , font8x8 622Specifies font files for the 623.Fl f 624option. 625.It Ar scrnmap 626Specifies a screen output map file for the 627.Fl l 628option. 629.El 630.Pp 631See 632.Xr rc.conf 5 633for more details. 634.Ss Driver Configuration 635The video card driver may let you change default configuration 636options, such as the default font, so that you do not need to set up 637the options at boot time. 638See video card driver manuals, (e.g., 639.Xr vga 4 ) 640for details. 641.Sh FILES 642.Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact 643.It Pa /usr/share/syscons/fonts/* 644.It Pa /usr/share/vt/fonts/* 645font files. 646.It Pa /usr/share/syscons/scrnmaps/* 647screen output map files (relevant for 648.Xr syscons 4 649only). 650.El 651.Sh EXAMPLES 652If you want to load 653.Pa /usr/share/syscons/fonts/iso-8x16.fnt 654to the kernel, run 655.Nm 656as: 657.Pp 658.Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt 659.Pp 660So long as the font file is in 661.Pa /usr/share/syscons/fonts 662(if using syscons) or 663.Pa /usr/share/vt/fonts 664(if using vt), 665you may abbreviate the file name as 666.Pa iso-8x16 : 667.Pp 668.Dl vidcontrol -f 8x16 iso-8x16 669.Pp 670Furthermore, you can also omit font size 671.Dq Li 8x16 : 672.Pp 673.Dl vidcontrol -f iso-8x16 674.Pp 675Moreover, the suffix specifying the font size can also be omitted; in 676this case, 677.Nm 678will use the size of the currently displayed font to construct the 679suffix: 680.Pp 681.Dl vidcontrol -f iso 682.Pp 683Likewise, you can also abbreviate the screen output map file name for 684the 685.Fl l 686option if the file is found in 687.Pa /usr/share/syscons/scrnmaps . 688.Pp 689.Dl vidcontrol -l iso-8859-1_to_cp437 690.Pp 691The above command will load 692.Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm . 693.Pp 694The following command will set-up a 100x37 raster text mode (useful for 695some LCD models): 696.Pp 697.Dl vidcontrol -g 100x37 VESA_800x600 698.Pp 699The following command will capture the contents of the first virtual 700terminal video buffer, and redirect the output to the 701.Pa shot.scr 702file: 703.Pp 704.Dl vidcontrol -p < /dev/ttyv0 > shot.scr 705.Pp 706The following command will dump contents of the fourth virtual terminal 707video buffer 708to the standard output in the human readable format: 709.Pp 710.Dl vidcontrol -P < /dev/ttyv3 711.Sh SEE ALSO 712.Xr kbdcontrol 1 , 713.Xr vidfont 1 , 714.Xr keyboard 4 , 715.Xr screen 4 , 716.Xr syscons 4 , 717.Xr vga 4 , 718.Xr vt 4 , 719.Xr rc.conf 5 , 720.Xr kldload 8 , 721.Xr moused 8 , 722.Xr watch 8 723.Pp 724The various 725.Pa scr2* 726utilities in the 727.Pa graphics 728and 729.Pa textproc 730categories of the 731.Em "Ports Collection" . 732.Sh AUTHORS 733.An S\(/oren Schmidt Aq Mt sos@FreeBSD.org 734.An Sascha Wildner Aq Mt saw@online.de 735.Sh CONTRIBUTORS 736.An -split 737.An Maxim Sobolev Aq Mt sobomax@FreeBSD.org 738.An Nik Clayton Aq Mt nik@FreeBSD.org 739