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