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.
14 .\" $FreeBSD: src/usr.sbin/vidcontrol/vidcontrol.1,v 1.24.2.14 2002/09/15 22:31:50 dd Exp $
15 .\" $DragonFly: src/usr.sbin/vidcontrol/vidcontrol.1,v 1.3 2004/04/25 06:35:32 dillon Exp $
22 .Nd system console control and configuration utility
27 .Op Fl c Ar appearance
35 .Op Fl i Cm adapter | mode
36 .Op Fl l Ar screen_map
39 .Op Fl r Ar foreground Ar background
42 .Op Fl t Ar N | Cm off
44 .Op Ar foreground Op Ar background
49 command 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
95 A list of valid mode numbers can be obtained with the
98 .Sx Video Mode Support
100 .It Ar foreground Op Ar background
101 Change colors when displaying text.
102 Specify the foreground color
104 .Dq vidcontrol white ) ,
105 or both a foreground and background colors
107 .Dq vidcontrol yellow blue ) .
110 command below to see available colors.
112 See the supported colors on a given platform.
116 This option may not be always supported by the video driver.
118 Clear the history buffer.
119 .It Fl c Cm normal | blink | destructive
120 Change the cursor appearance.
121 The cursor is either an inverting block
125 or it can be like the old hardware cursor
127 The latter is actually a simulation.
129 Print out current output screen map.
144 The font file can be either uuencoded or in raw binary format.
145 You can also use the menu-driven
147 command to load the font of your choice.
150 may be omitted, in this case
152 will try to guess it from the size of font file.
154 Note that older video cards, such as MDA and CGA, do not support
157 .Sx Video Mode Support
160 below and the man page for
165 of the text mode for the modes with selectable
167 Currently only raster modes, such as
171 .Sx Video Mode Support
176 Set the size of the history (scrollback) buffer to
180 Shows info about the current video adapter.
182 Shows the possible video modes with the current video hardware.
183 .It Fl l Ar screen_map
184 Install screen output map file from
189 Install default screen output map.
191 Sets the base character used to render the mouse pointer to
194 Switch the mouse pointer
198 Used together with the
200 daemon for text mode cut & paste functionality.
202 Capture the current contents of the video buffer corresponding
203 to the terminal device referred to by standard input.
206 utility writes contents of the video buffer to the standard
207 output in a raw binary format.
208 For details about that
210 .Sx Format of Video Buffer Dump
215 but dump contents of the video buffer in a plain text format
216 ignoring nonprintable characters and information about text
218 .It Fl r Ar foreground background
219 Change reverse mode colors to
224 Turn vty switching on or off.
225 When vty switching is off,
226 attempts to switch to a different virtual terminal will fail.
227 (The default is to permit vty switching.)
229 Set the current vty to
231 .It Fl t Ar N | Cm off
232 Set the screensaver timeout to
237 Use hexadecimal digits for output.
239 .Ss Video Mode Support
240 Note that not all modes listed above may be supported by the video
242 You can verify which mode is supported by the video hardware, using the
246 The VESA BIOS support must be linked to the kernel
247 or loaded as a KLD module if you wish to use VESA video modes
252 You need to compile your kernel with the
254 option if you wish to use VGA 90 column modes
258 Video modes other than 25 and 30 line modes may require specific size of font.
261 option above to load a font file to the kernel.
262 If the required size of font has not been loaded to the kernel,
264 will fail if the user attempts to set a new video mode.
266 .Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact
267 .Sy Modes Ta Sy Font size
268 .Li 25 line modes Ta 8x16 (VGA), 8x14 (EGA)
269 .Li 30 line modes Ta 8x16
270 .Li 43 line modes Ta 8x8
271 .Li 50 line modes Ta 8x8
272 .Li 60 line modes Ta 8x8
275 It is better to always load all three sizes (8x8, 8x14 and 8x16)
278 You may set variables in
281 .Pa /etc/rc.conf.local
282 so that desired font files will be automatically loaded
283 when the system starts up.
286 If you want to use any of the raster text modes you need to recompile your
292 for more details on this kernel option.
293 .Ss Format of Video Buffer Dump
300 to capture the current contents of the video buffer.
303 utility writes version and additional information to the standard
304 output, followed by the contents of the terminal device.
306 PC video memory is typically arranged in two byte tuples,
307 one per character position.
308 In each tuple, the first byte
309 will be the character code, and the second byte is the
310 character's color attribute.
312 The color attribute byte is further broken down in to the
313 low nibble, which specifies which of 16 different foreground
314 colors is active, and the high nibble, which specifies which
315 of 16 different background colors is active.
317 .Bl -hang -offset indent -compact
352 It can be seen that the last 8 colors are brighter
353 versions of the first 8.
355 For example, the two bytes
359 specify an uppercase A (character code 65), in
360 yellow (low nibble 15) on a light blue background
365 output contains a small header which includes additional
366 information which may be useful to utilities processing
369 The first 10 bytes are always arranged as follows:
370 .Bl -column "Byte range" "Contents" -offset indent
371 .It Sy "Byte Range Contents"
372 .It "1 thru 8 Literal text" Dq Li SCRSHOT_
373 .It "9 File format version number"
374 .It "10 Remaining number of bytes in the header"
377 Subsequent bytes depend on the version number.
378 .Bl -column "Version" "13 and up" -offset indent
379 .It Sy "Version Byte Meaning"
380 .It "1 11 Terminal width, in characters"
381 .It " 12 Terminal depth, in characters"
382 .It " 13 and up The snapshot data"
385 So a dump of an 80x25 screen would start (in hex)
386 .Bd -literal -offset indent
387 53 43 52 53 48 4f 54 5f 01 02 50 19
388 ----------------------- -- -- -- --
390 | | | `--- 80 decimal
391 | | `------ 2 remaining bytes of header data
392 | `--------- File format version 1
393 `------------------------ Literal "SCRSHOT_"
395 .Sh VIDEO OUTPUT CONFIGURATION
396 .Ss Boot Time Configuration
397 You may set the following variables in
400 .Pa /etc/rc.conf.local
401 in order to configure the video output at boot time.
403 .Bl -tag -width foo_bar_var -compact
405 Sets the timeout value for the
408 .It Ar font8x16 , font8x14 , font8x8
409 Specifies font files for the
413 Specifies a screen output map file for the
421 .Ss Driver Configuration
422 The video card driver may let you change default configuration
423 options, such as the default font, so that you do not need to set up
424 the options at boot time.
425 See video card driver manuals, (e.g.\&
429 .Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact
430 .It Pa /usr/share/syscons/fonts/*
432 .It Pa /usr/share/syscons/scrnmaps/*
433 screen output map files.
437 .Pa /usr/share/syscons/fonts/iso-8x16.fnt
442 .Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt
444 So long as the font file is in
445 .Pa /usr/share/syscons/fonts ,
446 you may abbreviate the file name as
449 .Dl vidcontrol -f 8x16 iso-8x16
451 Furthermore, you can also omit font size
454 .Dl vidcontrol -f iso-8x16
456 Moreover, the suffix specifying the font size can be also omitted; in
459 will use the size of the currently displayed font to construct the
462 .Dl vidcontrol -f iso
464 Likewise, you can also abbreviate the screen output map file name for
467 option if the file is found in
468 .Pa /usr/share/syscons/scrnmaps .
470 .Dl vidcontrol -l iso-8859-1_to_cp437
472 The above command will load
473 .Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm .
475 The following command will set-up a 100x37 raster text mode (useful for
478 .Dl vidcontrol -g 100x37 VESA_800x600
480 The following command will capture the contents of the first virtual
481 terminal, and redirect the output to the
485 .Dl vidcontrol -p < /dev/ttyv0 > shot.scr
487 The following command will dump contents of the fourth virtual terminal
488 to the standard output in the human readable format:
490 .Dl vidcontrol -P < /dev/ttyv3
510 .Em "Ports Collection" .
512 .An S\(/oren Schmidt Aq sos@FreeBSD.org