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
37 .Op Fl i Cm active | adapter | mode
38 .Op Fl l Ar screen_map
41 .Op Fl r Ar foreground Ar background
44 .Op Fl T Cm xterm | cons25
45 .Op Fl t Ar N | Cm off
47 .Op Ar foreground Op Ar background
52 utility is used to set various options for the
57 such as video mode, colors, cursor shape, screen output map, font, and screen
59 Only a small subset of options is supported by
61 Unsupported options lead to error messages, typically including
62 the text "Inappropriate ioctl for device".
64 The following command line options are supported:
65 .Bl -tag -width indent
67 Select a new video mode.
68 The modes currently recognized are:
101 Alternatively, a mode can be specified with its number by using a mode name of
103 .Li MODE_ Ns Aq Ar NUMBER .
104 A list of valid mode numbers can be obtained with the
108 .Sx Video Mode Support
110 .It Ar foreground Op Ar background
111 Change colors when displaying text.
112 Specify the foreground color
114 .Dq vidcontrol white ) ,
115 or both a foreground and background colors
117 .Dq vidcontrol yellow blue ) .
120 command below to see available colors.
122 See the supported colors on a given platform.
126 This option may not be always supported by the video driver.
128 Clear the history buffer.
129 .It Fl c Ar setting Ns Op , Ns Ar setting ...
130 Change the cursor appearance.
131 The change is specified by a non-empty comma-separated list of
135 overrides or modifies previous ones in left to right order.
137 The following override
140 .Bl -tag -width indent
142 Set to a block covering 1 character cell,
143 with a configuration-dependent coloring
144 that should be at worst inverse video.
146 Set to a blinking sub-block with
148 scanlines starting at
152 is bad for backwards compatibility.
155 should not force destructiveness,
156 and it now only gives destructiveness in some
157 configurations (typically for hardware cursors
159 Blinking limits destructiveness.
162 should now be spelled
163 .Cm normal , Ns Cm blink , Ns Cm noblock .
164 A non-blinking destructive cursor would be unusable,
168 and this version does not have an override for it.
169 .It Cm base Ns = Ns Ar value , Cm height Ns = Ns Ar value
170 Set the specified scanline parameters.
171 These parameters are only active in
175 is an integer in any base supported by
179 to 0 turns off the cursor in
184 are silently ignored.
187 are clamped to fit in the character cell when the cursor is drawn.
190 The following modifier
193 .Bl -tag -width indent
194 .It Cm blink , noblink
195 Set or clear the blinking attribute.
196 This is not quite backwards compatible.
199 was an override to a blinking block.
200 .It Cm block , noblock
204 This attribute is the inverse of the flag
206 in the implementation.
207 It deactivates the scanline parameters,
208 and expresses a preference for using a
209 simpler method of implementation.
210 Its inverse does the opposite.
211 When the scanline parameters give a full block,
212 this attribute reduces to a method selection bit.
215 method tends to give better coloring.
216 .It Cm hidden , nohidden
217 Set or clear the hidden attribute.
220 The following (non-sticky) flags control application of the
222 .Bl -tag -width indent
228 to the (character) cursor's list of preferred colors instead of its shape.
229 Beware that the color numbers are raw VGA palette indexes,
230 not ANSI color numbers.
231 The indexes are reduced mod 8, 16 or 256,
233 depending on the video mode and renderer.
235 Colors for the mouse cursor in graphics mode.
238 except there is no preference or sequence;
240 gives the mouse border color and
242 gives the mouse interior color.
245 this gives 2 selection bits which select between
246 only 3 of 4 sub-destinations of the 4 destinations selected by
256 Apply the changes to the default settings and then to the active settings,
257 instead of only to the active settings.
260 this gives 2 selection bits which select between 4 destinations.
262 Ignore any changes to the
268 Apply the changes to the current vty.
269 The default is to apply them to a global place
270 and copy from there to all vtys.
273 The default is to not reset.
276 parameter is specified, the current local settings are reset
277 to default local settings.
278 Otherwise, the current global settings are reset to default
279 global settings and then copied to the current and default
280 settings for all vtys.
282 Show the current changes.
285 Print out current output screen map.
287 Set the terminal emulator to
290 Show the active and available terminal emulators.
307 The font file can be either uuencoded or in raw binary format.
308 You can also use the menu-driven
310 command to load the font of your choice.
313 may be omitted, in this case
315 will try to guess it from the size of font file.
323 can be omitted, and the default font will be loaded.
325 Note that older video cards, such as MDA and CGA, do not support
328 .Sx Video Mode Support
331 below and the man page for either
335 (depending on which driver you use).
339 of the text mode for the modes with selectable
341 Currently only raster modes, such as
345 .Sx Video Mode Support
350 Set the size of the history (scrollback) buffer to
354 Shows the active vty number.
356 Shows info about the current video adapter.
358 Shows the possible video modes with the current video hardware.
359 .It Fl l Ar screen_map
360 Install screen output map file from
366 (depending on which driver you use).
368 Install default screen output map.
370 Sets the base character used to render the mouse pointer to
373 Switch the mouse pointer
377 Used together with the
379 daemon for text mode cut & paste functionality.
381 Capture the current contents of the video buffer corresponding
382 to the terminal device referred to by standard input.
385 utility writes contents of the video buffer to the standard
386 output in a raw binary format.
387 For details about that
389 .Sx Format of Video Buffer Dump
394 but dump contents of the video buffer in a plain text format
395 ignoring nonprintable characters and information about text
404 to dump full history buffer instead of visible portion of
405 the video buffer only.
406 .It Fl r Ar foreground background
407 Change reverse mode colors to
412 Turn vty switching on or off.
413 When vty switching is off,
414 attempts to switch to a different virtual terminal will fail.
415 (The default is to permit vty switching.)
416 This protection can be easily bypassed when the kernel is compiled with
420 However, you probably should not compile the kernel debugger on a box which
421 is supposed to be physically secure.
423 Set the active vty to
425 .It Fl T Cm xterm | cons25
426 Switch between xterm and cons25 style terminal emulation.
427 .It Fl t Ar N | Cm off
428 Set the screensaver timeout to
433 Use hexadecimal digits for output.
435 .Ss Video Mode Support
436 Note that not all modes listed above may be supported by the video
438 You can verify which mode is supported by the video hardware, using the
442 The VESA BIOS support must be linked to the kernel
443 or loaded as a KLD module if you wish to use VESA video modes
448 You need to compile your kernel with the
450 option if you wish to use VGA 90 column modes
454 Video modes other than 25 and 30 line modes may require specific size of font.
457 option above to load a font file to the kernel.
458 If the required size of font has not been loaded to the kernel,
460 will fail if the user attempts to set a new video mode.
462 .Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact
463 .Sy Modes Ta Sy Font size
464 .No 25 line modes Ta 8x16 (VGA), 8x14 (EGA)
465 .No 30 line modes Ta 8x16
466 .No 43 line modes Ta 8x8
467 .No 50 line modes Ta 8x8
468 .No 60 line modes Ta 8x8
471 It is better to always load all three sizes (8x8, 8x14 and 8x16)
474 You may set variables in
477 .Pa /etc/rc.conf.local
478 so that desired font files will be automatically loaded
479 when the system starts up.
482 If you want to use any of the raster text modes you need to recompile your
490 (depending on which driver you use)
491 for more details on this kernel option.
492 .Ss Format of Video Buffer Dump
497 .\" is it supported on vt(4)???
502 to capture the current contents of the video buffer.
505 utility writes version and additional information to the standard
506 output, followed by the contents of the video buffer.
508 VGA video memory is typically arranged in two byte tuples,
509 one per character position.
510 In each tuple, the first byte will be the character code,
511 and the second byte is the character's color attribute.
513 The VGA color attribute byte looks like this:
514 .Bl -column "X:X" "<00000000>" "width" "bright foreground color"
515 .Sy "bits# width meaning"
516 .Li "7 <X0000000> 1 character blinking"
517 .Li "6:4 <0XXX0000> 3 background color"
518 .Li "3 <0000X000> 1 bright foreground color"
519 .Li "2:0 <00000XXX> 3 foreground color"
522 Here is a list of the three bit wide base colors:
524 .Bl -hang -offset indent -compact
543 Base colors with bit 3 (the bright foreground flag) set:
545 .Bl -hang -offset indent -compact
564 For example, the two bytes
568 specify an uppercase A (character code 65), blinking
569 (bit 7 set) in yellow (bits 3:0) on a blue background
574 output contains a small header which includes additional
575 information which may be useful to utilities processing
578 The first 10 bytes are always arranged as follows:
579 .Bl -column "Byte range" "Contents" -offset indent
580 .It Sy "Byte Range Contents"
581 .It "1 - 8 Literal text" Dq Li SCRSHOT_
582 .It "9 File format version number"
583 .It "10 Remaining number of bytes in the header"
586 Subsequent bytes depend on the version number.
587 .Bl -column "Version" "13 and up" -offset indent
588 .It Sy "Version Byte Meaning"
589 .It "1 11 Terminal width, in characters"
590 .It " 12 Terminal depth, in characters"
591 .It " 13 and up The snapshot data"
594 So a dump of an 80x25 screen would start (in hex)
595 .Bd -literal -offset indent
596 53 43 52 53 48 4f 54 5f 01 02 50 19
597 ----------------------- -- -- -- --
599 | | | `--- 80 decimal
600 | | `------ 2 remaining bytes of header data
601 | `--------- File format version 1
602 `------------------------ Literal "SCRSHOT_"
604 .Sh VIDEO OUTPUT CONFIGURATION
605 .Ss Boot Time Configuration
606 You may set the following variables in
609 .Pa /etc/rc.conf.local
610 in order to configure the video output at boot time.
612 .Bl -tag -width foo_bar_var -compact
614 Sets the timeout value for the
617 .It Ar font8x16 , font8x14 , font8x8
618 Specifies font files for the
622 Specifies a screen output map file for the
630 .Ss Driver Configuration
631 The video card driver may let you change default configuration
632 options, such as the default font, so that you do not need to set up
633 the options at boot time.
634 See video card driver manuals, (e.g.,
638 .Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact
639 .It Pa /usr/share/syscons/fonts/*
640 .It Pa /usr/share/vt/fonts/*
642 .It Pa /usr/share/syscons/scrnmaps/*
643 screen output map files (relevant for
649 .Pa /usr/share/syscons/fonts/iso-8x16.fnt
654 .Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt
656 So long as the font file is in
657 .Pa /usr/share/syscons/fonts
658 (if using syscons) or
659 .Pa /usr/share/vt/fonts
661 you may abbreviate the file name as
664 .Dl vidcontrol -f 8x16 iso-8x16
666 Furthermore, you can also omit font size
669 .Dl vidcontrol -f iso-8x16
671 Moreover, the suffix specifying the font size can also be omitted; in
674 will use the size of the currently displayed font to construct the
677 .Dl vidcontrol -f iso
679 Likewise, you can also abbreviate the screen output map file name for
682 option if the file is found in
683 .Pa /usr/share/syscons/scrnmaps .
685 .Dl vidcontrol -l iso-8859-1_to_cp437
687 The above command will load
688 .Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm .
690 The following command will set-up a 100x37 raster text mode (useful for
693 .Dl vidcontrol -g 100x37 VESA_800x600
695 The following command will capture the contents of the first virtual
696 terminal video buffer, and redirect the output to the
700 .Dl vidcontrol -p < /dev/ttyv0 > shot.scr
702 The following command will dump contents of the fourth virtual terminal
704 to the standard output in the human readable format:
706 .Dl vidcontrol -P < /dev/ttyv3
727 .Em "Ports Collection" .
729 .An S\(/oren Schmidt Aq Mt sos@FreeBSD.org
730 .An Sascha Wildner Aq Mt saw@online.de
733 .An Maxim Sobolev Aq Mt sobomax@FreeBSD.org
734 .An Nik Clayton Aq Mt nik@FreeBSD.org