usr.sbin/vidcontrol/vidcontrol.1

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