usr.sbin/vidcontrol/vidcontrol.1

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