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