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