2 .\" vidcontrol - a utility for manipulating the syscons or vt video driver
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
18 .Nd system console control and configuration utility
23 .Op Fl c Ar appearance
34 .Op Fl i Cm active | adapter | mode
35 .Op Fl l Ar screen_map
38 .Op Fl r Ar foreground Ar background
41 .Op Fl T Cm xterm | cons25
42 .Op Fl t Ar N | Cm off
44 .Op Ar foreground Op Ar background
49 utility is used to set various options for the
54 such as video mode, colors, cursor shape, screen output map, font, and screen
56 Only a small subset of options is supported by
58 Unsupported options lead to error messages, typically including
59 the text "Inappropriate ioctl for device".
61 The following command line options are supported:
62 .Bl -tag -width indent
64 Select a new video mode.
65 The modes currently recognized are:
98 Alternatively, a mode can be specified with its number by using a mode name of
100 .Li MODE_ Ns Aq Ar NUMBER .
101 A list of valid mode numbers can be obtained with the
105 .Sx Video Mode Support
107 .It Ar foreground Op Ar background
108 Change colors when displaying text.
109 Specify the foreground color
111 .Dq vidcontrol white ) ,
112 or both a foreground and background colors
114 .Dq vidcontrol yellow blue ) .
117 command below to see available colors.
119 See the supported colors on a given platform.
123 This option may not be always supported by the video driver.
125 Clear the history buffer.
126 .It Fl c Ar setting Ns Op , Ns Ar setting ...
127 Change the cursor appearance.
128 The change is specified by a non-empty comma-separated list of
132 overrides or modifies previous ones in left to right order.
134 The following override
137 .Bl -tag -width indent
139 Set to a block covering 1 character cell,
140 with a configuration-dependent coloring
141 that should be at worst inverse video.
143 Set to a blinking sub-block with
145 scanlines starting at
149 is bad for backwards compatibility.
152 should not force destructiveness,
153 and it now only gives destructiveness in some
154 configurations (typically for hardware cursors
156 Blinking limits destructiveness.
159 should now be spelled
160 .Cm normal , Ns Cm blink , Ns Cm noblock .
161 A non-blinking destructive cursor would be unusable,
165 and this version does not have an override for it.
166 .It Cm base Ns = Ns Ar value , Cm height Ns = Ns Ar value
167 Set the specified scanline parameters.
168 These parameters are only active in
172 is an integer in any base supported by
176 to 0 turns off the cursor in
181 are silently ignored.
184 are clamped to fit in the character cell when the cursor is drawn.
187 The following modifier
190 .Bl -tag -width indent
191 .It Cm blink , noblink
192 Set or clear the blinking attribute.
193 This is not quite backwards compatible.
196 was an override to a blinking block.
197 .It Cm block , noblock
201 This attribute is the inverse of the flag
203 in the implementation.
204 It deactivates the scanline parameters,
205 and expresses a preference for using a
206 simpler method of implementation.
207 Its inverse does the opposite.
208 When the scanline parameters give a full block,
209 this attribute reduces to a method selection bit.
212 method tends to give better coloring.
213 .It Cm hidden , nohidden
214 Set or clear the hidden attribute.
217 The following (non-sticky) flags control application of the
219 .Bl -tag -width indent
225 to the (character) cursor's list of preferred colors instead of its shape.
226 Beware that the color numbers are raw VGA palette indexes,
227 not ANSI color numbers.
228 The indexes are reduced mod 8, 16 or 256,
230 depending on the video mode and renderer.
232 Colors for the mouse cursor in graphics mode.
235 except there is no preference or sequence;
237 gives the mouse border color and
239 gives the mouse interior color.
242 this gives 2 selection bits which select between
243 only 3 of 4 sub-destinations of the 4 destinations selected by
253 Apply the changes to the default settings and then to the active settings,
254 instead of only to the active settings.
257 this gives 2 selection bits which select between 4 destinations.
259 Ignore any changes to the
265 Apply the changes to the current vty.
266 The default is to apply them to a global place
267 and copy from there to all vtys.
270 The default is to not reset.
273 parameter is specified, the current local settings are reset
274 to default local settings.
275 Otherwise, the current global settings are reset to default
276 global settings and then copied to the current and default
277 settings for all vtys.
279 Show the current changes.
282 Print out current output screen map.
284 Set the terminal emulator to
287 Show the active and available terminal emulators.
304 The font file can be either uuencoded or in raw binary format.
305 You can also use the menu-driven
307 command to load the font of your choice.
310 may be omitted, in this case
312 will try to guess it from the size of font file.
320 can be omitted, and the default font will be loaded.
322 Note that older video cards, such as MDA and CGA, do not support
325 .Sx Video Mode Support
328 below and the man page for either
332 (depending on which driver you use).
336 of the text mode for the modes with selectable
338 Currently only raster modes, such as
342 .Sx Video Mode Support
347 Set the size of the history (scrollback) buffer to
351 Shows the active vty number.
353 Shows info about the current video adapter.
355 Shows the possible video modes with the current video hardware.
356 .It Fl l Ar screen_map
357 Install screen output map file from
363 (depending on which driver you use).
365 Install default screen output map.
367 Sets the base character used to render the mouse pointer to
370 Switch the mouse pointer
374 Used together with the
376 daemon for text mode cut & paste functionality.
378 Capture the current contents of the video buffer corresponding
379 to the terminal device referred to by standard input.
382 utility writes contents of the video buffer to the standard
383 output in a raw binary format.
384 For details about that
386 .Sx Format of Video Buffer Dump
393 but dump contents of the video buffer in a plain text format
394 ignoring nonprintable characters and information about text
405 to dump full history buffer instead of visible portion of
406 the video buffer only.
407 .It Fl r Ar foreground background
408 Change reverse mode colors to
413 Turn vty switching on or off.
414 When vty switching is off,
415 attempts to switch to a different virtual terminal will fail.
416 (The default is to permit vty switching.)
417 This protection can be easily bypassed when the kernel is compiled with
421 However, you probably should not compile the kernel debugger on a box which
422 is supposed to be physically secure.
424 Set the active vty to
426 .It Fl T Cm xterm | cons25
427 Switch between xterm and cons25 style terminal emulation.
428 .It Fl t Ar N | Cm off
429 Set the screensaver timeout to
434 Use hexadecimal digits for output.
436 .Ss Video Mode Support
437 Note that not all modes listed above may be supported by the video
439 You can verify which mode is supported by the video hardware, using the
443 The VESA BIOS support must be linked to the kernel
444 or loaded as a KLD module if you wish to use VESA video modes
449 You need to compile your kernel with the
451 option if you wish to use VGA 90 column modes
455 Video modes other than 25 and 30 line modes may require specific size of font.
458 option above to load a font file to the kernel.
459 If the required size of font has not been loaded to the kernel,
461 will fail if the user attempts to set a new video mode.
463 .Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact
464 .Sy Modes Ta Sy Font size
465 .No 25 line modes Ta 8x16 (VGA), 8x14 (EGA)
466 .No 30 line modes Ta 8x16
467 .No 43 line modes Ta 8x8
468 .No 50 line modes Ta 8x8
469 .No 60 line modes Ta 8x8
472 It is better to always load all three sizes (8x8, 8x14 and 8x16)
475 You may set variables in
478 .Pa /etc/rc.conf.local
479 so that desired font files will be automatically loaded
480 when the system starts up.
483 If you want to use any of the raster text modes you need to recompile your
491 (depending on which driver you use)
492 for more details on this kernel option.
493 .Ss Format of Video Buffer Dump
498 .\" is it supported on vt(4)???
503 to capture the current contents of the video buffer.
506 utility writes version and additional information to the standard
507 output, followed by the contents of the video buffer.
509 VGA video memory is typically arranged in two byte tuples,
510 one per character position.
511 In each tuple, the first byte will be the character code,
512 and the second byte is the character's color attribute.
514 The VGA color attribute byte looks like this:
515 .Bl -column "X:X" "<00000000>" "width" "bright foreground color"
516 .Sy "bits# width meaning"
517 .Li "7 <X0000000> 1 character blinking"
518 .Li "6:4 <0XXX0000> 3 background color"
519 .Li "3 <0000X000> 1 bright foreground color"
520 .Li "2:0 <00000XXX> 3 foreground color"
523 Here is a list of the three bit wide base colors:
525 .Bl -hang -offset indent -compact
544 Base colors with bit 3 (the bright foreground flag) set:
546 .Bl -hang -offset indent -compact
565 For example, the two bytes
569 specify an uppercase A (character code 65), blinking
570 (bit 7 set) in yellow (bits 3:0) on a blue background
575 output contains a small header which includes additional
576 information which may be useful to utilities processing
579 The first 10 bytes are always arranged as follows:
580 .Bl -column "Byte range" "Contents" -offset indent
581 .It Sy "Byte Range Contents"
582 .It "1 - 8 Literal text" Dq Li SCRSHOT_
583 .It "9 File format version number"
584 .It "10 Remaining number of bytes in the header"
587 Subsequent bytes depend on the version number.
588 .Bl -column "Version" "13 and up" -offset indent
589 .It Sy "Version Byte Meaning"
590 .It "1 11 Terminal width, in characters"
591 .It " 12 Terminal depth, in characters"
592 .It " 13 and up The snapshot data"
595 So a dump of an 80x25 screen would start (in hex)
596 .Bd -literal -offset indent
597 53 43 52 53 48 4f 54 5f 01 02 50 19
598 ----------------------- -- -- -- --
600 | | | `--- 80 decimal
601 | | `------ 2 remaining bytes of header data
602 | `--------- File format version 1
603 `------------------------ Literal "SCRSHOT_"
605 .Sh VIDEO OUTPUT CONFIGURATION
606 .Ss Boot Time Configuration
607 You may set the following variables in
610 .Pa /etc/rc.conf.local
611 in order to configure the video output at boot time.
613 .Bl -tag -width foo_bar_var -compact
615 Sets the timeout value for the
618 .It Ar font8x16 , font8x14 , font8x8
619 Specifies font files for the
623 Specifies a screen output map file for the
631 .Ss Driver Configuration
632 The video card driver may let you change default configuration
633 options, such as the default font, so that you do not need to set up
634 the options at boot time.
635 See video card driver manuals, (e.g.,
639 .Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact
640 .It Pa /usr/share/syscons/fonts/*
641 .It Pa /usr/share/vt/fonts/*
643 .It Pa /usr/share/syscons/scrnmaps/*
644 screen output map files (relevant for
650 .Pa /usr/share/syscons/fonts/iso-8x16.fnt
655 .Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt
657 So long as the font file is in
658 .Pa /usr/share/syscons/fonts
659 (if using syscons) or
660 .Pa /usr/share/vt/fonts
662 you may abbreviate the file name as
665 .Dl vidcontrol -f 8x16 iso-8x16
667 Furthermore, you can also omit font size
670 .Dl vidcontrol -f iso-8x16
672 Moreover, the suffix specifying the font size can also be omitted; in
675 will use the size of the currently displayed font to construct the
678 .Dl vidcontrol -f iso
680 Likewise, you can also abbreviate the screen output map file name for
683 option if the file is found in
684 .Pa /usr/share/syscons/scrnmaps .
686 .Dl vidcontrol -l iso-8859-1_to_cp437
688 The above command will load
689 .Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm .
691 The following command will set-up a 100x37 raster text mode (useful for
694 .Dl vidcontrol -g 100x37 VESA_800x600
696 The following command will capture the contents of the first virtual
697 terminal video buffer, and redirect the output to the
701 .Dl vidcontrol -p < /dev/ttyv0 > shot.scr
703 The following command will dump contents of the fourth virtual terminal
705 to the standard output in the human readable format:
707 .Dl vidcontrol -P < /dev/ttyv3
728 .Em "Ports Collection" .
730 .An S\(/oren Schmidt Aq Mt sos@FreeBSD.org
731 .An Sascha Wildner Aq Mt saw@online.de
734 .An Maxim Sobolev Aq Mt sobomax@FreeBSD.org
735 .An Nik Clayton Aq Mt nik@FreeBSD.org