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 Cm normal | blink | destructive
129 Change the cursor appearance.
130 The cursor is either an inverting block
134 or it can be like the old hardware cursor
136 The latter is actually a simulation.
138 Print out current output screen map.
155 The font file can be either uuencoded or in raw binary format.
156 You can also use the menu-driven
158 command to load the font of your choice.
161 may be omitted, in this case
163 will try to guess it from the size of font file.
171 can be omitted, and the default font will be loaded.
173 Note that older video cards, such as MDA and CGA, do not support
176 .Sx Video Mode Support
179 below and the man page for either
183 (depending on which driver you use).
187 of the text mode for the modes with selectable
189 Currently only raster modes, such as
193 .Sx Video Mode Support
198 Set the size of the history (scrollback) buffer to
202 Shows the active vty number.
204 Shows info about the current video adapter.
206 Shows the possible video modes with the current video hardware.
207 .It Fl l Ar screen_map
208 Install screen output map file from
214 (depending on which driver you use).
216 Install default screen output map.
218 Sets the base character used to render the mouse pointer to
221 Switch the mouse pointer
225 Used together with the
227 daemon for text mode cut & paste functionality.
229 Capture the current contents of the video buffer corresponding
230 to the terminal device referred to by standard input.
233 utility writes contents of the video buffer to the standard
234 output in a raw binary format.
235 For details about that
237 .Sx Format of Video Buffer Dump
242 but dump contents of the video buffer in a plain text format
243 ignoring nonprintable characters and information about text
252 to dump full history buffer instead of visible portion of
253 the video buffer only.
254 .It Fl r Ar foreground background
255 Change reverse mode colors to
260 Turn vty switching on or off.
261 When vty switching is off,
262 attempts to switch to a different virtual terminal will fail.
263 (The default is to permit vty switching.)
264 This protection can be easily bypassed when the kernel is compiled with
268 However, you probably should not compile the kernel debugger on a box which
269 is supposed to be physically secure.
271 Set the active vty to
273 .It Fl T Cm xterm | cons25
274 Switch between xterm and cons25 style terminal emulation.
275 .It Fl t Ar N | Cm off
276 Set the screensaver timeout to
281 Use hexadecimal digits for output.
283 .Ss Video Mode Support
284 Note that not all modes listed above may be supported by the video
286 You can verify which mode is supported by the video hardware, using the
290 The VESA BIOS support must be linked to the kernel
291 or loaded as a KLD module if you wish to use VESA video modes
296 You need to compile your kernel with the
298 option if you wish to use VGA 90 column modes
302 Video modes other than 25 and 30 line modes may require specific size of font.
305 option above to load a font file to the kernel.
306 If the required size of font has not been loaded to the kernel,
308 will fail if the user attempts to set a new video mode.
310 .Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact
311 .Sy Modes Ta Sy Font size
312 .No 25 line modes Ta 8x16 (VGA), 8x14 (EGA)
313 .No 30 line modes Ta 8x16
314 .No 43 line modes Ta 8x8
315 .No 50 line modes Ta 8x8
316 .No 60 line modes Ta 8x8
319 It is better to always load all three sizes (8x8, 8x14 and 8x16)
322 You may set variables in
325 .Pa /etc/rc.conf.local
326 so that desired font files will be automatically loaded
327 when the system starts up.
330 If you want to use any of the raster text modes you need to recompile your
338 (depending on which driver you use)
339 for more details on this kernel option.
340 .Ss Format of Video Buffer Dump
345 .\" is it supported on vt(4)???
350 to capture the current contents of the video buffer.
353 utility writes version and additional information to the standard
354 output, followed by the contents of the video buffer.
356 VGA video memory is typically arranged in two byte tuples,
357 one per character position.
358 In each tuple, the first byte will be the character code,
359 and the second byte is the character's color attribute.
361 The VGA color attribute byte looks like this:
362 .Bl -column "X:X" "<00000000>" "width" "bright foreground color"
363 .Sy "bits# width meaning"
364 .Li "7 <X0000000> 1 character blinking"
365 .Li "6:4 <0XXX0000> 3 background color"
366 .Li "3 <0000X000> 1 bright foreground color"
367 .Li "2:0 <00000XXX> 3 foreground color"
370 Here is a list of the three bit wide base colors:
372 .Bl -hang -offset indent -compact
391 Base colors with bit 3 (the bright foreground flag) set:
393 .Bl -hang -offset indent -compact
412 For example, the two bytes
416 specify an uppercase A (character code 65), blinking
417 (bit 7 set) in yellow (bits 3:0) on a blue background
422 output contains a small header which includes additional
423 information which may be useful to utilities processing
426 The first 10 bytes are always arranged as follows:
427 .Bl -column "Byte range" "Contents" -offset indent
428 .It Sy "Byte Range Contents"
429 .It "1 thru 8 Literal text" Dq Li SCRSHOT_
430 .It "9 File format version number"
431 .It "10 Remaining number of bytes in the header"
434 Subsequent bytes depend on the version number.
435 .Bl -column "Version" "13 and up" -offset indent
436 .It Sy "Version Byte Meaning"
437 .It "1 11 Terminal width, in characters"
438 .It " 12 Terminal depth, in characters"
439 .It " 13 and up The snapshot data"
442 So a dump of an 80x25 screen would start (in hex)
443 .Bd -literal -offset indent
444 53 43 52 53 48 4f 54 5f 01 02 50 19
445 ----------------------- -- -- -- --
447 | | | `--- 80 decimal
448 | | `------ 2 remaining bytes of header data
449 | `--------- File format version 1
450 `------------------------ Literal "SCRSHOT_"
452 .Sh VIDEO OUTPUT CONFIGURATION
453 .Ss Boot Time Configuration
454 You may set the following variables in
457 .Pa /etc/rc.conf.local
458 in order to configure the video output at boot time.
460 .Bl -tag -width foo_bar_var -compact
462 Sets the timeout value for the
465 .It Ar font8x16 , font8x14 , font8x8
466 Specifies font files for the
470 Specifies a screen output map file for the
478 .Ss Driver Configuration
479 The video card driver may let you change default configuration
480 options, such as the default font, so that you do not need to set up
481 the options at boot time.
482 See video card driver manuals, (e.g.\&
486 .Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact
487 .It Pa /usr/share/syscons/fonts/*
488 .It Pa /usr/share/vt/fonts/*
490 .It Pa /usr/share/syscons/scrnmaps/*
491 screen output map files (relevant for
497 .Pa /usr/share/syscons/fonts/iso-8x16.fnt
502 .Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt
504 So long as the font file is in
505 .Pa /usr/share/syscons/fonts
506 (if using syscons) or
507 .Pa /usr/share/vt/fonts
509 you may abbreviate the file name as
512 .Dl vidcontrol -f 8x16 iso-8x16
514 Furthermore, you can also omit font size
517 .Dl vidcontrol -f iso-8x16
519 Moreover, the suffix specifying the font size can be also omitted; in
522 will use the size of the currently displayed font to construct the
525 .Dl vidcontrol -f iso
527 Likewise, you can also abbreviate the screen output map file name for
530 option if the file is found in
531 .Pa /usr/share/syscons/scrnmaps .
533 .Dl vidcontrol -l iso-8859-1_to_cp437
535 The above command will load
536 .Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm .
538 The following command will set-up a 100x37 raster text mode (useful for
541 .Dl vidcontrol -g 100x37 VESA_800x600
543 The following command will capture the contents of the first virtual
544 terminal video buffer, and redirect the output to the
548 .Dl vidcontrol -p < /dev/ttyv0 > shot.scr
550 The following command will dump contents of the fourth virtual terminal
552 to the standard output in the human readable format:
554 .Dl vidcontrol -P < /dev/ttyv3
575 .Em "Ports Collection" .
577 .An S\(/oren Schmidt Aq Mt sos@FreeBSD.org
578 .An Sascha Wildner Aq Mt saw@online.de
581 .An Maxim Sobolev Aq Mt sobomax@FreeBSD.org
582 .An Nik Clayton Aq Mt nik@FreeBSD.org