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