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
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
54 such as video mode, colors, cursor shape, screen output map, font and screen
56 Only a small subset of options is supported by
58 Unsupported options lead to error messages, typically including
59 the text "Inappropriate ioctl for device".
61 The following command line options are supported:
62 .Bl -tag -width indent
64 Select a new video mode.
65 The modes currently recognized are:
98 Alternatively, a mode can be specified with its number by using a mode name of
100 .Li MODE_ Ns Aq Ar NUMBER .
101 A list of valid mode numbers can be obtained with the
105 .Sx Video Mode Support
107 .It Ar foreground Op Ar background
108 Change colors when displaying text.
109 Specify the foreground color
111 .Dq vidcontrol white ) ,
112 or both a foreground and background colors
114 .Dq vidcontrol yellow blue ) .
117 command below to see available colors.
119 See the supported colors on a given platform.
123 This option may not be always supported by the video driver.
125 Clear the history buffer.
126 .It Fl c Cm normal | blink | destructive
127 Change the cursor appearance.
128 The cursor is either an inverting block
132 or it can be like the old hardware cursor
134 The latter is actually a simulation.
136 Print out current output screen map.
151 The font file can be either uuencoded or in raw binary format.
152 You can also use the menu-driven
154 command to load the font of your choice.
157 may be omitted, in this case
159 will try to guess it from the size of font file.
161 Note that older video cards, such as MDA and CGA, do not support
164 .Sx Video Mode Support
167 below and the man page for either
171 (depending on which driver you use).
175 of the text mode for the modes with selectable
177 Currently only raster modes, such as
181 .Sx Video Mode Support
186 Set the size of the history (scrollback) buffer to
190 Shows info about the current video adapter.
192 Shows the possible video modes with the current video hardware.
193 .It Fl l Ar screen_map
194 Install screen output map file from
200 (depending on which driver you use).
202 Install default screen output map.
204 Sets the base character used to render the mouse pointer to
207 Switch the mouse pointer
211 Used together with the
213 daemon for text mode cut & paste functionality.
215 Capture the current contents of the video buffer corresponding
216 to the terminal device referred to by standard input.
219 utility writes contents of the video buffer to the standard
220 output in a raw binary format.
221 For details about that
223 .Sx Format of Video Buffer Dump
228 but dump contents of the video buffer in a plain text format
229 ignoring nonprintable characters and information about text
238 to dump full history buffer instead of visible portion of
239 the video buffer only.
240 .It Fl r Ar foreground background
241 Change reverse mode colors to
246 Turn vty switching on or off.
247 When vty switching is off,
248 attempts to switch to a different virtual terminal will fail.
249 (The default is to permit vty switching.)
250 This protection can be easily bypassed when the kernel is compiled with
254 However, you probably should not compile the kernel debugger on a box which
255 is supposed to be physically secure.
257 Set the current vty to
259 .It Fl T Cm xterm | cons25
260 Switch between xterm and cons25 style terminal emulation.
261 .It Fl t Ar N | Cm off
262 Set the screensaver timeout to
267 Use hexadecimal digits for output.
269 .Ss Video Mode Support
270 Note that not all modes listed above may be supported by the video
272 You can verify which mode is supported by the video hardware, using the
276 The VESA BIOS support must be linked to the kernel
277 or loaded as a KLD module if you wish to use VESA video modes
282 You need to compile your kernel with the
284 option if you wish to use VGA 90 column modes
288 Video modes other than 25 and 30 line modes may require specific size of font.
291 option above to load a font file to the kernel.
292 If the required size of font has not been loaded to the kernel,
294 will fail if the user attempts to set a new video mode.
296 .Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact
297 .Sy Modes Ta Sy Font size
298 .No 25 line modes Ta 8x16 (VGA), 8x14 (EGA)
299 .No 30 line modes Ta 8x16
300 .No 43 line modes Ta 8x8
301 .No 50 line modes Ta 8x8
302 .No 60 line modes Ta 8x8
305 It is better to always load all three sizes (8x8, 8x14 and 8x16)
308 You may set variables in
311 .Pa /etc/rc.conf.local
312 so that desired font files will be automatically loaded
313 when the system starts up.
316 If you want to use any of the raster text modes you need to recompile your
324 (depending on which driver you use)
325 for more details on this kernel option.
326 .Ss Format of Video Buffer Dump
331 .\" is it supported on vt(4)???
336 to capture the current contents of the video buffer.
339 utility writes version and additional information to the standard
340 output, followed by the contents of the video buffer.
342 VGA video memory is typically arranged in two byte tuples,
343 one per character position.
344 In each tuple, the first byte will be the character code,
345 and the second byte is the character's color attribute.
347 The VGA color attribute byte looks like this:
348 .Bl -column "X:X" "<00000000>" "width" "bright foreground color"
349 .Sy "bits# width meaning"
350 .Li "7 <X0000000> 1 character blinking"
351 .Li "6:4 <0XXX0000> 3 background color"
352 .Li "3 <0000X000> 1 bright foreground color"
353 .Li "2:0 <00000XXX> 3 foreground color"
356 Here is a list of the three bit wide base colors:
358 .Bl -hang -offset indent -compact
377 Base colors with bit 3 (the bright foreground flag) set:
379 .Bl -hang -offset indent -compact
398 For example, the two bytes
402 specify an uppercase A (character code 65), blinking
403 (bit 7 set) in yellow (bits 3:0) on a blue background
408 output contains a small header which includes additional
409 information which may be useful to utilities processing
412 The first 10 bytes are always arranged as follows:
413 .Bl -column "Byte range" "Contents" -offset indent
414 .It Sy "Byte Range Contents"
415 .It "1 thru 8 Literal text" Dq Li SCRSHOT_
416 .It "9 File format version number"
417 .It "10 Remaining number of bytes in the header"
420 Subsequent bytes depend on the version number.
421 .Bl -column "Version" "13 and up" -offset indent
422 .It Sy "Version Byte Meaning"
423 .It "1 11 Terminal width, in characters"
424 .It " 12 Terminal depth, in characters"
425 .It " 13 and up The snapshot data"
428 So a dump of an 80x25 screen would start (in hex)
429 .Bd -literal -offset indent
430 53 43 52 53 48 4f 54 5f 01 02 50 19
431 ----------------------- -- -- -- --
433 | | | `--- 80 decimal
434 | | `------ 2 remaining bytes of header data
435 | `--------- File format version 1
436 `------------------------ Literal "SCRSHOT_"
438 .Sh VIDEO OUTPUT CONFIGURATION
439 .Ss Boot Time Configuration
440 You may set the following variables in
443 .Pa /etc/rc.conf.local
444 in order to configure the video output at boot time.
446 .Bl -tag -width foo_bar_var -compact
448 Sets the timeout value for the
451 .It Ar font8x16 , font8x14 , font8x8
452 Specifies font files for the
456 Specifies a screen output map file for the
464 .Ss Driver Configuration
465 The video card driver may let you change default configuration
466 options, such as the default font, so that you do not need to set up
467 the options at boot time.
468 See video card driver manuals, (e.g.\&
472 .Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact
473 .It Pa /usr/share/syscons/fonts/*
474 .It Pa /usr/share/vt/fonts/*
476 .It Pa /usr/share/syscons/scrnmaps/*
477 screen output map files (relevant for
483 .Pa /usr/share/syscons/fonts/iso-8x16.fnt
488 .Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt
490 So long as the font file is in
491 .Pa /usr/share/syscons/fonts
492 (if using syscons) or
493 .Pa /usr/share/vt/fonts
495 you may abbreviate the file name as
498 .Dl vidcontrol -f 8x16 iso-8x16
500 Furthermore, you can also omit font size
503 .Dl vidcontrol -f iso-8x16
505 Moreover, the suffix specifying the font size can be also omitted; in
508 will use the size of the currently displayed font to construct the
511 .Dl vidcontrol -f iso
513 Likewise, you can also abbreviate the screen output map file name for
516 option if the file is found in
517 .Pa /usr/share/syscons/scrnmaps .
519 .Dl vidcontrol -l iso-8859-1_to_cp437
521 The above command will load
522 .Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm .
524 The following command will set-up a 100x37 raster text mode (useful for
527 .Dl vidcontrol -g 100x37 VESA_800x600
529 The following command will capture the contents of the first virtual
530 terminal video buffer, and redirect the output to the
534 .Dl vidcontrol -p < /dev/ttyv0 > shot.scr
536 The following command will dump contents of the fourth virtual terminal
538 to the standard output in the human readable format:
540 .Dl vidcontrol -P < /dev/ttyv3
561 .Em "Ports Collection" .
563 .An S\(/oren Schmidt Aq sos@FreeBSD.org
566 .An Maxim Sobolev Aq sobomax@FreeBSD.org ,
567 .An Nik Clayton Aq nik@FreeBSD.org