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.
20 .Nd system console control and configuration utility
25 .Op Fl c Ar appearance
36 .Op Fl i Cm active | adapter | mode
37 .Op Fl l Ar screen_map
40 .Op Fl r Ar foreground Ar background
43 .Op Fl T Cm xterm | cons25
44 .Op Fl t Ar N | Cm off
46 .Op Ar foreground Op Ar background
51 utility is used to set various options for the
56 such as video mode, colors, cursor shape, screen output map, font, and screen
58 Only a small subset of options is supported by
60 Unsupported options lead to error messages, typically including
61 the text "Inappropriate ioctl for device".
63 The following command line options are supported:
64 .Bl -tag -width indent
66 Select a new video mode.
67 The modes currently recognized are:
100 Alternatively, a mode can be specified with its number by using a mode name of
102 .Li MODE_ Ns Aq Ar NUMBER .
103 A list of valid mode numbers can be obtained with the
107 .Sx Video Mode Support
109 .It Ar foreground Op Ar background
110 Change colors when displaying text.
111 Specify the foreground color
113 .Dq vidcontrol white ) ,
114 or both a foreground and background colors
116 .Dq vidcontrol yellow blue ) .
119 command below to see available colors.
121 See the supported colors on a given platform.
125 This option may not be always supported by the video driver.
127 Clear the history buffer.
128 .It Fl c Ar setting Ns Op , Ns Ar setting ...
129 Change the cursor appearance.
130 The change is specified by a non-empty comma-separated list of
134 overrides or modifies previous ones in left to right order.
136 The following override
139 .Bl -tag -width indent
141 Set to a block covering 1 character cell,
142 with a configuration-dependent coloring
143 that should be at worst inverse video.
145 Set to a blinking sub-block with
147 scanlines starting at
151 is bad for backwards compatibility.
154 should not force destructiveness,
155 and it now only gives destructiveness in some
156 configurations (typically for hardware cursors
158 Blinking limits destructiveness.
161 should now be spelled
162 .Cm normal , Ns Cm blink , Ns Cm noblock .
163 A non-blinking destructive cursor would be unusable,
167 and this version does not have an override for it.
168 .It Cm base Ns = Ns Ar value , Cm height Ns = Ns Ar value
169 Set the specified scanline parameters.
170 These parameters are only active in
174 is an integer in any base supported by
178 to 0 turns off the cursor in
183 are silently ignored.
186 are clamped to fit in the character cell when the cursor is drawn.
189 The following modifier
192 .Bl -tag -width indent
193 .It Cm blink , noblink
194 Set or clear the blinking attribute.
195 This is not quite backwards compatible.
198 was an override to a blinking block.
199 .It Cm block , noblock
203 This attribute is the inverse of the flag
205 in the implementation.
206 It deactivates the scanline parameters,
207 and expresses a preference for using a
208 simpler method of implementation.
209 Its inverse does the opposite.
210 When the scanline parameters give a full block,
211 this attribute reduces to a method selection bit.
214 method tends to give better coloring.
215 .It Cm hidden , nohidden
216 Set or clear the hidden attribute.
219 The following (non-sticky) flags control application of the
221 .Bl -tag -width indent
227 to the (character) cursor's list of preferred colors instead of its shape.
228 Beware that the color numbers are raw VGA palette indexes,
229 not ANSI color numbers.
230 The indexes are reduced mod 8, 16 or 256,
232 depending on the video mode and renderer.
234 Colors for the mouse cursor in graphics mode.
237 except there is no preference or sequence;
239 gives the mouse border color and
241 gives the mouse interior color.
244 this gives 2 selection bits which select between
245 only 3 of 4 sub-destinations of the 4 destinations selected by
255 Apply the changes to the default settings and then to the active settings,
256 instead of only to the active settings.
259 this gives 2 selection bits which select between 4 destinations.
261 Ignore any changes to the
267 Apply the changes to the current vty.
268 The default is to apply them to a global place
269 and copy from there to all vtys.
272 The default is to not reset.
275 parameter is specified, the current local settings are reset
276 to default local settings.
277 Otherwise, the current global settings are reset to default
278 global settings and then copied to the current and default
279 settings for all vtys.
281 Show the current changes.
284 Print out current output screen map.
286 Set the terminal emulator to
289 Show the active and available terminal emulators.
306 The font file can be either uuencoded or in raw binary format.
307 You can also use the menu-driven
309 command to load the font of your choice.
312 may be omitted, in this case
314 will try to guess it from the size of font file.
322 can be omitted, and the default font will be loaded.
324 Note that older video cards, such as MDA and CGA, do not support
327 .Sx Video Mode Support
330 below and the man page for either
334 (depending on which driver you use).
338 of the text mode for the modes with selectable
340 Currently only raster modes, such as
344 .Sx Video Mode Support
349 Set the size of the history (scrollback) buffer to
353 Shows the active vty number.
355 Shows info about the current video adapter.
357 Shows the possible video modes with the current video hardware.
358 .It Fl l Ar screen_map
359 Install screen output map file from
365 (depending on which driver you use).
367 Install default screen output map.
369 Sets the base character used to render the mouse pointer to
372 Switch the mouse pointer
376 Used together with the
378 daemon for text mode cut & paste functionality.
380 Capture the current contents of the video buffer corresponding
381 to the terminal device referred to by standard input.
384 utility writes contents of the video buffer to the standard
385 output in a raw binary format.
386 For details about that
388 .Sx Format of Video Buffer Dump
395 but dump contents of the video buffer in a plain text format
396 ignoring nonprintable characters and information about text
407 to dump full history buffer instead of visible portion of
408 the video buffer only.
409 .It Fl r Ar foreground background
410 Change reverse mode colors to
415 Turn vty switching on or off.
416 When vty switching is off,
417 attempts to switch to a different virtual terminal will fail.
418 (The default is to permit vty switching.)
419 This protection can be easily bypassed when the kernel is compiled with
423 However, you probably should not compile the kernel debugger on a box which
424 is supposed to be physically secure.
426 Set the active vty to
428 .It Fl T Cm xterm | cons25
429 Switch between xterm and cons25 style terminal emulation.
430 .It Fl t Ar N | Cm off
431 Set the screensaver timeout to
436 Use hexadecimal digits for output.
438 .Ss Video Mode Support
439 Note that not all modes listed above may be supported by the video
441 You can verify which mode is supported by the video hardware, using the
445 The VESA BIOS support must be linked to the kernel
446 or loaded as a KLD module if you wish to use VESA video modes
451 You need to compile your kernel with the
453 option if you wish to use VGA 90 column modes
457 Video modes other than 25 and 30 line modes may require specific size of font.
460 option above to load a font file to the kernel.
461 If the required size of font has not been loaded to the kernel,
463 will fail if the user attempts to set a new video mode.
465 .Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact
466 .Sy Modes Ta Sy Font size
467 .No 25 line modes Ta 8x16 (VGA), 8x14 (EGA)
468 .No 30 line modes Ta 8x16
469 .No 43 line modes Ta 8x8
470 .No 50 line modes Ta 8x8
471 .No 60 line modes Ta 8x8
474 It is better to always load all three sizes (8x8, 8x14 and 8x16)
477 You may set variables in
480 .Pa /etc/rc.conf.local
481 so that desired font files will be automatically loaded
482 when the system starts up.
485 If you want to use any of the raster text modes you need to recompile your
493 (depending on which driver you use)
494 for more details on this kernel option.
495 .Ss Format of Video Buffer Dump
500 .\" is it supported on vt(4)???
505 to capture the current contents of the video buffer.
508 utility writes version and additional information to the standard
509 output, followed by the contents of the video buffer.
511 VGA video memory is typically arranged in two byte tuples,
512 one per character position.
513 In each tuple, the first byte will be the character code,
514 and the second byte is the character's color attribute.
516 The VGA color attribute byte looks like this:
517 .Bl -column "X:X" "<00000000>" "width" "bright foreground color"
518 .Sy "bits# width meaning"
519 .Li "7 <X0000000> 1 character blinking"
520 .Li "6:4 <0XXX0000> 3 background color"
521 .Li "3 <0000X000> 1 bright foreground color"
522 .Li "2:0 <00000XXX> 3 foreground color"
525 Here is a list of the three bit wide base colors:
527 .Bl -hang -offset indent -compact
546 Base colors with bit 3 (the bright foreground flag) set:
548 .Bl -hang -offset indent -compact
567 For example, the two bytes
571 specify an uppercase A (character code 65), blinking
572 (bit 7 set) in yellow (bits 3:0) on a blue background
577 output contains a small header which includes additional
578 information which may be useful to utilities processing
581 The first 10 bytes are always arranged as follows:
582 .Bl -column "Byte range" "Contents" -offset indent
583 .It Sy "Byte Range Contents"
584 .It "1 - 8 Literal text" Dq Li SCRSHOT_
585 .It "9 File format version number"
586 .It "10 Remaining number of bytes in the header"
589 Subsequent bytes depend on the version number.
590 .Bl -column "Version" "13 and up" -offset indent
591 .It Sy "Version Byte Meaning"
592 .It "1 11 Terminal width, in characters"
593 .It " 12 Terminal depth, in characters"
594 .It " 13 and up The snapshot data"
597 So a dump of an 80x25 screen would start (in hex)
598 .Bd -literal -offset indent
599 53 43 52 53 48 4f 54 5f 01 02 50 19
600 ----------------------- -- -- -- --
602 | | | `--- 80 decimal
603 | | `------ 2 remaining bytes of header data
604 | `--------- File format version 1
605 `------------------------ Literal "SCRSHOT_"
607 .Sh VIDEO OUTPUT CONFIGURATION
608 .Ss Boot Time Configuration
609 You may set the following variables in
612 .Pa /etc/rc.conf.local
613 in order to configure the video output at boot time.
615 .Bl -tag -width foo_bar_var -compact
617 Sets the timeout value for the
620 .It Ar font8x16 , font8x14 , font8x8
621 Specifies font files for the
625 Specifies a screen output map file for the
633 .Ss Driver Configuration
634 The video card driver may let you change default configuration
635 options, such as the default font, so that you do not need to set up
636 the options at boot time.
637 See video card driver manuals, (e.g.,
641 .Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact
642 .It Pa /usr/share/syscons/fonts/*
643 .It Pa /usr/share/vt/fonts/*
645 .It Pa /usr/share/syscons/scrnmaps/*
646 screen output map files (relevant for
652 .Pa /usr/share/syscons/fonts/iso-8x16.fnt
657 .Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt
659 So long as the font file is in
660 .Pa /usr/share/syscons/fonts
661 (if using syscons) or
662 .Pa /usr/share/vt/fonts
664 you may abbreviate the file name as
667 .Dl vidcontrol -f 8x16 iso-8x16
669 Furthermore, you can also omit font size
672 .Dl vidcontrol -f iso-8x16
674 Moreover, the suffix specifying the font size can also be omitted; in
677 will use the size of the currently displayed font to construct the
680 .Dl vidcontrol -f iso
682 Likewise, you can also abbreviate the screen output map file name for
685 option if the file is found in
686 .Pa /usr/share/syscons/scrnmaps .
688 .Dl vidcontrol -l iso-8859-1_to_cp437
690 The above command will load
691 .Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm .
693 The following command will set-up a 100x37 raster text mode (useful for
696 .Dl vidcontrol -g 100x37 VESA_800x600
698 The following command will capture the contents of the first virtual
699 terminal video buffer, and redirect the output to the
703 .Dl vidcontrol -p < /dev/ttyv0 > shot.scr
705 The following command will dump contents of the fourth virtual terminal
707 to the standard output in the human readable format:
709 .Dl vidcontrol -P < /dev/ttyv3
730 .Em "Ports Collection" .
732 .An S\(/oren Schmidt Aq Mt sos@FreeBSD.org
733 .An Sascha Wildner Aq Mt saw@online.de
736 .An Maxim Sobolev Aq Mt sobomax@FreeBSD.org
737 .An Nik Clayton Aq Mt nik@FreeBSD.org