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.
21 .Nd system console control and configuration utility
26 .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.
301 The font file can be either uuencoded or in raw binary format.
302 You can also use the menu-driven
304 command to load the font of your choice.
307 may be omitted, in this case
309 will try to guess it from the size of font file.
317 can be omitted, and the default font will be loaded.
319 Note that older video cards, such as MDA and CGA, do not support
322 .Sx Video Mode Support
325 below and the man page for either
329 (depending on which driver you use).
333 of the text mode for the modes with selectable
335 Currently only raster modes, such as
339 .Sx Video Mode Support
344 Set the size of the history (scrollback) buffer to
348 Shows the active vty number.
350 Shows info about the current video adapter.
352 Shows the possible video modes with the current video hardware.
353 .It Fl l Ar screen_map
354 Install screen output map file from
360 (depending on which driver you use).
362 Install default screen output map.
364 Sets the base character used to render the mouse pointer to
367 Switch the mouse pointer
371 Used together with the
373 daemon for text mode cut & paste functionality.
375 Capture the current contents of the video buffer corresponding
376 to the terminal device referred to by standard input.
379 utility writes contents of the video buffer to the standard
380 output in a raw binary format.
381 For details about that
383 .Sx Format of Video Buffer Dump
388 but dump contents of the video buffer in a plain text format
389 ignoring nonprintable characters and information about text
398 to dump full history buffer instead of visible portion of
399 the video buffer only.
400 .It Fl r Ar foreground background
401 Change reverse mode colors to
406 Turn vty switching on or off.
407 When vty switching is off,
408 attempts to switch to a different virtual terminal will fail.
409 (The default is to permit vty switching.)
410 This protection can be easily bypassed when the kernel is compiled with
414 However, you probably should not compile the kernel debugger on a box which
415 is supposed to be physically secure.
417 Set the active vty to
419 .It Fl T Cm xterm | cons25
420 Switch between xterm and cons25 style terminal emulation.
421 .It Fl t Ar N | Cm off
422 Set the screensaver timeout to
427 Use hexadecimal digits for output.
429 .Ss Video Mode Support
430 Note that not all modes listed above may be supported by the video
432 You can verify which mode is supported by the video hardware, using the
436 The VESA BIOS support must be linked to the kernel
437 or loaded as a KLD module if you wish to use VESA video modes
442 You need to compile your kernel with the
444 option if you wish to use VGA 90 column modes
448 Video modes other than 25 and 30 line modes may require specific size of font.
451 option above to load a font file to the kernel.
452 If the required size of font has not been loaded to the kernel,
454 will fail if the user attempts to set a new video mode.
456 .Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact
457 .Sy Modes Ta Sy Font size
458 .No 25 line modes Ta 8x16 (VGA), 8x14 (EGA)
459 .No 30 line modes Ta 8x16
460 .No 43 line modes Ta 8x8
461 .No 50 line modes Ta 8x8
462 .No 60 line modes Ta 8x8
465 It is better to always load all three sizes (8x8, 8x14 and 8x16)
468 You may set variables in
471 .Pa /etc/rc.conf.local
472 so that desired font files will be automatically loaded
473 when the system starts up.
476 If you want to use any of the raster text modes you need to recompile your
484 (depending on which driver you use)
485 for more details on this kernel option.
486 .Ss Format of Video Buffer Dump
491 .\" is it supported on vt(4)???
496 to capture the current contents of the video buffer.
499 utility writes version and additional information to the standard
500 output, followed by the contents of the video buffer.
502 VGA video memory is typically arranged in two byte tuples,
503 one per character position.
504 In each tuple, the first byte will be the character code,
505 and the second byte is the character's color attribute.
507 The VGA color attribute byte looks like this:
508 .Bl -column "X:X" "<00000000>" "width" "bright foreground color"
509 .Sy "bits# width meaning"
510 .Li "7 <X0000000> 1 character blinking"
511 .Li "6:4 <0XXX0000> 3 background color"
512 .Li "3 <0000X000> 1 bright foreground color"
513 .Li "2:0 <00000XXX> 3 foreground color"
516 Here is a list of the three bit wide base colors:
518 .Bl -hang -offset indent -compact
537 Base colors with bit 3 (the bright foreground flag) set:
539 .Bl -hang -offset indent -compact
558 For example, the two bytes
562 specify an uppercase A (character code 65), blinking
563 (bit 7 set) in yellow (bits 3:0) on a blue background
568 output contains a small header which includes additional
569 information which may be useful to utilities processing
572 The first 10 bytes are always arranged as follows:
573 .Bl -column "Byte range" "Contents" -offset indent
574 .It Sy "Byte Range Contents"
575 .It "1 - 8 Literal text" Dq Li SCRSHOT_
576 .It "9 File format version number"
577 .It "10 Remaining number of bytes in the header"
580 Subsequent bytes depend on the version number.
581 .Bl -column "Version" "13 and up" -offset indent
582 .It Sy "Version Byte Meaning"
583 .It "1 11 Terminal width, in characters"
584 .It " 12 Terminal depth, in characters"
585 .It " 13 and up The snapshot data"
588 So a dump of an 80x25 screen would start (in hex)
589 .Bd -literal -offset indent
590 53 43 52 53 48 4f 54 5f 01 02 50 19
591 ----------------------- -- -- -- --
593 | | | `--- 80 decimal
594 | | `------ 2 remaining bytes of header data
595 | `--------- File format version 1
596 `------------------------ Literal "SCRSHOT_"
598 .Sh VIDEO OUTPUT CONFIGURATION
599 .Ss Boot Time Configuration
600 You may set the following variables in
603 .Pa /etc/rc.conf.local
604 in order to configure the video output at boot time.
606 .Bl -tag -width foo_bar_var -compact
608 Sets the timeout value for the
611 .It Ar font8x16 , font8x14 , font8x8
612 Specifies font files for the
616 Specifies a screen output map file for the
624 .Ss Driver Configuration
625 The video card driver may let you change default configuration
626 options, such as the default font, so that you do not need to set up
627 the options at boot time.
628 See video card driver manuals, (e.g.,
632 .Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact
633 .It Pa /usr/share/syscons/fonts/*
634 .It Pa /usr/share/vt/fonts/*
636 .It Pa /usr/share/syscons/scrnmaps/*
637 screen output map files (relevant for
643 .Pa /usr/share/syscons/fonts/iso-8x16.fnt
648 .Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt
650 So long as the font file is in
651 .Pa /usr/share/syscons/fonts
652 (if using syscons) or
653 .Pa /usr/share/vt/fonts
655 you may abbreviate the file name as
658 .Dl vidcontrol -f 8x16 iso-8x16
660 Furthermore, you can also omit font size
663 .Dl vidcontrol -f iso-8x16
665 Moreover, the suffix specifying the font size can also be omitted; in
668 will use the size of the currently displayed font to construct the
671 .Dl vidcontrol -f iso
673 Likewise, you can also abbreviate the screen output map file name for
676 option if the file is found in
677 .Pa /usr/share/syscons/scrnmaps .
679 .Dl vidcontrol -l iso-8859-1_to_cp437
681 The above command will load
682 .Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm .
684 The following command will set-up a 100x37 raster text mode (useful for
687 .Dl vidcontrol -g 100x37 VESA_800x600
689 The following command will capture the contents of the first virtual
690 terminal video buffer, and redirect the output to the
694 .Dl vidcontrol -p < /dev/ttyv0 > shot.scr
696 The following command will dump contents of the fourth virtual terminal
698 to the standard output in the human readable format:
700 .Dl vidcontrol -P < /dev/ttyv3
721 .Em "Ports Collection" .
723 .An S\(/oren Schmidt Aq Mt sos@FreeBSD.org
724 .An Sascha Wildner Aq Mt saw@online.de
727 .An Maxim Sobolev Aq Mt sobomax@FreeBSD.org
728 .An Nik Clayton Aq Mt nik@FreeBSD.org