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