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 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 info about the current video adapter.
204 Shows the possible video modes with the current video hardware.
205 .It Fl l Ar screen_map
206 Install screen output map file from
212 (depending on which driver you use).
214 Install default screen output map.
216 Sets the base character used to render the mouse pointer to
219 Switch the mouse pointer
223 Used together with the
225 daemon for text mode cut & paste functionality.
227 Capture the current contents of the video buffer corresponding
228 to the terminal device referred to by standard input.
231 utility writes contents of the video buffer to the standard
232 output in a raw binary format.
233 For details about that
235 .Sx Format of Video Buffer Dump
240 but dump contents of the video buffer in a plain text format
241 ignoring nonprintable characters and information about text
250 to dump full history buffer instead of visible portion of
251 the video buffer only.
252 .It Fl r Ar foreground background
253 Change reverse mode colors to
258 Turn vty switching on or off.
259 When vty switching is off,
260 attempts to switch to a different virtual terminal will fail.
261 (The default is to permit vty switching.)
262 This protection can be easily bypassed when the kernel is compiled with
266 However, you probably should not compile the kernel debugger on a box which
267 is supposed to be physically secure.
269 Set the current vty to
271 .It Fl T Cm xterm | cons25
272 Switch between xterm and cons25 style terminal emulation.
273 .It Fl t Ar N | Cm off
274 Set the screensaver timeout to
279 Use hexadecimal digits for output.
281 .Ss Video Mode Support
282 Note that not all modes listed above may be supported by the video
284 You can verify which mode is supported by the video hardware, using the
288 The VESA BIOS support must be linked to the kernel
289 or loaded as a KLD module if you wish to use VESA video modes
294 You need to compile your kernel with the
296 option if you wish to use VGA 90 column modes
300 Video modes other than 25 and 30 line modes may require specific size of font.
303 option above to load a font file to the kernel.
304 If the required size of font has not been loaded to the kernel,
306 will fail if the user attempts to set a new video mode.
308 .Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact
309 .Sy Modes Ta Sy Font size
310 .No 25 line modes Ta 8x16 (VGA), 8x14 (EGA)
311 .No 30 line modes Ta 8x16
312 .No 43 line modes Ta 8x8
313 .No 50 line modes Ta 8x8
314 .No 60 line modes Ta 8x8
317 It is better to always load all three sizes (8x8, 8x14 and 8x16)
320 You may set variables in
323 .Pa /etc/rc.conf.local
324 so that desired font files will be automatically loaded
325 when the system starts up.
328 If you want to use any of the raster text modes you need to recompile your
336 (depending on which driver you use)
337 for more details on this kernel option.
338 .Ss Format of Video Buffer Dump
343 .\" is it supported on vt(4)???
348 to capture the current contents of the video buffer.
351 utility writes version and additional information to the standard
352 output, followed by the contents of the video buffer.
354 VGA video memory is typically arranged in two byte tuples,
355 one per character position.
356 In each tuple, the first byte will be the character code,
357 and the second byte is the character's color attribute.
359 The VGA color attribute byte looks like this:
360 .Bl -column "X:X" "<00000000>" "width" "bright foreground color"
361 .Sy "bits# width meaning"
362 .Li "7 <X0000000> 1 character blinking"
363 .Li "6:4 <0XXX0000> 3 background color"
364 .Li "3 <0000X000> 1 bright foreground color"
365 .Li "2:0 <00000XXX> 3 foreground color"
368 Here is a list of the three bit wide base colors:
370 .Bl -hang -offset indent -compact
389 Base colors with bit 3 (the bright foreground flag) set:
391 .Bl -hang -offset indent -compact
410 For example, the two bytes
414 specify an uppercase A (character code 65), blinking
415 (bit 7 set) in yellow (bits 3:0) on a blue background
420 output contains a small header which includes additional
421 information which may be useful to utilities processing
424 The first 10 bytes are always arranged as follows:
425 .Bl -column "Byte range" "Contents" -offset indent
426 .It Sy "Byte Range Contents"
427 .It "1 thru 8 Literal text" Dq Li SCRSHOT_
428 .It "9 File format version number"
429 .It "10 Remaining number of bytes in the header"
432 Subsequent bytes depend on the version number.
433 .Bl -column "Version" "13 and up" -offset indent
434 .It Sy "Version Byte Meaning"
435 .It "1 11 Terminal width, in characters"
436 .It " 12 Terminal depth, in characters"
437 .It " 13 and up The snapshot data"
440 So a dump of an 80x25 screen would start (in hex)
441 .Bd -literal -offset indent
442 53 43 52 53 48 4f 54 5f 01 02 50 19
443 ----------------------- -- -- -- --
445 | | | `--- 80 decimal
446 | | `------ 2 remaining bytes of header data
447 | `--------- File format version 1
448 `------------------------ Literal "SCRSHOT_"
450 .Sh VIDEO OUTPUT CONFIGURATION
451 .Ss Boot Time Configuration
452 You may set the following variables in
455 .Pa /etc/rc.conf.local
456 in order to configure the video output at boot time.
458 .Bl -tag -width foo_bar_var -compact
460 Sets the timeout value for the
463 .It Ar font8x16 , font8x14 , font8x8
464 Specifies font files for the
468 Specifies a screen output map file for the
476 .Ss Driver Configuration
477 The video card driver may let you change default configuration
478 options, such as the default font, so that you do not need to set up
479 the options at boot time.
480 See video card driver manuals, (e.g.\&
484 .Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact
485 .It Pa /usr/share/syscons/fonts/*
486 .It Pa /usr/share/vt/fonts/*
488 .It Pa /usr/share/syscons/scrnmaps/*
489 screen output map files (relevant for
495 .Pa /usr/share/syscons/fonts/iso-8x16.fnt
500 .Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt
502 So long as the font file is in
503 .Pa /usr/share/syscons/fonts
504 (if using syscons) or
505 .Pa /usr/share/vt/fonts
507 you may abbreviate the file name as
510 .Dl vidcontrol -f 8x16 iso-8x16
512 Furthermore, you can also omit font size
515 .Dl vidcontrol -f iso-8x16
517 Moreover, the suffix specifying the font size can be also omitted; in
520 will use the size of the currently displayed font to construct the
523 .Dl vidcontrol -f iso
525 Likewise, you can also abbreviate the screen output map file name for
528 option if the file is found in
529 .Pa /usr/share/syscons/scrnmaps .
531 .Dl vidcontrol -l iso-8859-1_to_cp437
533 The above command will load
534 .Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm .
536 The following command will set-up a 100x37 raster text mode (useful for
539 .Dl vidcontrol -g 100x37 VESA_800x600
541 The following command will capture the contents of the first virtual
542 terminal video buffer, and redirect the output to the
546 .Dl vidcontrol -p < /dev/ttyv0 > shot.scr
548 The following command will dump contents of the fourth virtual terminal
550 to the standard output in the human readable format:
552 .Dl vidcontrol -P < /dev/ttyv3
573 .Em "Ports Collection" .
575 .An S\(/oren Schmidt Aq sos@FreeBSD.org
578 .An Maxim Sobolev Aq sobomax@FreeBSD.org ,
579 .An Nik Clayton Aq nik@FreeBSD.org