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