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