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 October 20, 2018
  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 CdHLPpx
  25 .Op Fl b Ar color
  26 .Op Fl c Ar appearance
  27 .Op Fl E Ar emulator
  28 .Oo
  29 .Fl f
  30 .Oo
  31 .Op Ar size
  32 .Ar file
  33 .Oc
  34 .Oc
  35 .Op Fl g Ar geometry
  36 .Op Fl h Ar size
  37 .Op Fl i Cm active | adapter | mode
  38 .Op Fl l Ar screen_map
  39 .Op Fl M Ar char
  40 .Op Fl m Cm on | off
  41 .Op Fl r Ar foreground Ar background
  42 .Op Fl S Cm on | off
  43 .Op Fl s Ar number
  44 .Op Fl T Cm xterm | cons25
  45 .Op Fl t Ar N | Cm off
  46 .Op Ar mode
  47 .Op Ar foreground Op Ar background
  48 .Op Cm show
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 utility is used to set various options for the
  53 .Xr syscons 4
  54 or
  55 .Xr vt 4
  56 console driver,
  57 such as video mode, colors, cursor shape, screen output map, font, and screen
  58 saver timeout.
  59 Only a small subset of options is supported by
  60 .Xr vt 4 .
  61 Unsupported options lead to error messages, typically including
  62 the text "Inappropriate ioctl for device".
  63 .Pp
  64 The following command line options are supported:
  65 .Bl -tag -width indent
  66 .It Ar mode
  67 Select a new video mode.
  68 The modes currently recognized are:
  69 .Ar 80x25 ,
  70 .Ar 80x30 ,
  71 .Ar 80x43 ,
  72 .Ar 80x50 ,
  73 .Ar 80x60 ,
  74 .Ar 132x25 ,
  75 .Ar 132x30 ,
  76 .Ar 132x43 ,
  77 .Ar 132x50 ,
  78 .Ar 132x60 ,
  79 .Ar VGA_40x25 ,
  80 .Ar VGA_80x25 ,
  81 .Ar VGA_80x30 ,
  82 .Ar VGA_80x50 ,
  83 .Ar VGA_80x60 ,
  84 .Ar VGA_90x25 ,
  85 .Ar VGA_90x30 ,
  86 .Ar VGA_90x43 ,
  87 .Ar VGA_90x50 ,
  88 .Ar VGA_90x60 ,
  89 .Ar EGA_80x25 ,
  90 .Ar EGA_80x43 ,
  91 .Ar VESA_132x25 ,
  92 .Ar VESA_132x43 ,
  93 .Ar VESA_132x50 ,
  94 .Ar VESA_132x60 .
  95 .\"The graphic mode
  96 .\".Ar VGA_320x200
  97 .\"and
  98 The raster text mode
  99 .Ar VESA_800x600
 100 can also be chosen.
 101 Alternatively, a mode can be specified with its number by using a mode name of
 102 the form
 103 .Li MODE_ Ns Aq Ar NUMBER .
 104 A list of valid mode numbers can be obtained with the
 105 .Fl i Cm mode
 106 option.
 107 See
 108 .Sx Video Mode Support
 109 below.
 110 .It Ar foreground Op Ar background
 111 Change colors when displaying text.
 112 Specify the foreground color
 113 (e.g.,
 114 .Dq vidcontrol white ) ,
 115 or both a foreground and background colors
 116 (e.g.,
 117 .Dq vidcontrol yellow blue ) .
 118 Use the
 119 .Cm show
 120 command below to see available colors.
 121 .It Cm show
 122 See the supported colors on a given platform.
 123 .It Fl b Ar color
 124 Set border color to
 125 .Ar color .
 126 This option may not be always supported by the video driver.
 127 .It Fl C
 128 Clear the history buffer.
 129 .It Fl c Ar setting Ns Op , Ns Ar setting ...
 130 Change the cursor appearance.
 131 The change is specified by a non-empty comma-separated list of
 132 .Ar setting Ns s .
 133 Each
 134 .Ar setting
 135 overrides or modifies previous ones in left to right order.
 136 .Pp
 137 The following override
 138 .Ar setting Ns s
 139 are available:
 140 .Bl -tag -width indent
 141 .It Cm normal
 142 Set to a block covering 1 character cell,
 143 with a configuration-dependent coloring
 144 that should be at worst inverse video.
 145 .It Cm destructive
 146 Set to a blinking sub-block with
 147 .Cm height
 148 scanlines starting at
 149 .Cm base .
 150 The name
 151 .Dq destructive
 152 is bad for backwards compatibility.
 153 This
 154 .Ar setting
 155 should not force destructiveness,
 156 and it now only gives destructiveness in some
 157 configurations (typically for hardware cursors
 158 in text mode).
 159 Blinking limits destructiveness.
 160 This
 161 .Ar setting
 162 should now be spelled
 163 .Cm normal , Ns Cm blink , Ns Cm noblock .
 164 A non-blinking destructive cursor would be unusable,
 165 so old versions of
 166 .Nm
 167 did not support it,
 168 and this version does not have an override for it.
 169 .It Cm base Ns = Ns Ar value , Cm height Ns = Ns Ar value
 170 Set the specified scanline parameters.
 171 These parameters are only active in
 172 .Cm noblock
 173 mode.
 174 .Cm value
 175 is an integer in any base supported by
 176 .Xr strtol 3 .
 177 Setting
 178 .Cm height
 179 to 0 turns off the cursor in
 180 .Cm noblock
 181 mode.
 182 Negative
 183 .Ar value Ns s
 184 are silently ignored.
 185 Positive
 186 .Ar value Ns s
 187 are clamped to fit in the character cell when the cursor is drawn.
 188 .El
 189 .Pp
 190 The following modifier
 191 .Ar setting Ns s
 192 are available:
 193 .Bl -tag -width indent
 194 .It Cm blink , noblink
 195 Set or clear the blinking attribute.
 196 This is not quite backwards compatible.
 197 In old versions of
 198 .Nm , Cm blink
 199 was an override to a blinking block.
 200 .It Cm block , noblock
 201 Set or clear the
 202 .Cm block
 203 attribute.
 204 This attribute is the inverse of the flag
 205 .Dv CONS_CHAR_CURSOR
 206 in the implementation.
 207 It deactivates the scanline parameters,
 208 and expresses a preference for using a
 209 simpler method of implementation.
 210 Its inverse does the opposite.
 211 When the scanline parameters give a full block,
 212 this attribute reduces to a method selection bit.
 213 The
 214 .Cm block
 215 method tends to give better coloring.
 216 .It Cm hidden , nohidden
 217 Set or clear the hidden attribute.
 218 .El
 219 .Pp
 220 The following (non-sticky) flags control application of the
 221 .Ar setting Ns s :
 222 .Bl -tag -width indent
 223 .It Cm charcolors
 224 Apply
 225 .Cm base
 226 and
 227 .Cm height
 228 to the (character) cursor's list of preferred colors instead of its shape.
 229 Beware that the color numbers are raw VGA palette indexes,
 230 not ANSI color numbers.
 231 The indexes are reduced mod 8, 16 or 256,
 232 or ignored,
 233 depending on the video mode and renderer.
 234 .It Cm mousecolors
 235 Colors for the mouse cursor in graphics mode.
 236 Like
 237 .Cm charcolors ,
 238 except there is no preference or sequence;
 239 .Cm base
 240 gives the mouse border color and
 241 .Cm height
 242 gives the mouse interior color.
 243 Together with
 244 .Cm charcolors ,
 245 this gives 2 selection bits which select between
 246 only 3 of 4 sub-destinations of the 4 destinations selected by
 247 .Cm default
 248 and
 249 .Cm local
 250 (by ignoring
 251 .Cm mousecolors
 252 if
 253 .Cm charcolors
 254 is also set).
 255 .It Cm default
 256 Apply the changes to the default settings and then to the active settings,
 257 instead of only to the active settings.
 258 Together with
 259 .Cm local ,
 260 this gives 2 selection bits which select between 4 destinations.
 261 .It Cm shapeonly
 262 Ignore any changes to the
 263 .Cm block
 264 and
 265 .Cm hidden
 266 attributes.
 267 .It Cm local
 268 Apply the changes to the current vty.
 269 The default is to apply them to a global place
 270 and copy from there to all vtys.
 271 .It Cm reset
 272 Reset everything.
 273 The default is to not reset.
 274 When the
 275 .Cm local
 276 parameter is specified, the current local settings are reset
 277 to default local settings.
 278 Otherwise, the current global settings are reset to default
 279 global settings and then copied to the current and default
 280 settings for all vtys.
 281 .It Cm show
 282 Show the current changes.
 283 .El
 284 .It Fl d
 285 Print out current output screen map.
 286 .It Fl E Ar emulator
 287 Set the terminal emulator to
 288 .Ar emulator .
 289 .It Fl e
 290 Show the active and available terminal emulators.
 291 .It Xo
 292 .Fl f
 293 .Oo
 294 .Op Ar size
 295 .Ar file
 296 .Oc
 297 .Xc
 298 Load font
 299 .Ar file
 300 for
 301 .Ar size
 302 (currently, only
 303 .Cm 8x8 ,
 304 .Cm 8x14
 305 or
 306 .Cm 8x16 ) .
 307 The font file can be either uuencoded or in raw binary format.
 308 You can also use the menu-driven
 309 .Xr vidfont 1
 310 command to load the font of your choice.
 311 .Pp
 312 .Ar Size
 313 may be omitted, in this case
 314 .Nm
 315 will try to guess it from the size of font file.
 316 .Pp
 317 When using
 318 .Xr vt 4
 319 both
 320 .Ar size
 321 and
 322 .Ar file
 323 can be omitted, and the default font will be loaded.
 324 .Pp
 325 Note that older video cards, such as MDA and CGA, do not support
 326 software font.
 327 See also
 328 .Sx Video Mode Support
 329 and
 330 .Sx EXAMPLES
 331 below and the man page for either
 332 .Xr syscons 4
 333 or
 334 .Xr vt 4
 335 (depending on which driver you use).
 336 .It Fl g Ar geometry
 337 Set the
 338 .Ar geometry
 339 of the text mode for the modes with selectable
 340 geometry.
 341 Currently only raster modes, such as
 342 .Ar VESA_800x600 ,
 343 support this option.
 344 See also
 345 .Sx Video Mode Support
 346 and
 347 .Sx EXAMPLES
 348 below.
 349 .It Fl h Ar size
 350 Set the size of the history (scrollback) buffer to
 351 .Ar size
 352 lines.
 353 .It Fl i Cm active
 354 Shows the active vty number.
 355 .It Fl i Cm adapter
 356 Shows info about the current video adapter.
 357 .It Fl i Cm mode
 358 Shows the possible video modes with the current video hardware.
 359 .It Fl l Ar screen_map
 360 Install screen output map file from
 361 .Ar screen_map .
 362 See also
 363 .Xr syscons 4
 364 or
 365 .Xr vt 4
 366 (depending on which driver you use).
 367 .It Fl L
 368 Install default screen output map.
 369 .It Fl M Ar char
 370 Sets the base character used to render the mouse pointer to
 371 .Ar char .
 372 .It Fl m Cm on | off
 373 Switch the mouse pointer
 374 .Cm on
 375 or
 376 .Cm off .
 377 Used together with the
 378 .Xr moused 8
 379 daemon for text mode cut & paste functionality.
 380 .It Fl p
 381 Capture the current contents of the video buffer corresponding
 382 to the terminal device referred to by standard input.
 383 The
 384 .Nm
 385 utility writes contents of the video buffer to the standard
 386 output in a raw binary format.
 387 For details about that
 388 format see
 389 .Sx Format of Video Buffer Dump
 390 below.
 391 .It Fl P
 392 Same as
 393 .Fl p ,
 394 but dump contents of the video buffer in a plain text format
 395 ignoring nonprintable characters and information about text
 396 attributes.
 397 .It Fl H
 398 When used with
 399 .Fl p
 400 or
 401 .Fl P ,
 402 it instructs
 403 .Nm
 404 to dump full history buffer instead of visible portion of
 405 the video buffer only.
 406 .It Fl r Ar foreground background
 407 Change reverse mode colors to
 408 .Ar foreground
 409 and
 410 .Ar background .
 411 .It Fl S Cm on | off
 412 Turn vty switching on or off.
 413 When vty switching is off,
 414 attempts to switch to a different virtual terminal will fail.
 415 (The default is to permit vty switching.)
 416 This protection can be easily bypassed when the kernel is compiled with
 417 the
 418 .Dv DDB
 419 option.
 420 However, you probably should not compile the kernel debugger on a box which
 421 is supposed to be physically secure.
 422 .It Fl s Ar number
 423 Set the active vty to
 424 .Ar number .
 425 .It Fl T Cm xterm | cons25
 426 Switch between xterm and cons25 style terminal emulation.
 427 .It Fl t Ar N | Cm off
 428 Set the screensaver timeout to
 429 .Ar N
 430 seconds, or turns it
 431 .Cm off .
 432 .It Fl x
 433 Use hexadecimal digits for output.
 434 .El
 435 .Ss Video Mode Support
 436 Note that not all modes listed above may be supported by the video
 437 hardware.
 438 You can verify which mode is supported by the video hardware, using the
 439 .Fl i Cm mode
 440 option.
 441 .Pp
 442 The VESA BIOS support must be linked to the kernel
 443 or loaded as a KLD module if you wish to use VESA video modes
 444 or 132 column modes
 445 (see
 446 .Xr vga 4 ) .
 447 .Pp
 448 You need to compile your kernel with the
 449 .Ar VGA_WIDTH90
 450 option if you wish to use VGA 90 column modes
 451 (see
 452 .Xr vga 4 ) .
 453 .Pp
 454 Video modes other than 25 and 30 line modes may require specific size of font.
 455 Use
 456 .Fl f
 457 option above to load a font file to the kernel.
 458 If the required size of font has not been loaded to the kernel,
 459 .Nm
 460 will fail if the user attempts to set a new video mode.
 461 .Pp
 462 .Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact
 463 .Sy Modes Ta Sy Font size
 464 .No 25 line modes Ta 8x16 (VGA), 8x14 (EGA)
 465 .No 30 line modes Ta 8x16
 466 .No 43 line modes Ta 8x8
 467 .No 50 line modes Ta 8x8
 468 .No 60 line modes Ta 8x8
 469 .El
 470 .Pp
 471 It is better to always load all three sizes (8x8, 8x14 and 8x16)
 472 of the same font.
 473 .Pp
 474 You may set variables in
 475 .Pa /etc/rc.conf
 476 or
 477 .Pa /etc/rc.conf.local
 478 so that desired font files will be automatically loaded
 479 when the system starts up.
 480 See below.
 481 .Pp
 482 If you want to use any of the raster text modes you need to recompile your
 483 kernel with the
 484 .Dv SC_PIXEL_MODE
 485 option.
 486 See
 487 .Xr syscons 4
 488 or
 489 .Xr vt 4
 490 (depending on which driver you use)
 491 for more details on this kernel option.
 492 .Ss Format of Video Buffer Dump
 493 The
 494 .Nm
 495 utility uses the
 496 .Xr syscons 4
 497 .\" is it supported on vt(4)???
 498 or
 499 .Xr vt 4
 500 .Dv CONS_SCRSHOT
 501 .Xr ioctl 2
 502 to capture the current contents of the video buffer.
 503 The
 504 .Nm
 505 utility writes version and additional information to the standard
 506 output, followed by the contents of the video buffer.
 507 .Pp
 508 VGA video memory is typically arranged in two byte tuples,
 509 one per character position.
 510 In each tuple, the first byte will be the character code,
 511 and the second byte is the character's color attribute.
 512 .Pp
 513 The VGA color attribute byte looks like this:
 514 .Bl -column "X:X" "<00000000>" "width" "bright foreground color"
 515 .Sy "bits#              width   meaning"
 516 .Li "7  <X0000000>      1       character blinking"
 517 .Li "6:4        <0XXX0000>      3       background color"
 518 .Li "3  <0000X000>      1       bright foreground color"
 519 .Li "2:0        <00000XXX>      3       foreground color"
 520 .El
 521 .Pp
 522 Here is a list of the three bit wide base colors:
 523 .Pp
 524 .Bl -hang -offset indent -compact
 525 .It 0
 526 Black
 527 .It 1
 528 Blue
 529 .It 2
 530 Green
 531 .It 3
 532 Cyan
 533 .It 4
 534 Red
 535 .It 5
 536 Magenta
 537 .It 6
 538 Brown
 539 .It 7
 540 Light Grey
 541 .El
 542 .Pp
 543 Base colors with bit 3 (the bright foreground flag) set:
 544 .Pp
 545 .Bl -hang -offset indent -compact
 546 .It 0
 547 Dark Grey
 548 .It 1
 549 Light Blue
 550 .It 2
 551 Light Green
 552 .It 3
 553 Light Cyan
 554 .It 4
 555 Light Red
 556 .It 5
 557 Light Magenta
 558 .It 6
 559 Yellow
 560 .It 7
 561 White
 562 .El
 563 .Pp
 564 For example, the two bytes
 565 .Pp
 566 .Dl "65 158"
 567 .Pp
 568 specify an uppercase A (character code 65), blinking
 569 (bit 7 set) in yellow (bits 3:0) on a blue background
 570 (bits 6:4).
 571 .Pp
 572 The
 573 .Nm
 574 output contains a small header which includes additional
 575 information which may be useful to utilities processing
 576 the output.
 577 .Pp
 578 The first 10 bytes are always arranged as follows:
 579 .Bl -column "Byte range" "Contents" -offset indent
 580 .It Sy "Byte Range      Contents"
 581 .It "1 - 8      Literal text" Dq Li SCRSHOT_
 582 .It "9  File format version number"
 583 .It "10 Remaining number of bytes in the header"
 584 .El
 585 .Pp
 586 Subsequent bytes depend on the version number.
 587 .Bl -column "Version" "13 and up" -offset indent
 588 .It Sy "Version Byte    Meaning"
 589 .It "1  11      Terminal width, in characters"
 590 .It "   12      Terminal depth, in characters"
 591 .It "   13 and up       The snapshot data"
 592 .El
 593 .Pp
 594 So a dump of an 80x25 screen would start (in hex)
 595 .Bd -literal -offset indent
 596 53 43 52 53 48 4f 54 5f 01 02 50 19
 597 ----------------------- -- -- -- --
 598           |              |  |  |  ` 25 decimal
 599           |              |  |  `--- 80 decimal
 600           |              |  `------ 2 remaining bytes of header data
 601           |              `--------- File format version 1
 602           `------------------------ Literal "SCRSHOT_"
 603 .Ed
 604 .Sh VIDEO OUTPUT CONFIGURATION
 605 .Ss Boot Time Configuration
 606 You may set the following variables in
 607 .Pa /etc/rc.conf
 608 or
 609 .Pa /etc/rc.conf.local
 610 in order to configure the video output at boot time.
 611 .Pp
 612 .Bl -tag -width foo_bar_var -compact
 613 .It Ar blanktime
 614 Sets the timeout value for the
 615 .Fl t
 616 option.
 617 .It Ar font8x16 , font8x14 , font8x8
 618 Specifies font files for the
 619 .Fl f
 620 option.
 621 .It Ar scrnmap
 622 Specifies a screen output map file for the
 623 .Fl l
 624 option.
 625 .El
 626 .Pp
 627 See
 628 .Xr rc.conf 5
 629 for more details.
 630 .Ss Driver Configuration
 631 The video card driver may let you change default configuration
 632 options, such as the default font, so that you do not need to set up
 633 the options at boot time.
 634 See video card driver manuals, (e.g.,
 635 .Xr vga 4 )
 636 for details.
 637 .Sh FILES
 638 .Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact
 639 .It Pa /usr/share/syscons/fonts/*
 640 .It Pa /usr/share/vt/fonts/*
 641 font files.
 642 .It Pa /usr/share/syscons/scrnmaps/*
 643 screen output map files (relevant for
 644 .Xr syscons 4
 645 only).
 646 .El
 647 .Sh EXAMPLES
 648 If you want to load
 649 .Pa /usr/share/syscons/fonts/iso-8x16.fnt
 650 to the kernel, run
 651 .Nm
 652 as:
 653 .Pp
 654 .Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt
 655 .Pp
 656 So long as the font file is in
 657 .Pa /usr/share/syscons/fonts
 658 (if using syscons) or
 659 .Pa /usr/share/vt/fonts
 660 (if using vt),
 661 you may abbreviate the file name as
 662 .Pa iso-8x16 :
 663 .Pp
 664 .Dl vidcontrol -f 8x16 iso-8x16
 665 .Pp
 666 Furthermore, you can also omit font size
 667 .Dq Li 8x16 :
 668 .Pp
 669 .Dl vidcontrol -f iso-8x16
 670 .Pp
 671 Moreover, the suffix specifying the font size can also be omitted; in
 672 this case,
 673 .Nm
 674 will use the size of the currently displayed font to construct the
 675 suffix:
 676 .Pp
 677 .Dl vidcontrol -f iso
 678 .Pp
 679 Likewise, you can also abbreviate the screen output map file name for
 680 the
 681 .Fl l
 682 option if the file is found in
 683 .Pa /usr/share/syscons/scrnmaps .
 684 .Pp
 685 .Dl vidcontrol -l iso-8859-1_to_cp437
 686 .Pp
 687 The above command will load
 688 .Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm .
 689 .Pp
 690 The following command will set-up a 100x37 raster text mode (useful for
 691 some LCD models):
 692 .Pp
 693 .Dl vidcontrol -g 100x37 VESA_800x600
 694 .Pp
 695 The following command will capture the contents of the first virtual
 696 terminal video buffer, and redirect the output to the
 697 .Pa shot.scr
 698 file:
 699 .Pp
 700 .Dl vidcontrol -p < /dev/ttyv0 > shot.scr
 701 .Pp
 702 The following command will dump contents of the fourth virtual terminal
 703 video buffer
 704 to the standard output in the human readable format:
 705 .Pp
 706 .Dl vidcontrol -P < /dev/ttyv3
 707 .Sh SEE ALSO
 708 .Xr kbdcontrol 1 ,
 709 .Xr vidfont 1 ,
 710 .Xr keyboard 4 ,
 711 .Xr screen 4 ,
 712 .Xr syscons 4 ,
 713 .Xr vga 4 ,
 714 .Xr vt 4 ,
 715 .Xr rc.conf 5 ,
 716 .Xr kldload 8 ,
 717 .Xr moused 8 ,
 718 .Xr watch 8
 719 .Pp
 720 The various
 721 .Pa scr2*
 722 utilities in the
 723 .Pa graphics
 724 and
 725 .Pa textproc
 726 categories of the
 727 .Em "Ports Collection" .
 728 .Sh AUTHORS
 729 .An S\(/oren Schmidt Aq Mt sos@FreeBSD.org
 730 .An Sascha Wildner Aq Mt saw@online.de
 731 .Sh CONTRIBUTORS
 732 .An -split
 733 .An Maxim Sobolev Aq Mt sobomax@FreeBSD.org
 734 .An Nik Clayton Aq Mt nik@FreeBSD.org