2 .\" vidcontrol - a utility for manipulating the syscons 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
34 .Op Fl i Cm adapter | mode
35 .Op Fl l Ar screen_map
38 .Op Fl r Ar foreground Ar background
41 .Op Fl T Cm xterm | cons25
42 .Op Fl t Ar N | Cm off
44 .Op Ar foreground Op Ar background
49 utility is used to set various options for the
52 such as video mode, colors, cursor shape, screen output map, font and screen
55 The following command line options are supported:
56 .Bl -tag -width indent
58 Select a new video mode.
59 The modes currently recognized are:
92 Alternatively, a mode can be specified with its number by using a mode name of
94 .Li MODE_ Ns Aq Ar NUMBER .
95 A list of valid mode numbers can be obtained with the
99 .Sx Video Mode Support
101 .It Ar foreground Op Ar background
102 Change colors when displaying text.
103 Specify the foreground color
105 .Dq vidcontrol white ) ,
106 or both a foreground and background colors
108 .Dq vidcontrol yellow blue ) .
111 command below to see available colors.
113 See the supported colors on a given platform.
117 This option may not be always supported by the video driver.
119 Clear the history buffer.
120 .It Fl c Cm normal | blink | destructive
121 Change the cursor appearance.
122 The cursor is either an inverting block
126 or it can be like the old hardware cursor
128 The latter is actually a simulation.
130 Print out current output screen map.
145 The font file can be either uuencoded or in raw binary format.
146 You can also use the menu-driven
148 command to load the font of your choice.
151 may be omitted, in this case
153 will try to guess it from the size of font file.
155 Note that older video cards, such as MDA and CGA, do not support
158 .Sx Video Mode Support
161 below and the man page for
166 of the text mode for the modes with selectable
168 Currently only raster modes, such as
172 .Sx Video Mode Support
177 Set the size of the history (scrollback) buffer to
181 Shows info about the current video adapter.
183 Shows the possible video modes with the current video hardware.
184 .It Fl l Ar screen_map
185 Install screen output map file from
190 Install default screen output map.
192 Sets the base character used to render the mouse pointer to
195 Switch the mouse pointer
199 Used together with the
201 daemon for text mode cut & paste functionality.
203 Capture the current contents of the video buffer corresponding
204 to the terminal device referred to by standard input.
207 utility writes contents of the video buffer to the standard
208 output in a raw binary format.
209 For details about that
211 .Sx Format of Video Buffer Dump
216 but dump contents of the video buffer in a plain text format
217 ignoring nonprintable characters and information about text
226 to dump full history buffer instead of visible portion of
227 the video buffer only.
228 .It Fl r Ar foreground background
229 Change reverse mode colors to
234 Turn vty switching on or off.
235 When vty switching is off,
236 attempts to switch to a different virtual terminal will fail.
237 (The default is to permit vty switching.)
238 This protection can be easily bypassed when the kernel is compiled with
242 However, you probably should not compile the kernel debugger on a box which
243 is supposed to be physically secure.
245 Set the current vty to
247 .It Fl T Cm xterm | cons25
248 Switch between xterm and cons25 style terminal emulation.
249 .It Fl t Ar N | Cm off
250 Set the screensaver timeout to
255 Use hexadecimal digits for output.
257 .Ss Video Mode Support
258 Note that not all modes listed above may be supported by the video
260 You can verify which mode is supported by the video hardware, using the
264 The VESA BIOS support must be linked to the kernel
265 or loaded as a KLD module if you wish to use VESA video modes
270 You need to compile your kernel with the
272 option if you wish to use VGA 90 column modes
276 Video modes other than 25 and 30 line modes may require specific size of font.
279 option above to load a font file to the kernel.
280 If the required size of font has not been loaded to the kernel,
282 will fail if the user attempts to set a new video mode.
284 .Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact
285 .Sy Modes Ta Sy Font size
286 .No 25 line modes Ta 8x16 (VGA), 8x14 (EGA)
287 .No 30 line modes Ta 8x16
288 .No 43 line modes Ta 8x8
289 .No 50 line modes Ta 8x8
290 .No 60 line modes Ta 8x8
293 It is better to always load all three sizes (8x8, 8x14 and 8x16)
296 You may set variables in
299 .Pa /etc/rc.conf.local
300 so that desired font files will be automatically loaded
301 when the system starts up.
304 If you want to use any of the raster text modes you need to recompile your
310 for more details on this kernel option.
311 .Ss Format of Video Buffer Dump
318 to capture the current contents of the video buffer.
321 utility writes version and additional information to the standard
322 output, followed by the contents of the video buffer.
324 VGA video memory is typically arranged in two byte tuples,
325 one per character position.
326 In each tuple, the first byte will be the character code,
327 and the second byte is the character's color attribute.
329 The VGA color attribute byte looks like this:
330 .Bl -column "X:X" "<00000000>" "width" "bright foreground color"
331 .Sy "bits# width meaning"
332 .Li "7 <X0000000> 1 character blinking"
333 .Li "6:4 <0XXX0000> 3 background color"
334 .Li "3 <0000X000> 1 bright foreground color"
335 .Li "2:0 <00000XXX> 3 foreground color"
338 Here is a list of the three bit wide base colors:
340 .Bl -hang -offset indent -compact
359 Base colors with bit 3 (the bright foreground flag) set:
361 .Bl -hang -offset indent -compact
380 For example, the two bytes
384 specify an uppercase A (character code 65), blinking
385 (bit 7 set) in yellow (bits 3:0) on a blue background
390 output contains a small header which includes additional
391 information which may be useful to utilities processing
394 The first 10 bytes are always arranged as follows:
395 .Bl -column "Byte range" "Contents" -offset indent
396 .It Sy "Byte Range Contents"
397 .It "1 thru 8 Literal text" Dq Li SCRSHOT_
398 .It "9 File format version number"
399 .It "10 Remaining number of bytes in the header"
402 Subsequent bytes depend on the version number.
403 .Bl -column "Version" "13 and up" -offset indent
404 .It Sy "Version Byte Meaning"
405 .It "1 11 Terminal width, in characters"
406 .It " 12 Terminal depth, in characters"
407 .It " 13 and up The snapshot data"
410 So a dump of an 80x25 screen would start (in hex)
411 .Bd -literal -offset indent
412 53 43 52 53 48 4f 54 5f 01 02 50 19
413 ----------------------- -- -- -- --
415 | | | `--- 80 decimal
416 | | `------ 2 remaining bytes of header data
417 | `--------- File format version 1
418 `------------------------ Literal "SCRSHOT_"
420 .Sh VIDEO OUTPUT CONFIGURATION
421 .Ss Boot Time Configuration
422 You may set the following variables in
425 .Pa /etc/rc.conf.local
426 in order to configure the video output at boot time.
428 .Bl -tag -width foo_bar_var -compact
430 Sets the timeout value for the
433 .It Ar font8x16 , font8x14 , font8x8
434 Specifies font files for the
438 Specifies a screen output map file for the
446 .Ss Driver Configuration
447 The video card driver may let you change default configuration
448 options, such as the default font, so that you do not need to set up
449 the options at boot time.
450 See video card driver manuals, (e.g.\&
454 .Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact
455 .It Pa /usr/share/syscons/fonts/*
457 .It Pa /usr/share/syscons/scrnmaps/*
458 screen output map files.
462 .Pa /usr/share/syscons/fonts/iso-8x16.fnt
467 .Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt
469 So long as the font file is in
470 .Pa /usr/share/syscons/fonts ,
471 you may abbreviate the file name as
474 .Dl vidcontrol -f 8x16 iso-8x16
476 Furthermore, you can also omit font size
479 .Dl vidcontrol -f iso-8x16
481 Moreover, the suffix specifying the font size can be also omitted; in
484 will use the size of the currently displayed font to construct the
487 .Dl vidcontrol -f iso
489 Likewise, you can also abbreviate the screen output map file name for
492 option if the file is found in
493 .Pa /usr/share/syscons/scrnmaps .
495 .Dl vidcontrol -l iso-8859-1_to_cp437
497 The above command will load
498 .Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm .
500 The following command will set-up a 100x37 raster text mode (useful for
503 .Dl vidcontrol -g 100x37 VESA_800x600
505 The following command will capture the contents of the first virtual
506 terminal video buffer, and redirect the output to the
510 .Dl vidcontrol -p < /dev/ttyv0 > shot.scr
512 The following command will dump contents of the fourth virtual terminal
514 to the standard output in the human readable format:
516 .Dl vidcontrol -P < /dev/ttyv3
536 .Em "Ports Collection" .
538 .An S\(/oren Schmidt Aq sos@FreeBSD.org
541 .An Maxim Sobolev Aq sobomax@FreeBSD.org ,
542 .An Nik Clayton Aq nik@FreeBSD.org