usr.sbin/vidcontrol/vidcontrol.1

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