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