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