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