1.\" 2.\" vidcontrol - a utility for manipulating the syscons 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 May 27, 2001 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 CdLPpx 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 Ar number 40.Op Fl t Ar N | Cm off 41.Op Ar mode 42.Op Ar foreground Op Ar background 43.Op Cm show 44.Sh DESCRIPTION 45The 46.Nm 47command is used to set various options for the 48.Xr syscons 4 49console driver, 50such as video mode, colors, cursor shape, screen output map, font and screen 51saver timeout. 52.Pp 53The following command line options are supported: 54.Bl -tag -width indent 55.It Ar mode 56Select a new video mode. 57The modes currently recognized are: 58.Ar 80x25 , 59.Ar 80x30 , 60.Ar 80x43 , 61.Ar 80x50 , 62.Ar 80x60 , 63.Ar 132x25 , 64.Ar 132x30 , 65.Ar 132x43 , 66.Ar 132x50 , 67.Ar 132x60 , 68.Ar VGA_40x25 , 69.Ar VGA_80x25 , 70.Ar VGA_80x30 , 71.Ar VGA_80x50 , 72.Ar VGA_80x60 , 73.Ar VGA_90x25 , 74.Ar VGA_90x30 , 75.Ar VGA_90x43 , 76.Ar VGA_90x50 , 77.Ar VGA_90x60 , 78.Ar EGA_80x25 , 79.Ar EGA_80x43 , 80.Ar VESA_132x25 , 81.Ar VESA_132x43 , 82.Ar VESA_132x50 , 83.Ar VESA_132x60 . 84.\"The graphic mode 85.\".Ar VGA_320x200 86.\"and 87The raster text mode 88.Ar VESA_800x600 89can also be chosen. 90See 91.Sx Video Mode Support 92below. 93.It Ar foreground Op Ar background 94Change colors when displaying text. 95Specify the foreground color 96(e.g. 97.Dq vidcontrol white ) , 98or both a foreground and background colors 99(e.g. 100.Dq vidcontrol yellow blue ) . 101Use the 102.Cm show 103command below to see available colors. 104.It Cm show 105See the supported colors on a given platform. 106.It Fl b Ar color 107Set border color to 108.Ar color . 109This option may not be always supported by the video driver. 110.It Fl C 111Clear the history buffer. 112.It Fl c Cm normal | blink | destructive 113Change the cursor appearance. 114The cursor is either an inverting block 115.Pq Cm normal 116that can optionally 117.Cm blink , 118or it can be like the old hardware cursor 119.Pq Cm destructive . 120The latter is actually a simulation. 121.It Fl d 122Print out current output screen map. 123.It Xo 124.Fl f 125.Op Ar size 126.Ar file 127.Xc 128Load font 129.Ar file 130for 131.Ar size 132(currently, only 133.Cm 8x8 , 134.Cm 8x14 135or 136.Cm 8x16 ) . 137The font file can be either uuencoded or in raw binary format. 138You can also use the menu-driven 139.Xr vidfont 1 140command to load the font of your choice. 141.Pp 142.Ar Size 143may be omitted, in this case 144.Nm 145will try to guess it from the size of font file. 146.Pp 147Note that older video cards, such as MDA and CGA, do not support 148software font. 149See also 150.Sx Video Mode Support 151and 152.Sx EXAMPLES 153below and the man page for 154.Xr syscons 4 . 155.It Fl g Ar geometry 156Set the 157.Ar geometry 158of the text mode for the modes with selectable 159geometry. 160Currently only raster modes, such as 161.Ar VESA_800x600 , 162support this option. 163See also 164.Sx Video Mode Support 165and 166.Sx EXAMPLES 167below. 168.It Fl h Cm size 169Set the size of the history (scrollback) buffer to 170.Cm size 171lines. 172.It Fl i Cm adapter 173Shows info about the current video adapter. 174.It Fl i Cm mode 175Shows the possible video modes with the current video hardware. 176.It Fl l Ar screen_map 177Install screen output map file from 178.Ar screen_map . 179See also 180.Xr syscons 4 . 181.It Fl L 182Install default screen output map. 183.It Fl M Ar char 184Sets the base character used to render the mouse pointer to 185.Ar char . 186.It Fl m Cm on | off 187Switch the mouse pointer 188.Cm on 189or 190.Cm off . 191Used together with the 192.Xr moused 8 193daemon for text mode cut & paste functionality. 194.It Fl p 195Capture the current contents of the video buffer corresponding 196to the terminal device referred to by standard input. 197.Nm 198writes contents of the video buffer to the standard 199output in a raw binary format. 200For details about that 201format see 202.Sx Format of Video Buffer Dump 203below. 204.It Fl P 205Same as 206.Fl p , 207but dump contents of the video buffer in a plain text format 208ignoring nonprintable characters and information about text 209attributes. 210.It Fl r Ar foreground background 211Change reverse mode colors to 212.Ar foreground 213and 214.Ar background . 215.It Fl s Ar number 216Set the current vty to 217.Ar number . 218.It Fl t Ar N | Cm off 219Set the screensaver timeout to 220.Ar N 221seconds, or turns it 222.Cm off . 223.It Fl x 224Use hexadecimal digits for output. 225.El 226.Ss Video Mode Support 227Note that not all modes listed above may be supported by the video 228hardware. 229You can verify which mode is supported by the video hardware, using the 230.Fl i Cm mode 231option. 232.Pp 233The VESA BIOS support must be linked to the kernel 234or loaded as a KLD module if you wish to use VESA video modes 235or 132 column modes 236.Pq see Xr vga 4 . 237.Pp 238You need to compile your kernel with the 239.Ar VGA_WIDTH90 240option if you wish to use VGA 90 column modes 241.Pq see Xr vga 4 . 242.Pp 243Video modes other than 25 and 30 line modes may require specific size of font. 244Use 245.Fl f 246option above to load a font file to the kernel. 247If the required size of font has not been loaded to the kernel, 248.Nm 249will fail if the user attempts to set a new video mode. 250.Pp 251.Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact 252.Sy Modes Ta Sy Font size 253.Li 25 line modes Ta 8x16 (VGA), 8x14 (EGA) 254.Li 30 line modes Ta 8x16 255.Li 43 line modes Ta 8x8 256.Li 50 line modes Ta 8x8 257.Li 60 line modes Ta 8x8 258.El 259.Pp 260It is better to always load all three sizes (8x8, 8x14 and 8x16) 261of the same font. 262.Pp 263You may set variables in 264.Pa /etc/rc.conf 265or 266.Pa /etc/rc.conf.local 267so that desired font files will be automatically loaded 268when the system starts up. 269See below. 270.Pp 271If you want to use the raster text mode 272.Ar VESA_800x600 , 273you need to recompile your kernel with the 274.Dv SC_PIXEL_MODE 275option. 276See 277.Xr syscons 4 278for more details on this kernel option. 279.Ss Format of Video Buffer Dump 280The 281.Nm 282utility uses the 283.Xr syscons 4 284.Dv CONS_SCRSHOT 285.Xr ioctl 2 286to capture the current contents of the video buffer. 287.Nm 288writes version and additional information to the standard 289output, followed by the contents of the terminal device. 290.Pp 291PC video memory is typically arranged in two byte tuples, 292one per character position. 293In each tuple, the first byte 294will be the character code, and the second byte is the 295character's color attribute. 296.Pp 297The color attribute byte is further broken down in to the 298low nibble, which specifies which of 16 different foreground 299colors is active, and the high nibble, which specifies which 300of 16 different background colors is active. 301.Pp 302.Bl -hang -offset indent -compact 303.It 0 304Black 305.It 1 306Blue 307.It 2 308Green 309.It 3 310Cyan 311.It 4 312Red 313.It 5 314Magenta 315.It 6 316Brown 317.It 7 318White 319.It 8 320Grey 321.It 9 322Light Blue 323.It 10 324Light Green 325.It 11 326Light Cyan 327.It 12 328Light Red 329.It 13 330Light Magenta 331.It 14 332Yellow 333.It 15 334White 335.El 336.Pp 337It can be seen that the last 8 colors are brighter 338versions of the first 8. 339.Pp 340For example, the two bytes 341.Pp 342.Dl "65 158" 343.Pp 344specify an uppercase A (character code 65), in 345yellow (low nibble 15) on a light blue background 346(high nibble 9). 347.Pp 348The 349.Nm 350output contains a small header which includes additional 351information which may be useful to utilities processing 352the output. 353.Pp 354The first 10 bytes are always arranged as follows: 355.Bl -column "Byte range" "Contents" -offset indent 356.It Sy "Byte Range Contents" 357.It "1 thru 8 Literal text" Dq Li SCRSHOT_ 358.It "9 File format version number" 359.It "10 Remaining number of bytes in the header" 360.El 361.Pp 362Subsequent bytes depend on the version number. 363.Bl -column "Version" "13 and up" -offset indent 364.It Sy "Version Byte Meaning" 365.It "1 11 Terminal width, in characters" 366.It " 12 Terminal depth, in characters" 367.It " 13 and up The snapshot data" 368.El 369.Pp 370So a dump of an 80x25 screen would start (in hex) 371.Bd -literal -offset indent 37253 43 52 53 48 4f 54 5f 01 02 50 19 373----------------------- -- -- -- -- 374 | | | | ` 25 decimal 375 | | | `--- 80 decimal 376 | | `------ 2 remaining bytes of header data 377 | `--------- File format version 1 378 `------------------------ Literal "SCRSHOT_" 379.Ed 380.Sh VIDEO OUTPUT CONFIGURATION 381.Ss Boot Time Configuration 382You may set the following variables in 383.Pa /etc/rc.conf 384or 385.Pa /etc/rc.conf.local 386in order to configure the video output at boot time. 387.Pp 388.Bl -tag -width foo_bar_var -compact 389.It Ar blanktime 390Sets the timeout value for the 391.Fl t 392option. 393.It Ar font8x16 , font8x14 , font8x8 394Specifies font files for the 395.Fl f 396option. 397.It Ar scrnmap 398Specifies a screen output map file for the 399.Fl l 400option. 401.El 402.Pp 403See 404.Xr rc.conf 5 405for more details. 406.Ss Driver Configuration 407The video card driver may let you change default configuration 408options, such as the default font, so that you do not need to set up 409the options at boot time. 410See video card driver manuals, (e.g.\& 411.Xr vga 4 ) 412for details. 413.Sh FILES 414.Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact 415.It Pa /usr/share/syscons/fonts/* 416font files. 417.It Pa /usr/share/syscons/scrnmaps/* 418screen output map files. 419.El 420.Sh EXAMPLES 421If you want to load 422.Pa /usr/share/syscons/fonts/iso-8x16.fnt 423to the kernel, run 424.Nm 425as: 426.Pp 427.Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt 428.Pp 429So long as the font file is in 430.Pa /usr/share/syscons/fonts , 431you may abbreviate the file name as 432.Pa iso-8x16 : 433.Pp 434.Dl vidcontrol -f 8x16 iso-8x16 435.Pp 436Furthermore, you can also omit font size 437.Dq Li 8x16 : 438.Pp 439.Dl vidcontrol -f iso-8x16 440.Pp 441Likewise, you can also abbreviate the screen output map file name for 442the 443.Fl l 444option if the file is found in 445.Pa /usr/share/syscons/scrnmaps . 446.Pp 447.Dl vidcontrol -l iso-8859-1_to_cp437 448.Pp 449The above command will load 450.Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm . 451.Pp 452The following command will set-up a 100x37 raster text mode (useful for 453some LCD models): 454.Pp 455.Dl vidcontrol -g 100x37 VESA_800x600 456.Pp 457The following command will capture the contents of the first virtual 458terminal, and redirect the output to the 459.Pa shot.scr 460file: 461.Pp 462.Dl vidcontrol -p < /dev/ttyv0 > shot.scr 463.Pp 464The following command will dump contents of the forth virtual terminal 465to the standard output in the human readable format: 466.Pp 467.Dl vidcontrol -P < /dev/ttyv3 468.Sh SEE ALSO 469.Xr kbdcontrol 1 , 470.Xr vidfont 1 , 471.Xr keyboard 4 , 472.Xr screen 4 , 473.Xr syscons 4 , 474.Xr vga 4 , 475.Xr rc.conf 5 , 476.Xr kldload 8 , 477.Xr moused 8 , 478.Xr watch 8 479.Pp 480The various 481.Li shot2* 482utilities in the 483.Li textproc 484category of the 485.Em "Ports Collection" . 486.Sh AUTHORS 487.An S\(/oren Schmidt Aq sos@FreeBSD.org 488.Sh CONTRIBUTORS 489.An Maxim Sobolev Aq sobomax@FreeBSD.org , 490.An Nik Clayton Aq nik@FreeBSD.org 491