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.4 2005/07/14 20:44:32 swildner 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 154See also 155.Sx Video Mode Support 156and 157.Sx EXAMPLES 158below and the man page for 159.Xr syscons 4 . 160.It Fl g Ar geometry 161Set the 162.Ar geometry 163of the text mode for the modes with selectable 164geometry. 165Currently only raster modes, such as 166.Ar VESA_800x600 , 167support this option. 168See also 169.Sx Video Mode Support 170and 171.Sx EXAMPLES 172below. 173.It Fl h Ar size 174Set the size of the history (scrollback) buffer to 175.Ar size 176lines. 177.It Fl i Cm adapter 178Shows info about the current video adapter. 179.It Fl i Cm mode 180Shows the possible video modes with the current video hardware. 181.It Fl l Ar screen_map 182Install screen output map file from 183.Ar screen_map . 184See also 185.Xr syscons 4 . 186.It Fl L 187Install default screen output map. 188.It Fl M Ar char 189Sets the base character used to render the mouse pointer to 190.Ar char . 191.It Fl m Cm on | off 192Switch the mouse pointer 193.Cm on 194or 195.Cm off . 196Used together with the 197.Xr moused 8 198daemon for text mode cut & paste functionality. 199.It Fl p 200Capture the current contents of the video buffer corresponding 201to the terminal device referred to by standard input. 202The 203.Nm 204utility writes contents of the video buffer to the standard 205output in a raw binary format. 206For details about that 207format see 208.Sx Format of Video Buffer Dump 209below. 210.It Fl P 211Same as 212.Fl p , 213but dump contents of the video buffer in a plain text format 214ignoring nonprintable characters and information about text 215attributes. 216.It Fl r Ar foreground background 217Change reverse mode colors to 218.Ar foreground 219and 220.Ar background . 221.It Fl S Cm on | off 222Turn vty switching on or off. 223When vty switching is off, 224attempts to switch to a different virtual terminal will fail. 225(The default is to permit vty switching.) 226.It Fl s Ar number 227Set the current vty to 228.Ar number . 229.It Fl t Ar N | Cm off 230Set the screensaver timeout to 231.Ar N 232seconds, or turns it 233.Cm off . 234.It Fl x 235Use hexadecimal digits for output. 236.El 237.Ss Video Mode Support 238Note that not all modes listed above may be supported by the video 239hardware. 240You can verify which mode is supported by the video hardware, using the 241.Fl i Cm mode 242option. 243.Pp 244The VESA BIOS support must be linked to the kernel 245or loaded as a KLD module if you wish to use VESA video modes 246or 132 column modes 247(see 248.Xr vga 4 ) . 249.Pp 250You need to compile your kernel with the 251.Ar VGA_WIDTH90 252option if you wish to use VGA 90 column modes 253(see 254.Xr vga 4 ) . 255.Pp 256Video modes other than 25 and 30 line modes may require specific size of font. 257Use 258.Fl f 259option above to load a font file to the kernel. 260If the required size of font has not been loaded to the kernel, 261.Nm 262will fail if the user attempts to set a new video mode. 263.Pp 264.Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact 265.Sy Modes Ta Sy Font size 266.Li 25 line modes Ta 8x16 (VGA), 8x14 (EGA) 267.Li 30 line modes Ta 8x16 268.Li 43 line modes Ta 8x8 269.Li 50 line modes Ta 8x8 270.Li 60 line modes Ta 8x8 271.El 272.Pp 273It is better to always load all three sizes (8x8, 8x14 and 8x16) 274of the same font. 275.Pp 276You may set variables in 277.Pa /etc/rc.conf 278or 279.Pa /etc/rc.conf.local 280so that desired font files will be automatically loaded 281when the system starts up. 282See below. 283.Pp 284If you want to use any of the raster text modes you need to recompile your 285kernel with the 286.Dv SC_PIXEL_MODE 287option. 288See 289.Xr syscons 4 290for more details on this kernel option. 291.Ss Format of Video Buffer Dump 292The 293.Nm 294utility uses the 295.Xr syscons 4 296.Dv CONS_SCRSHOT 297.Xr ioctl 2 298to capture the current contents of the video buffer. 299The 300.Nm 301utility writes version and additional information to the standard 302output, followed by the contents of the terminal device. 303.Pp 304PC video memory is typically arranged in two byte tuples, 305one per character position. 306In each tuple, the first byte 307will be the character code, and the second byte is the 308character's color attribute. 309.Pp 310The color attribute byte is further broken down in to the 311low nibble, which specifies which of 16 different foreground 312colors is active, and the high nibble, which specifies which 313of 16 different background colors is active. 314.Pp 315.Bl -hang -offset indent -compact 316.It 0 317Black 318.It 1 319Blue 320.It 2 321Green 322.It 3 323Cyan 324.It 4 325Red 326.It 5 327Magenta 328.It 6 329Brown 330.It 7 331White 332.It 8 333Grey 334.It 9 335Light Blue 336.It 10 337Light Green 338.It 11 339Light Cyan 340.It 12 341Light Red 342.It 13 343Light Magenta 344.It 14 345Yellow 346.It 15 347White 348.El 349.Pp 350It can be seen that the last 8 colors are brighter 351versions of the first 8. 352.Pp 353For example, the two bytes 354.Pp 355.Dl "65 158" 356.Pp 357specify an uppercase A (character code 65), in 358yellow (low nibble 15) on a light blue background 359(high nibble 9). 360.Pp 361The 362.Nm 363output contains a small header which includes additional 364information which may be useful to utilities processing 365the output. 366.Pp 367The first 10 bytes are always arranged as follows: 368.Bl -column "Byte range" "Contents" -offset indent 369.It Sy "Byte Range Contents" 370.It "1 thru 8 Literal text" Dq Li SCRSHOT_ 371.It "9 File format version number" 372.It "10 Remaining number of bytes in the header" 373.El 374.Pp 375Subsequent bytes depend on the version number. 376.Bl -column "Version" "13 and up" -offset indent 377.It Sy "Version Byte Meaning" 378.It "1 11 Terminal width, in characters" 379.It " 12 Terminal depth, in characters" 380.It " 13 and up The snapshot data" 381.El 382.Pp 383So a dump of an 80x25 screen would start (in hex) 384.Bd -literal -offset indent 38553 43 52 53 48 4f 54 5f 01 02 50 19 386----------------------- -- -- -- -- 387 | | | | ` 25 decimal 388 | | | `--- 80 decimal 389 | | `------ 2 remaining bytes of header data 390 | `--------- File format version 1 391 `------------------------ Literal "SCRSHOT_" 392.Ed 393.Sh VIDEO OUTPUT CONFIGURATION 394.Ss Boot Time Configuration 395You may set the following variables in 396.Pa /etc/rc.conf 397or 398.Pa /etc/rc.conf.local 399in order to configure the video output at boot time. 400.Pp 401.Bl -tag -width foo_bar_var -compact 402.It Ar blanktime 403Sets the timeout value for the 404.Fl t 405option. 406.It Ar font8x16 , font8x14 , font8x8 407Specifies font files for the 408.Fl f 409option. 410.It Ar scrnmap 411Specifies a screen output map file for the 412.Fl l 413option. 414.El 415.Pp 416See 417.Xr rc.conf 5 418for more details. 419.Ss Driver Configuration 420The video card driver may let you change default configuration 421options, such as the default font, so that you do not need to set up 422the options at boot time. 423See video card driver manuals, (e.g.\& 424.Xr vga 4 ) 425for details. 426.Sh FILES 427.Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact 428.It Pa /usr/share/syscons/fonts/* 429font files. 430.It Pa /usr/share/syscons/scrnmaps/* 431screen output map files. 432.El 433.Sh EXAMPLES 434If you want to load 435.Pa /usr/share/syscons/fonts/iso-8x16.fnt 436to the kernel, run 437.Nm 438as: 439.Pp 440.Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt 441.Pp 442So long as the font file is in 443.Pa /usr/share/syscons/fonts , 444you may abbreviate the file name as 445.Pa iso-8x16 : 446.Pp 447.Dl vidcontrol -f 8x16 iso-8x16 448.Pp 449Furthermore, you can also omit font size 450.Dq Li 8x16 : 451.Pp 452.Dl vidcontrol -f iso-8x16 453.Pp 454Moreover, the suffix specifying the font size can be also omitted; in 455this case, 456.Nm 457will use the size of the currently displayed font to construct the 458suffix: 459.Pp 460.Dl vidcontrol -f iso 461.Pp 462Likewise, you can also abbreviate the screen output map file name for 463the 464.Fl l 465option if the file is found in 466.Pa /usr/share/syscons/scrnmaps . 467.Pp 468.Dl vidcontrol -l iso-8859-1_to_cp437 469.Pp 470The above command will load 471.Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm . 472.Pp 473The following command will set-up a 100x37 raster text mode (useful for 474some LCD models): 475.Pp 476.Dl vidcontrol -g 100x37 VESA_800x600 477.Pp 478The following command will capture the contents of the first virtual 479terminal, and redirect the output to the 480.Pa shot.scr 481file: 482.Pp 483.Dl vidcontrol -p < /dev/ttyv0 > shot.scr 484.Pp 485The following command will dump contents of the fourth virtual terminal 486to the standard output in the human readable format: 487.Pp 488.Dl vidcontrol -P < /dev/ttyv3 489.Sh SEE ALSO 490.Xr kbdcontrol 1 , 491.Xr vidfont 1 , 492.Xr keyboard 4 , 493.Xr screen 4 , 494.Xr syscons 4 , 495.Xr vga 4 , 496.Xr rc.conf 5 , 497.Xr kldload 8 , 498.Xr moused 8 , 499.Xr watch 8 500.Pp 501The various 502.Li scr2* 503utilities in the 504.Li graphics 505and 506.Li textproc 507categories of the 508.Em "Ports Collection" . 509.Sh AUTHORS 510.An S\(/oren Schmidt Aq sos@FreeBSD.org 511.An Sascha Wildner 512