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