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 .\"
  16 .Dd May 27, 2002
  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 Cm on | off
  40 .Op Fl s Ar number
  41 .Op Fl t Ar N | Cm off
  42 .Op Ar mode
  43 .Op Ar foreground Op Ar background
  44 .Op Cm show
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 command is used to set various options for the
  49 .Xr syscons 4
  50 console driver,
  51 such as video mode, colors, cursor shape, screen output map, font and screen
  52 saver timeout.
  53 .Pp
  54 The following command line options are supported:
  55 .Bl -tag -width indent
  56 .It Ar mode
  57 Select a new video mode.
  58 The modes currently recognized are:
  59 .Ar 80x25 ,
  60 .Ar 80x30 ,
  61 .Ar 80x43 ,
  62 .Ar 80x50 ,
  63 .Ar 80x60 ,
  64 .Ar 132x25 ,
  65 .Ar 132x30 ,
  66 .Ar 132x43 ,
  67 .Ar 132x50 ,
  68 .Ar 132x60 ,
  69 .Ar VGA_40x25 ,
  70 .Ar VGA_80x25 ,
  71 .Ar VGA_80x30 ,
  72 .Ar VGA_80x50 ,
  73 .Ar VGA_80x60 ,
  74 .Ar VGA_90x25 ,
  75 .Ar VGA_90x30 ,
  76 .Ar VGA_90x43 ,
  77 .Ar VGA_90x50 ,
  78 .Ar VGA_90x60 ,
  79 .Ar EGA_80x25 ,
  80 .Ar EGA_80x43 ,
  81 .Ar VESA_132x25 ,
  82 .Ar VESA_132x43 ,
  83 .Ar VESA_132x50 ,
  84 .Ar VESA_132x60 .
  85 .\"The graphic mode
  86 .\".Ar VGA_320x200
  87 .\"and
  88 The raster text mode
  89 .Ar VESA_800x600
  90 can also be chosen.
  91 Alternatively, a mode can be specified with its number by using a mode name of
  92 the form
  93 .Ar MODE_<NUMBER> .
  94 A list of valid mode numbers can be obtained with the
  95 .Fl i Cm mode
  96 option. See
  97 .Sx Video Mode Support
  98 below.
  99 .It Ar foreground Op Ar background
 100 Change colors when displaying text.
 101 Specify the foreground color
 102 (e.g.\&
 103 .Dq vidcontrol white ) ,
 104 or both a foreground and background colors
 105 (e.g.\&
 106 .Dq vidcontrol yellow blue ) .
 107 Use the
 108 .Cm show
 109 command below to see available colors.
 110 .It Cm show
 111 See the supported colors on a given platform.
 112 .It Fl b Ar color
 113 Set border color to
 114 .Ar color .
 115 This option may not be always supported by the video driver.
 116 .It Fl C
 117 Clear the history buffer.
 118 .It Fl c Cm normal | blink | destructive
 119 Change the cursor appearance.
 120 The cursor is either an inverting block
 121 .Pq Cm normal
 122 that can optionally
 123 .Cm blink ,
 124 or it can be like the old hardware cursor
 125 .Pq Cm destructive .
 126 The latter is actually a simulation.
 127 .It Fl d
 128 Print out current output screen map.
 129 .It Xo
 130 .Fl f
 131 .Op Ar size
 132 .Ar file
 133 .Xc
 134 Load font
 135 .Ar file
 136 for
 137 .Ar size
 138 (currently, only
 139 .Cm 8x8 ,
 140 .Cm 8x14
 141 or
 142 .Cm 8x16 ) .
 143 The font file can be either uuencoded or in raw binary format.
 144 You can also use the menu-driven
 145 .Xr vidfont 1
 146 command to load the font of your choice.
 147 .Pp
 148 .Ar Size
 149 may be omitted, in this case
 150 .Nm
 151 will try to guess it from the size of font file.
 152 .Pp
 153 See also
 154 .Sx Video Mode Support
 155 and
 156 .Sx EXAMPLES
 157 below and the man page for
 158 .Xr syscons 4 .
 159 .It Fl g Ar geometry
 160 Set the
 161 .Ar geometry
 162 of the text mode for the modes with selectable
 163 geometry.
 164 Currently only raster modes, such as
 165 .Ar VESA_800x600 ,
 166 support this option.
 167 See also
 168 .Sx Video Mode Support
 169 and
 170 .Sx EXAMPLES
 171 below.
 172 .It Fl h Ar size
 173 Set the size of the history (scrollback) buffer to
 174 .Ar size
 175 lines.
 176 .It Fl i Cm adapter
 177 Shows info about the current video adapter.
 178 .It Fl i Cm mode
 179 Shows the possible video modes with the current video hardware.
 180 .It Fl l Ar screen_map
 181 Install screen output map file from
 182 .Ar screen_map .
 183 See also
 184 .Xr syscons 4 .
 185 .It Fl L
 186 Install default screen output map.
 187 .It Fl M Ar char
 188 Sets the base character used to render the mouse pointer to
 189 .Ar char .
 190 .It Fl m Cm on | off
 191 Switch the mouse pointer
 192 .Cm on
 193 or
 194 .Cm off .
 195 Used together with the
 196 .Xr moused 8
 197 daemon for text mode cut & paste functionality.
 198 .It Fl p
 199 Capture the current contents of the video buffer corresponding
 200 to the terminal device referred to by standard input.
 201 The
 202 .Nm
 203 utility writes contents of the video buffer to the standard
 204 output in a raw binary format.
 205 For details about that
 206 format see
 207 .Sx Format of Video Buffer Dump
 208 below.
 209 .It Fl P
 210 Same as
 211 .Fl p ,
 212 but dump contents of the video buffer in a plain text format
 213 ignoring nonprintable characters and information about text
 214 attributes.
 215 .It Fl r Ar foreground background
 216 Change reverse mode colors to
 217 .Ar foreground
 218 and
 219 .Ar background .
 220 .It Fl S Cm on | off
 221 Turn vty switching on or off.
 222 When vty switching is off,
 223 attempts to switch to a different virtual terminal will fail.
 224 (The default is to permit vty switching.)
 225 .It Fl s Ar number
 226 Set the current vty to
 227 .Ar number .
 228 .It Fl t Ar N | Cm off
 229 Set the screensaver timeout to
 230 .Ar N
 231 seconds, or turns it
 232 .Cm off .
 233 .It Fl x
 234 Use hexadecimal digits for output.
 235 .El
 236 .Ss Video Mode Support
 237 Note that not all modes listed above may be supported by the video
 238 hardware.
 239 You can verify which mode is supported by the video hardware, using the
 240 .Fl i Cm mode
 241 option.
 242 .Pp
 243 The VESA BIOS support must be linked to the kernel
 244 or loaded as a KLD module if you wish to use VESA video modes
 245 or 132 column modes
 246 (see
 247 .Xr vga 4 ) .
 248 .Pp
 249 You need to compile your kernel with the
 250 .Ar VGA_WIDTH90
 251 option if you wish to use VGA 90 column modes
 252 (see
 253 .Xr vga 4 ) .
 254 .Pp
 255 Video modes other than 25 and 30 line modes may require specific size of font.
 256 Use
 257 .Fl f
 258 option above to load a font file to the kernel.
 259 If the required size of font has not been loaded to the kernel,
 260 .Nm
 261 will fail if the user attempts to set a new video mode.
 262 .Pp
 263 .Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact
 264 .Sy Modes Ta Sy Font size
 265 .Li 25 line modes Ta 8x16 (VGA), 8x14 (EGA)
 266 .Li 30 line modes Ta 8x16
 267 .Li 43 line modes Ta 8x8
 268 .Li 50 line modes Ta 8x8
 269 .Li 60 line modes Ta 8x8
 270 .El
 271 .Pp
 272 It is better to always load all three sizes (8x8, 8x14 and 8x16)
 273 of the same font.
 274 .Pp
 275 You may set variables in
 276 .Pa /etc/rc.conf
 277 or
 278 .Pa /etc/rc.conf.local
 279 so that desired font files will be automatically loaded
 280 when the system starts up.
 281 See below.
 282 .Pp
 283 If you want to use any of the raster text modes you need to recompile your
 284 kernel with the
 285 .Dv SC_PIXEL_MODE
 286 option.
 287 See
 288 .Xr syscons 4
 289 for more details on this kernel option.
 290 .Ss Format of Video Buffer Dump
 291 The
 292 .Nm
 293 utility uses the
 294 .Xr syscons 4
 295 .Dv CONS_SCRSHOT
 296 .Xr ioctl 2
 297 to capture the current contents of the video buffer.
 298 The
 299 .Nm
 300 utility writes version and additional information to the standard
 301 output, followed by the contents of the terminal device.
 302 .Pp
 303 PC video memory is typically arranged in two byte tuples,
 304 one per character position.
 305 In each tuple, the first byte
 306 will be the character code, and the second byte is the
 307 character's color attribute.
 308 .Pp
 309 The color attribute byte is further broken down into the
 310 low nibble, which specifies which of 16 different foreground
 311 colors is active, and the high nibble, which specifies which
 312 of 16 different background colors is active.
 313 .Pp
 314 .Bl -hang -offset indent -compact
 315 .It 0
 316 Black
 317 .It 1
 318 Blue
 319 .It 2
 320 Green
 321 .It 3
 322 Cyan
 323 .It 4
 324 Red
 325 .It 5
 326 Magenta
 327 .It 6
 328 Brown
 329 .It 7
 330 White
 331 .It 8
 332 Grey
 333 .It 9
 334 Light Blue
 335 .It 10
 336 Light Green
 337 .It 11
 338 Light Cyan
 339 .It 12
 340 Light Red
 341 .It 13
 342 Light Magenta
 343 .It 14
 344 Yellow
 345 .It 15
 346 White
 347 .El
 348 .Pp
 349 It can be seen that the last 8 colors are brighter
 350 versions of the first 8.
 351 .Pp
 352 For example, the two bytes
 353 .Pp
 354 .Dl "65 158"
 355 .Pp
 356 specify an uppercase A (character code 65), in
 357 yellow (low nibble 15) on a light blue background
 358 (high nibble 9).
 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 .An Sascha Wildner