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 April 6, 2022
  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 Supported only with
 392 .Xr syscons 4 .
 393 .It Fl P
 394 Same as
 395 .Fl p ,
 396 but dump contents of the video buffer in a plain text format
 397 ignoring nonprintable characters and information about text
 398 attributes.
 399 Supported only with
 400 .Xr syscons 4 .
 401 .It Fl H
 402 When used with
 403 .Fl p
 404 or
 405 .Fl P ,
 406 it instructs
 407 .Nm
 408 to dump full history buffer instead of visible portion of
 409 the video buffer only.
 410 .It Fl r Ar foreground background
 411 Change reverse mode colors to
 412 .Ar foreground
 413 and
 414 .Ar background .
 415 .It Fl S Cm on | off
 416 Turn vty switching on or off.
 417 When vty switching is off,
 418 attempts to switch to a different virtual terminal will fail.
 419 (The default is to permit vty switching.)
 420 This protection can be easily bypassed when the kernel is compiled with
 421 the
 422 .Dv DDB
 423 option.
 424 However, you probably should not compile the kernel debugger on a box which
 425 is supposed to be physically secure.
 426 .It Fl s Ar number
 427 Set the active vty to
 428 .Ar number .
 429 .It Fl T Cm xterm | cons25
 430 Switch between xterm and cons25 style terminal emulation.
 431 .It Fl t Ar N | Cm off
 432 Set the screensaver timeout to
 433 .Ar N
 434 seconds, or turns it
 435 .Cm off .
 436 .It Fl x
 437 Use hexadecimal digits for output.
 438 .El
 439 .Ss Video Mode Support
 440 Note that not all modes listed above may be supported by the video
 441 hardware.
 442 You can verify which mode is supported by the video hardware, using the
 443 .Fl i Cm mode
 444 option.
 445 .Pp
 446 The VESA BIOS support must be linked to the kernel
 447 or loaded as a KLD module if you wish to use VESA video modes
 448 or 132 column modes
 449 (see
 450 .Xr vga 4 ) .
 451 .Pp
 452 You need to compile your kernel with the
 453 .Ar VGA_WIDTH90
 454 option if you wish to use VGA 90 column modes
 455 (see
 456 .Xr vga 4 ) .
 457 .Pp
 458 Video modes other than 25 and 30 line modes may require specific size of font.
 459 Use
 460 .Fl f
 461 option above to load a font file to the kernel.
 462 If the required size of font has not been loaded to the kernel,
 463 .Nm
 464 will fail if the user attempts to set a new video mode.
 465 .Pp
 466 .Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact
 467 .Sy Modes Ta Sy Font size
 468 .No 25 line modes Ta 8x16 (VGA), 8x14 (EGA)
 469 .No 30 line modes Ta 8x16
 470 .No 43 line modes Ta 8x8
 471 .No 50 line modes Ta 8x8
 472 .No 60 line modes Ta 8x8
 473 .El
 474 .Pp
 475 It is better to always load all three sizes (8x8, 8x14 and 8x16)
 476 of the same font.
 477 .Pp
 478 You may set variables in
 479 .Pa /etc/rc.conf
 480 or
 481 .Pa /etc/rc.conf.local
 482 so that desired font files will be automatically loaded
 483 when the system starts up.
 484 See below.
 485 .Pp
 486 If you want to use any of the raster text modes you need to recompile your
 487 kernel with the
 488 .Dv SC_PIXEL_MODE
 489 option.
 490 See
 491 .Xr syscons 4
 492 or
 493 .Xr vt 4
 494 (depending on which driver you use)
 495 for more details on this kernel option.
 496 .Ss Format of Video Buffer Dump
 497 The
 498 .Nm
 499 utility uses the
 500 .Xr syscons 4
 501 .\" is it supported on vt(4)???
 502 or
 503 .Xr vt 4
 504 .Dv CONS_SCRSHOT
 505 .Xr ioctl 2
 506 to capture the current contents of the video buffer.
 507 The
 508 .Nm
 509 utility writes version and additional information to the standard
 510 output, followed by the contents of the video buffer.
 511 .Pp
 512 VGA video memory is typically arranged in two byte tuples,
 513 one per character position.
 514 In each tuple, the first byte will be the character code,
 515 and the second byte is the character's color attribute.
 516 .Pp
 517 The VGA color attribute byte looks like this:
 518 .Bl -column "X:X" "<00000000>" "width" "bright foreground color"
 519 .Sy "bits#              width   meaning"
 520 .Li "7  <X0000000>      1       character blinking"
 521 .Li "6:4        <0XXX0000>      3       background color"
 522 .Li "3  <0000X000>      1       bright foreground color"
 523 .Li "2:0        <00000XXX>      3       foreground color"
 524 .El
 525 .Pp
 526 Here is a list of the three bit wide base colors:
 527 .Pp
 528 .Bl -hang -offset indent -compact
 529 .It 0
 530 Black
 531 .It 1
 532 Blue
 533 .It 2
 534 Green
 535 .It 3
 536 Cyan
 537 .It 4
 538 Red
 539 .It 5
 540 Magenta
 541 .It 6
 542 Brown
 543 .It 7
 544 Light Grey
 545 .El
 546 .Pp
 547 Base colors with bit 3 (the bright foreground flag) set:
 548 .Pp
 549 .Bl -hang -offset indent -compact
 550 .It 0
 551 Dark Grey
 552 .It 1
 553 Light Blue
 554 .It 2
 555 Light Green
 556 .It 3
 557 Light Cyan
 558 .It 4
 559 Light Red
 560 .It 5
 561 Light Magenta
 562 .It 6
 563 Yellow
 564 .It 7
 565 White
 566 .El
 567 .Pp
 568 For example, the two bytes
 569 .Pp
 570 .Dl "65 158"
 571 .Pp
 572 specify an uppercase A (character code 65), blinking
 573 (bit 7 set) in yellow (bits 3:0) on a blue background
 574 (bits 6:4).
 575 .Pp
 576 The
 577 .Nm
 578 output contains a small header which includes additional
 579 information which may be useful to utilities processing
 580 the output.
 581 .Pp
 582 The first 10 bytes are always arranged as follows:
 583 .Bl -column "Byte range" "Contents" -offset indent
 584 .It Sy "Byte Range      Contents"
 585 .It "1 - 8      Literal text" Dq Li SCRSHOT_
 586 .It "9  File format version number"
 587 .It "10 Remaining number of bytes in the header"
 588 .El
 589 .Pp
 590 Subsequent bytes depend on the version number.
 591 .Bl -column "Version" "13 and up" -offset indent
 592 .It Sy "Version Byte    Meaning"
 593 .It "1  11      Terminal width, in characters"
 594 .It "   12      Terminal depth, in characters"
 595 .It "   13 and up       The snapshot data"
 596 .El
 597 .Pp
 598 So a dump of an 80x25 screen would start (in hex)
 599 .Bd -literal -offset indent
 600 53 43 52 53 48 4f 54 5f 01 02 50 19
 601 ----------------------- -- -- -- --
 602           |              |  |  |  ` 25 decimal
 603           |              |  |  `--- 80 decimal
 604           |              |  `------ 2 remaining bytes of header data
 605           |              `--------- File format version 1
 606           `------------------------ Literal "SCRSHOT_"
 607 .Ed
 608 .Sh VIDEO OUTPUT CONFIGURATION
 609 .Ss Boot Time Configuration
 610 You may set the following variables in
 611 .Pa /etc/rc.conf
 612 or
 613 .Pa /etc/rc.conf.local
 614 in order to configure the video output at boot time.
 615 .Pp
 616 .Bl -tag -width foo_bar_var -compact
 617 .It Ar blanktime
 618 Sets the timeout value for the
 619 .Fl t
 620 option.
 621 .It Ar font8x16 , font8x14 , font8x8
 622 Specifies font files for the
 623 .Fl f
 624 option.
 625 .It Ar scrnmap
 626 Specifies a screen output map file for the
 627 .Fl l
 628 option.
 629 .El
 630 .Pp
 631 See
 632 .Xr rc.conf 5
 633 for more details.
 634 .Ss Driver Configuration
 635 The video card driver may let you change default configuration
 636 options, such as the default font, so that you do not need to set up
 637 the options at boot time.
 638 See video card driver manuals, (e.g.,
 639 .Xr vga 4 )
 640 for details.
 641 .Sh FILES
 642 .Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact
 643 .It Pa /usr/share/syscons/fonts/*
 644 .It Pa /usr/share/vt/fonts/*
 645 font files.
 646 .It Pa /usr/share/syscons/scrnmaps/*
 647 screen output map files (relevant for
 648 .Xr syscons 4
 649 only).
 650 .El
 651 .Sh EXAMPLES
 652 If you want to load
 653 .Pa /usr/share/syscons/fonts/iso-8x16.fnt
 654 to the kernel, run
 655 .Nm
 656 as:
 657 .Pp
 658 .Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt
 659 .Pp
 660 So long as the font file is in
 661 .Pa /usr/share/syscons/fonts
 662 (if using syscons) or
 663 .Pa /usr/share/vt/fonts
 664 (if using vt),
 665 you may abbreviate the file name as
 666 .Pa iso-8x16 :
 667 .Pp
 668 .Dl vidcontrol -f 8x16 iso-8x16
 669 .Pp
 670 Furthermore, you can also omit font size
 671 .Dq Li 8x16 :
 672 .Pp
 673 .Dl vidcontrol -f iso-8x16
 674 .Pp
 675 Moreover, the suffix specifying the font size can also be omitted; in
 676 this case,
 677 .Nm
 678 will use the size of the currently displayed font to construct the
 679 suffix:
 680 .Pp
 681 .Dl vidcontrol -f iso
 682 .Pp
 683 Likewise, you can also abbreviate the screen output map file name for
 684 the
 685 .Fl l
 686 option if the file is found in
 687 .Pa /usr/share/syscons/scrnmaps .
 688 .Pp
 689 .Dl vidcontrol -l iso-8859-1_to_cp437
 690 .Pp
 691 The above command will load
 692 .Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm .
 693 .Pp
 694 The following command will set-up a 100x37 raster text mode (useful for
 695 some LCD models):
 696 .Pp
 697 .Dl vidcontrol -g 100x37 VESA_800x600
 698 .Pp
 699 The following command will capture the contents of the first virtual
 700 terminal video buffer, and redirect the output to the
 701 .Pa shot.scr
 702 file:
 703 .Pp
 704 .Dl vidcontrol -p < /dev/ttyv0 > shot.scr
 705 .Pp
 706 The following command will dump contents of the fourth virtual terminal
 707 video buffer
 708 to the standard output in the human readable format:
 709 .Pp
 710 .Dl vidcontrol -P < /dev/ttyv3
 711 .Sh SEE ALSO
 712 .Xr kbdcontrol 1 ,
 713 .Xr vidfont 1 ,
 714 .Xr keyboard 4 ,
 715 .Xr screen 4 ,
 716 .Xr syscons 4 ,
 717 .Xr vga 4 ,
 718 .Xr vt 4 ,
 719 .Xr rc.conf 5 ,
 720 .Xr kldload 8 ,
 721 .Xr moused 8 ,
 722 .Xr watch 8
 723 .Pp
 724 The various
 725 .Pa scr2*
 726 utilities in the
 727 .Pa graphics
 728 and
 729 .Pa textproc
 730 categories of the
 731 .Em "Ports Collection" .
 732 .Sh AUTHORS
 733 .An S\(/oren Schmidt Aq Mt sos@FreeBSD.org
 734 .An Sascha Wildner Aq Mt saw@online.de
 735 .Sh CONTRIBUTORS
 736 .An -split
 737 .An Maxim Sobolev Aq Mt sobomax@FreeBSD.org
 738 .An Nik Clayton Aq Mt nik@FreeBSD.org