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