system console control and configuration
utility is used to set various
options for the
console driver, such as video mode, colors, cursor shape, screen output map,
font and screen saver timeout. Only a small subset of options is supported by
Unsupported options lead to error messages, typically including the text
"Inappropriate ioctl for device".
The following command line options are supported:
- Select a new video mode. The modes currently recognized are:
VESA_132x60. The raster text mode
VESA_800x600 can also be chosen.
Alternatively, a mode can be specified with its number by using a mode
name of the form
A list of valid mode numbers can be obtained with the
mode option. See
Video Mode Support
- Change colors when displaying text. Specify the foreground color (e.g.
“vidcontrol white”), or both a foreground and background
colors (e.g. “vidcontrol yellow blue”). Use the
show command below to see available
- See the supported colors on a given platform.
- Set border color to color. This option
may not be always supported by the video driver.
- Clear the history buffer.
- Change the cursor appearance. The change is specified by a non-empty
comma-separated list of
setting overrides or modifies previous
ones in left to right order.
The following override
The following modifier
- Set to a block covering 1 character cell, with a
configuration-dependent coloring that should be at worst inverse
- Set to a blinking sub-block with
height scanlines starting at
base. The name
“destructive” is bad for backwards compatibility. This
setting should not force
destructiveness, and it now only gives destructiveness in some
configurations (typically for hardware cursors in text mode). Blinking
limits destructiveness. This
setting should now be spelled
A non-blinking destructive cursor would be unusable, so old versions
vidcontrol didn't support it,
and this version doesn't have an override for it.
- Set the specified scanline parameters. These parameters are only
value is an integer in any base
height to 0 turns off the
noblock mode. Negative
values are silently ignored. Positive
values are clamped to fit in the
character cell when the cursor is drawn.
The following (non-sticky) flags control application of the
- Set or clear the blinking attribute. This is not quite backwards
compatible. In old versions of
blink was an override to a blinking
- Set or clear the
This attribute is the inverse of the flag
CONS_CHAR_CURSOR in the
implementation. It deactivates the scanline parameters, and expresses
a preference for using a simpler method of implementation. Its inverse
does the opposite. When the scanline parameters give a full block,
this attribute reduces to a method selection bit. The
block method tends to give better
- Set or clear the hidden attribute.
height to the (character) cursor's
list of preferred colors instead of its shape. Beware that the color
numbers are raw VGA palette indexes, not ANSI color numbers. The
indexes are reduced mod 8, 16 or 256, or ignored, depending on the
video mode and renderer.
- Colors for the mouse cursor in graphics mode. Like
charcolors, except there is no
preference or sequence;
the mouse border color and
gives the mouse interior color. Together with
charcolors, this gives 2 selection
bits which select between only 3 of 4 sub-destinations of the 4
destinations selected by
local (by ignoring
charcolors is also set).
- Apply the changes to the default settings and then to the active
settings, instead of only to the active settings. Together with
local, this gives 2 selection bits
which select between 4 destinations.
- Ignore any changes to the
- Apply the changes to the current vty. The default is to apply them to
a global place and copy from there to all vtys.
- Reset everything. The default is to not reset. When the
local parameter is specified, the
current local settings are reset to default local settings. Otherwise,
the current global settings are reset to default global settings and
then copied to the current and default settings for all vtys.
- Show the current changes.
- Print out current output screen map.
- Load font file for
size (currently, only
8x16). The font file can be either
uuencoded or in raw binary format. You can also use the menu-driven
command to load the font of your choice.
Size may be omitted, in this case
vidcontrol will try to guess it from
the size of font file.
both size and
font can be omitted, and the default font
will be loaded.
Note that older video cards, such as MDA and CGA, do not support software
font. See also Video
Mode Support and
EXAMPLES below and the man
page for either
(depending on which driver you use).
- Set the geometry of the text mode for the
modes with selectable geometry. Currently only raster modes, such as
VESA_800x600, support this option. See
also Video Mode
Support and EXAMPLES
- Set the size of the history (scrollback) buffer to
- Shows the active vty number.
- Shows info about the current video adapter.
- Shows the possible video modes with the current video hardware.
- Install screen output map file from
screen_map. See also
(depending on which driver you use).
- Install default screen output map.
- Sets the base character used to render the mouse pointer to
- Switch the mouse pointer
off. Used together with the
daemon for text mode cut & paste functionality.
- Capture the current contents of the video buffer corresponding to the
terminal device referred to by standard input. The
vidcontrol utility writes contents of
the video buffer to the standard output in a raw binary format. For
details about that format see
Video Buffer Dump below.
- Same as
-p, but dump contents of the
video buffer in a plain text format ignoring nonprintable characters and
information about text attributes.
- When used with
-P, it instructs
vidcontrol to dump full history buffer
instead of visible portion of the video buffer only.
- Change reverse mode colors to foreground
- Turn vty switching on or off. When vty switching is off, attempts to
switch to a different virtual terminal will fail. (The default is to
permit vty switching.) This protection can be easily bypassed when the
kernel is compiled with the
However, you probably should not compile the kernel debugger on a box
which is supposed to be physically secure.
- Set the active vty to number.
- Switch between xterm and cons25 style terminal emulation.
- Set the screensaver timeout to N seconds,
or turns it
- Use hexadecimal digits for output.
Note that not all modes listed above may be supported by the video hardware. You
can verify which mode is supported by the video hardware, using the
The VESA BIOS support must be linked to the kernel or loaded as a KLD module if
you wish to use VESA video modes or 132 column modes (see
You need to compile your kernel with the
option if you wish to use VGA 90
column modes (see
Video modes other than 25 and 30 line modes may require specific size of font.
option above to load a font file to
the kernel. If the required size of font has not been loaded to the kernel,
will fail if the user attempts
to set a new video mode.
It is better to always load all three sizes (8x8, 8x14 and 8x16) of the same
You may set variables in /etc/rc.conf
so that desired font
files will be automatically loaded when the system starts up. See below.
If you want to use any of the raster text modes you need to recompile your
kernel with the
(depending on which driver you use) for more details on this kernel option.
utility uses the
to capture the current contents of the video buffer. The
utility writes version and
additional information to the standard output, followed by the contents of the
VGA video memory is typically arranged in two byte tuples, one per character
position. In each tuple, the first byte will be the character code, and the
second byte is the character's color attribute.
The VGA color attribute byte looks like this:
||bright foreground color
Here is a list of the three bit wide base colors:
- Light Grey
Base colors with bit 3 (the bright foreground flag) set:
- Dark Grey
- Light Blue
- Light Green
- Light Cyan
- Light Red
- Light Magenta
For example, the two bytes
specify an uppercase A (character code 65), blinking (bit 7 set) in yellow (bits
3:0) on a blue background (bits 6:4).
output contains a small header
which includes additional information which may be useful to utilities
processing the output.
The first 10 bytes are always arranged as follows:
|1 thru 8
||Literal text “
||File format version number
||Remaining number of bytes in the header
Subsequent bytes depend on the version number.
||Terminal width, in characters
||Terminal depth, in characters
||13 and up
||The snapshot data
So a dump of an 80x25 screen would start (in hex)
53 43 52 53 48 4f 54 5f 01 02 50 19
----------------------- -- -- -- --
| | | | ` 25 decimal
| | | `--- 80 decimal
| | `------ 2 remaining bytes of header data
| `--------- File format version 1
`------------------------ Literal "SCRSHOT_"
You may set the following variables in
in order to configure
the video output at boot time.
- Sets the timeout value for the
- Specifies font files for the
- Specifies a screen output map file for the
for more details.
The video card driver may let you change default configuration options, such as
the default font, so that you do not need to set up the options at boot time.
See video card driver manuals, (e.g.
- font files.
- screen output map files (relevant for
If you want to load
the kernel, run
vidcontrol -f 8x16
So long as the font file is in
(if using syscons)
(if using vt), you
may abbreviate the file name as iso-8x16
vidcontrol -f 8x16
Furthermore, you can also omit font size
vidcontrol -f iso-8x16
Moreover, the suffix specifying the font size can be also omitted; in this case,
will use the size of the
currently displayed font to construct the suffix:
vidcontrol -f iso
Likewise, you can also abbreviate the screen output map file name for the
option if the file is found in
The above command will load
The following command will set-up a 100x37 raster text mode (useful for some LCD
vidcontrol -g 100x37
The following command will capture the contents of the first virtual terminal
video buffer, and redirect the output to the
vidcontrol -p < /dev/ttyv0 >
The following command will dump contents of the fourth virtual terminal video
buffer to the standard output in the human readable format:
vidcontrol -P <
The various scr2*
utilities in the
categories of the