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 January 19, 2016
  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 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 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 active
 202 Shows the active vty number.
 203 .It Fl i Cm adapter
 204 Shows info about the current video adapter.
 205 .It Fl i Cm mode
 206 Shows the possible video modes with the current video hardware.
 207 .It Fl l Ar screen_map
 208 Install screen output map file from
 209 .Ar screen_map .
 210 See also
 211 .Xr syscons 4
 212 or
 213 .Xr vt 4
 214 (depending on which driver you use).
 215 .It Fl L
 216 Install default screen output map.
 217 .It Fl M Ar char
 218 Sets the base character used to render the mouse pointer to
 219 .Ar char .
 220 .It Fl m Cm on | off
 221 Switch the mouse pointer
 222 .Cm on
 223 or
 224 .Cm off .
 225 Used together with the
 226 .Xr moused 8
 227 daemon for text mode cut & paste functionality.
 228 .It Fl p
 229 Capture the current contents of the video buffer corresponding
 230 to the terminal device referred to by standard input.
 231 The
 232 .Nm
 233 utility writes contents of the video buffer to the standard
 234 output in a raw binary format.
 235 For details about that
 236 format see
 237 .Sx Format of Video Buffer Dump
 238 below.
 239 .It Fl P
 240 Same as
 241 .Fl p ,
 242 but dump contents of the video buffer in a plain text format
 243 ignoring nonprintable characters and information about text
 244 attributes.
 245 .It Fl H
 246 When used with
 247 .Fl p
 248 or
 249 .Fl P ,
 250 it instructs
 251 .Nm
 252 to dump full history buffer instead of visible portion of
 253 the video buffer only.
 254 .It Fl r Ar foreground background
 255 Change reverse mode colors to
 256 .Ar foreground
 257 and
 258 .Ar background .
 259 .It Fl S Cm on | off
 260 Turn vty switching on or off.
 261 When vty switching is off,
 262 attempts to switch to a different virtual terminal will fail.
 263 (The default is to permit vty switching.)
 264 This protection can be easily bypassed when the kernel is compiled with
 265 the
 266 .Dv DDB
 267 option.
 268 However, you probably should not compile the kernel debugger on a box which
 269 is supposed to be physically secure.
 270 .It Fl s Ar number
 271 Set the active vty to
 272 .Ar number .
 273 .It Fl T Cm xterm | cons25
 274 Switch between xterm and cons25 style terminal emulation.
 275 .It Fl t Ar N | Cm off
 276 Set the screensaver timeout to
 277 .Ar N
 278 seconds, or turns it
 279 .Cm off .
 280 .It Fl x
 281 Use hexadecimal digits for output.
 282 .El
 283 .Ss Video Mode Support
 284 Note that not all modes listed above may be supported by the video
 285 hardware.
 286 You can verify which mode is supported by the video hardware, using the
 287 .Fl i Cm mode
 288 option.
 289 .Pp
 290 The VESA BIOS support must be linked to the kernel
 291 or loaded as a KLD module if you wish to use VESA video modes
 292 or 132 column modes
 293 (see
 294 .Xr vga 4 ) .
 295 .Pp
 296 You need to compile your kernel with the
 297 .Ar VGA_WIDTH90
 298 option if you wish to use VGA 90 column modes
 299 (see
 300 .Xr vga 4 ) .
 301 .Pp
 302 Video modes other than 25 and 30 line modes may require specific size of font.
 303 Use
 304 .Fl f
 305 option above to load a font file to the kernel.
 306 If the required size of font has not been loaded to the kernel,
 307 .Nm
 308 will fail if the user attempts to set a new video mode.
 309 .Pp
 310 .Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact
 311 .Sy Modes Ta Sy Font size
 312 .No 25 line modes Ta 8x16 (VGA), 8x14 (EGA)
 313 .No 30 line modes Ta 8x16
 314 .No 43 line modes Ta 8x8
 315 .No 50 line modes Ta 8x8
 316 .No 60 line modes Ta 8x8
 317 .El
 318 .Pp
 319 It is better to always load all three sizes (8x8, 8x14 and 8x16)
 320 of the same font.
 321 .Pp
 322 You may set variables in
 323 .Pa /etc/rc.conf
 324 or
 325 .Pa /etc/rc.conf.local
 326 so that desired font files will be automatically loaded
 327 when the system starts up.
 328 See below.
 329 .Pp
 330 If you want to use any of the raster text modes you need to recompile your
 331 kernel with the
 332 .Dv SC_PIXEL_MODE
 333 option.
 334 See
 335 .Xr syscons 4
 336 or
 337 .Xr vt 4
 338 (depending on which driver you use)
 339 for more details on this kernel option.
 340 .Ss Format of Video Buffer Dump
 341 The
 342 .Nm
 343 utility uses the
 344 .Xr syscons 4
 345 .\" is it supported on vt(4)???
 346 or
 347 .Xr vt 4
 348 .Dv CONS_SCRSHOT
 349 .Xr ioctl 2
 350 to capture the current contents of the video buffer.
 351 The
 352 .Nm
 353 utility writes version and additional information to the standard
 354 output, followed by the contents of the video buffer.
 355 .Pp
 356 VGA video memory is typically arranged in two byte tuples,
 357 one per character position.
 358 In each tuple, the first byte will be the character code,
 359 and the second byte is the character's color attribute.
 360 .Pp
 361 The VGA color attribute byte looks like this:
 362 .Bl -column "X:X" "<00000000>" "width" "bright foreground color"
 363 .Sy "bits#              width   meaning"
 364 .Li "7  <X0000000>      1       character blinking"
 365 .Li "6:4        <0XXX0000>      3       background color"
 366 .Li "3  <0000X000>      1       bright foreground color"
 367 .Li "2:0        <00000XXX>      3       foreground color"
 368 .El
 369 .Pp
 370 Here is a list of the three bit wide base colors:
 371 .Pp
 372 .Bl -hang -offset indent -compact
 373 .It 0
 374 Black
 375 .It 1
 376 Blue
 377 .It 2
 378 Green
 379 .It 3
 380 Cyan
 381 .It 4
 382 Red
 383 .It 5
 384 Magenta
 385 .It 6
 386 Brown
 387 .It 7
 388 Light Grey
 389 .El
 390 .Pp
 391 Base colors with bit 3 (the bright foreground flag) set:
 392 .Pp
 393 .Bl -hang -offset indent -compact
 394 .It 0
 395 Dark Grey
 396 .It 1
 397 Light Blue
 398 .It 2
 399 Light Green
 400 .It 3
 401 Light Cyan
 402 .It 4
 403 Light Red
 404 .It 5
 405 Light Magenta
 406 .It 6
 407 Yellow
 408 .It 7
 409 White
 410 .El
 411 .Pp
 412 For example, the two bytes
 413 .Pp
 414 .Dl "65 158"
 415 .Pp
 416 specify an uppercase A (character code 65), blinking
 417 (bit 7 set) in yellow (bits 3:0) on a blue background
 418 (bits 6:4).
 419 .Pp
 420 The
 421 .Nm
 422 output contains a small header which includes additional
 423 information which may be useful to utilities processing
 424 the output.
 425 .Pp
 426 The first 10 bytes are always arranged as follows:
 427 .Bl -column "Byte range" "Contents" -offset indent
 428 .It Sy "Byte Range      Contents"
 429 .It "1 thru 8   Literal text" Dq Li SCRSHOT_
 430 .It "9  File format version number"
 431 .It "10 Remaining number of bytes in the header"
 432 .El
 433 .Pp
 434 Subsequent bytes depend on the version number.
 435 .Bl -column "Version" "13 and up" -offset indent
 436 .It Sy "Version Byte    Meaning"
 437 .It "1  11      Terminal width, in characters"
 438 .It "   12      Terminal depth, in characters"
 439 .It "   13 and up       The snapshot data"
 440 .El
 441 .Pp
 442 So a dump of an 80x25 screen would start (in hex)
 443 .Bd -literal -offset indent
 444 53 43 52 53 48 4f 54 5f 01 02 50 19
 445 ----------------------- -- -- -- --
 446           |              |  |  |  ` 25 decimal
 447           |              |  |  `--- 80 decimal
 448           |              |  `------ 2 remaining bytes of header data
 449           |              `--------- File format version 1
 450           `------------------------ Literal "SCRSHOT_"
 451 .Ed
 452 .Sh VIDEO OUTPUT CONFIGURATION
 453 .Ss Boot Time Configuration
 454 You may set the following variables in
 455 .Pa /etc/rc.conf
 456 or
 457 .Pa /etc/rc.conf.local
 458 in order to configure the video output at boot time.
 459 .Pp
 460 .Bl -tag -width foo_bar_var -compact
 461 .It Ar blanktime
 462 Sets the timeout value for the
 463 .Fl t
 464 option.
 465 .It Ar font8x16 , font8x14 , font8x8
 466 Specifies font files for the
 467 .Fl f
 468 option.
 469 .It Ar scrnmap
 470 Specifies a screen output map file for the
 471 .Fl l
 472 option.
 473 .El
 474 .Pp
 475 See
 476 .Xr rc.conf 5
 477 for more details.
 478 .Ss Driver Configuration
 479 The video card driver may let you change default configuration
 480 options, such as the default font, so that you do not need to set up
 481 the options at boot time.
 482 See video card driver manuals, (e.g.\&
 483 .Xr vga 4 )
 484 for details.
 485 .Sh FILES
 486 .Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact
 487 .It Pa /usr/share/syscons/fonts/*
 488 .It Pa /usr/share/vt/fonts/*
 489 font files.
 490 .It Pa /usr/share/syscons/scrnmaps/*
 491 screen output map files (relevant for
 492 .Xr syscons 4
 493 only).
 494 .El
 495 .Sh EXAMPLES
 496 If you want to load
 497 .Pa /usr/share/syscons/fonts/iso-8x16.fnt
 498 to the kernel, run
 499 .Nm
 500 as:
 501 .Pp
 502 .Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt
 503 .Pp
 504 So long as the font file is in
 505 .Pa /usr/share/syscons/fonts
 506 (if using syscons) or
 507 .Pa /usr/share/vt/fonts
 508 (if using vt),
 509 you may abbreviate the file name as
 510 .Pa iso-8x16 :
 511 .Pp
 512 .Dl vidcontrol -f 8x16 iso-8x16
 513 .Pp
 514 Furthermore, you can also omit font size
 515 .Dq Li 8x16 :
 516 .Pp
 517 .Dl vidcontrol -f iso-8x16
 518 .Pp
 519 Moreover, the suffix specifying the font size can be also omitted; in
 520 this case,
 521 .Nm
 522 will use the size of the currently displayed font to construct the
 523 suffix:
 524 .Pp
 525 .Dl vidcontrol -f iso
 526 .Pp
 527 Likewise, you can also abbreviate the screen output map file name for
 528 the
 529 .Fl l
 530 option if the file is found in
 531 .Pa /usr/share/syscons/scrnmaps .
 532 .Pp
 533 .Dl vidcontrol -l iso-8859-1_to_cp437
 534 .Pp
 535 The above command will load
 536 .Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm .
 537 .Pp
 538 The following command will set-up a 100x37 raster text mode (useful for
 539 some LCD models):
 540 .Pp
 541 .Dl vidcontrol -g 100x37 VESA_800x600
 542 .Pp
 543 The following command will capture the contents of the first virtual
 544 terminal video buffer, and redirect the output to the
 545 .Pa shot.scr
 546 file:
 547 .Pp
 548 .Dl vidcontrol -p < /dev/ttyv0 > shot.scr
 549 .Pp
 550 The following command will dump contents of the fourth virtual terminal
 551 video buffer
 552 to the standard output in the human readable format:
 553 .Pp
 554 .Dl vidcontrol -P < /dev/ttyv3
 555 .Sh SEE ALSO
 556 .Xr kbdcontrol 1 ,
 557 .Xr vidfont 1 ,
 558 .Xr keyboard 4 ,
 559 .Xr screen 4 ,
 560 .Xr syscons 4 ,
 561 .Xr vga 4 ,
 562 .Xr vt 4 ,
 563 .Xr rc.conf 5 ,
 564 .Xr kldload 8 ,
 565 .Xr moused 8 ,
 566 .Xr watch 8
 567 .Pp
 568 The various
 569 .Pa scr2*
 570 utilities in the
 571 .Pa graphics
 572 and
 573 .Pa textproc
 574 categories of the
 575 .Em "Ports Collection" .
 576 .Sh AUTHORS
 577 .An S\(/oren Schmidt Aq Mt sos@FreeBSD.org
 578 .An Sascha Wildner Aq Mt saw@online.de
 579 .Sh CONTRIBUTORS
 580 .An -split
 581 .An Maxim Sobolev Aq Mt sobomax@FreeBSD.org
 582 .An Nik Clayton Aq Mt nik@FreeBSD.org