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