1.\"
2.\" vidcontrol - a utility for manipulating the syscons video driver
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
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.
12.\"
13.\"     @(#)vidcontrol.1
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 $
16.\"
17.Dd May 27, 2002
18.Dt VIDCONTROL 1
19.Os
20.Sh NAME
21.Nm vidcontrol
22.Nd system console control and configuration utility
23.Sh SYNOPSIS
24.Nm
25.Op Fl CdLPpx
26.Op Fl b Ar color
27.Op Fl c Ar appearance
28.Oo
29.Fl f
30.Op Ar size
31.Ar file
32.Oc
33.Op Fl g Ar geometry
34.Op Fl h Ar size
35.Op Fl i Cm adapter | mode
36.Op Fl l Ar screen_map
37.Op Fl M Ar char
38.Op Fl m Cm on | off
39.Op Fl r Ar foreground Ar background
40.Op Fl S Cm on | off
41.Op Fl s Ar number
42.Op Fl t Ar N | Cm off
43.Op Ar mode
44.Op Ar foreground Op Ar background
45.Op Cm show
46.Sh DESCRIPTION
47The
48.Nm
49command is used to set various options for the
50.Xr syscons 4
51console driver,
52such as video mode, colors, cursor shape, screen output map, font and screen
53saver timeout.
54.Pp
55The following command line options are supported:
56.Bl -tag -width indent
57.It Ar mode
58Select a new video mode.
59The modes currently recognized are:
60.Ar 80x25 ,
61.Ar 80x30 ,
62.Ar 80x43 ,
63.Ar 80x50 ,
64.Ar 80x60 ,
65.Ar 132x25 ,
66.Ar 132x30 ,
67.Ar 132x43 ,
68.Ar 132x50 ,
69.Ar 132x60 ,
70.Ar VGA_40x25 ,
71.Ar VGA_80x25 ,
72.Ar VGA_80x30 ,
73.Ar VGA_80x50 ,
74.Ar VGA_80x60 ,
75.Ar VGA_90x25 ,
76.Ar VGA_90x30 ,
77.Ar VGA_90x43 ,
78.Ar VGA_90x50 ,
79.Ar VGA_90x60 ,
80.Ar EGA_80x25 ,
81.Ar EGA_80x43 ,
82.Ar VESA_132x25 ,
83.Ar VESA_132x43 ,
84.Ar VESA_132x50 ,
85.Ar VESA_132x60 .
86.\"The graphic mode
87.\".Ar VGA_320x200
88.\"and
89The raster text mode
90.Ar VESA_800x600
91can also be chosen.
92Alternatively, a mode can be specified with its number by using a mode name of
93the form
94.Ar MODE_<NUMBER> .
95A list of valid mode numbers can be obtained with the
96.Fl i Cm mode
97option. See
98.Sx Video Mode Support
99below.
100.It Ar foreground Op Ar background
101Change colors when displaying text.
102Specify the foreground color
103(e.g.\&
104.Dq vidcontrol white ) ,
105or both a foreground and background colors
106(e.g.\&
107.Dq vidcontrol yellow blue ) .
108Use the
109.Cm show
110command below to see available colors.
111.It Cm show
112See the supported colors on a given platform.
113.It Fl b Ar color
114Set border color to
115.Ar color .
116This option may not be always supported by the video driver.
117.It Fl C
118Clear the history buffer.
119.It Fl c Cm normal | blink | destructive
120Change the cursor appearance.
121The cursor is either an inverting block
122.Pq Cm normal
123that can optionally
124.Cm blink ,
125or it can be like the old hardware cursor
126.Pq Cm destructive .
127The latter is actually a simulation.
128.It Fl d
129Print out current output screen map.
130.It Xo
131.Fl f
132.Op Ar size
133.Ar file
134.Xc
135Load font
136.Ar file
137for
138.Ar size
139(currently, only
140.Cm 8x8 ,
141.Cm 8x14
142or
143.Cm 8x16 ) .
144The font file can be either uuencoded or in raw binary format.
145You can also use the menu-driven
146.Xr vidfont 1
147command to load the font of your choice.
148.Pp
149.Ar Size
150may be omitted, in this case
151.Nm
152will try to guess it from the size of font file.
153.Pp
154Note that older video cards, such as MDA and CGA, do not support
155software font.
156See also
157.Sx Video Mode Support
158and
159.Sx EXAMPLES
160below and the man page for
161.Xr syscons 4 .
162.It Fl g Ar geometry
163Set the
164.Ar geometry
165of the text mode for the modes with selectable
166geometry.
167Currently only raster modes, such as
168.Ar VESA_800x600 ,
169support this option.
170See also
171.Sx Video Mode Support
172and
173.Sx EXAMPLES
174below.
175.It Fl h Ar size
176Set the size of the history (scrollback) buffer to
177.Ar size
178lines.
179.It Fl i Cm adapter
180Shows info about the current video adapter.
181.It Fl i Cm mode
182Shows the possible video modes with the current video hardware.
183.It Fl l Ar screen_map
184Install screen output map file from
185.Ar screen_map .
186See also
187.Xr syscons 4 .
188.It Fl L
189Install default screen output map.
190.It Fl M Ar char
191Sets the base character used to render the mouse pointer to
192.Ar char .
193.It Fl m Cm on | off
194Switch the mouse pointer
195.Cm on
196or
197.Cm off .
198Used together with the
199.Xr moused 8
200daemon for text mode cut & paste functionality.
201.It Fl p
202Capture the current contents of the video buffer corresponding
203to the terminal device referred to by standard input.
204The
205.Nm
206utility writes contents of the video buffer to the standard
207output in a raw binary format.
208For details about that
209format see
210.Sx Format of Video Buffer Dump
211below.
212.It Fl P
213Same as
214.Fl p ,
215but dump contents of the video buffer in a plain text format
216ignoring nonprintable characters and information about text
217attributes.
218.It Fl r Ar foreground background
219Change reverse mode colors to
220.Ar foreground
221and
222.Ar background .
223.It Fl S Cm on | off
224Turn vty switching on or off.
225When vty switching is off,
226attempts to switch to a different virtual terminal will fail.
227(The default is to permit vty switching.)
228.It Fl s Ar number
229Set the current vty to
230.Ar number .
231.It Fl t Ar N | Cm off
232Set the screensaver timeout to
233.Ar N
234seconds, or turns it
235.Cm off .
236.It Fl x
237Use hexadecimal digits for output.
238.El
239.Ss Video Mode Support
240Note that not all modes listed above may be supported by the video
241hardware.
242You can verify which mode is supported by the video hardware, using the
243.Fl i Cm mode
244option.
245.Pp
246The VESA BIOS support must be linked to the kernel
247or loaded as a KLD module if you wish to use VESA video modes
248or 132 column modes
249(see
250.Xr vga 4 ) .
251.Pp
252You need to compile your kernel with the
253.Ar VGA_WIDTH90
254option if you wish to use VGA 90 column modes
255(see
256.Xr vga 4 ) .
257.Pp
258Video modes other than 25 and 30 line modes may require specific size of font.
259Use
260.Fl f
261option above to load a font file to the kernel.
262If the required size of font has not been loaded to the kernel,
263.Nm
264will fail if the user attempts to set a new video mode.
265.Pp
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
273.El
274.Pp
275It is better to always load all three sizes (8x8, 8x14 and 8x16)
276of the same font.
277.Pp
278You may set variables in
279.Pa /etc/rc.conf
280or
281.Pa /etc/rc.conf.local
282so that desired font files will be automatically loaded
283when the system starts up.
284See below.
285.Pp
286If you want to use any of the raster text modes you need to recompile your
287kernel with the
288.Dv SC_PIXEL_MODE
289option.
290See
291.Xr syscons 4
292for more details on this kernel option.
293.Ss Format of Video Buffer Dump
294The
295.Nm
296utility uses the
297.Xr syscons 4
298.Dv CONS_SCRSHOT
299.Xr ioctl 2
300to capture the current contents of the video buffer.
301The
302.Nm
303utility writes version and additional information to the standard
304output, followed by the contents of the terminal device.
305.Pp
306PC video memory is typically arranged in two byte tuples,
307one per character position.
308In each tuple, the first byte
309will be the character code, and the second byte is the
310character's color attribute.
311.Pp
312The color attribute byte is further broken down in to the
313low nibble, which specifies which of 16 different foreground
314colors is active, and the high nibble, which specifies which
315of 16 different background colors is active.
316.Pp
317.Bl -hang -offset indent -compact
318.It 0
319Black
320.It 1
321Blue
322.It 2
323Green
324.It 3
325Cyan
326.It 4
327Red
328.It 5
329Magenta
330.It 6
331Brown
332.It 7
333White
334.It 8
335Grey
336.It 9
337Light Blue
338.It 10
339Light Green
340.It 11
341Light Cyan
342.It 12
343Light Red
344.It 13
345Light Magenta
346.It 14
347Yellow
348.It 15
349White
350.El
351.Pp
352It can be seen that the last 8 colors are brighter
353versions of the first 8.
354.Pp
355For example, the two bytes
356.Pp
357.Dl "65 158"
358.Pp
359specify an uppercase A (character code 65), in
360yellow (low nibble 15) on a light blue background
361(high nibble 9).
362.Pp
363The
364.Nm
365output contains a small header which includes additional
366information which may be useful to utilities processing
367the output.
368.Pp
369The 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"
375.El
376.Pp
377Subsequent 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"
383.El
384.Pp
385So a dump of an 80x25 screen would start (in hex)
386.Bd -literal -offset indent
38753 43 52 53 48 4f 54 5f 01 02 50 19
388----------------------- -- -- -- --
389          |              |  |  |  ` 25 decimal
390          |              |  |  `--- 80 decimal
391          |              |  `------ 2 remaining bytes of header data
392          |              `--------- File format version 1
393          `------------------------ Literal "SCRSHOT_"
394.Ed
395.Sh VIDEO OUTPUT CONFIGURATION
396.Ss Boot Time Configuration
397You may set the following variables in
398.Pa /etc/rc.conf
399or
400.Pa /etc/rc.conf.local
401in order to configure the video output at boot time.
402.Pp
403.Bl -tag -width foo_bar_var -compact
404.It Ar blanktime
405Sets the timeout value for the
406.Fl t
407option.
408.It Ar font8x16 , font8x14 , font8x8
409Specifies font files for the
410.Fl f
411option.
412.It Ar scrnmap
413Specifies a screen output map file for the
414.Fl l
415option.
416.El
417.Pp
418See
419.Xr rc.conf 5
420for more details.
421.Ss Driver Configuration
422The video card driver may let you change default configuration
423options, such as the default font, so that you do not need to set up
424the options at boot time.
425See video card driver manuals, (e.g.\&
426.Xr vga 4 )
427for details.
428.Sh FILES
429.Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact
430.It Pa /usr/share/syscons/fonts/*
431font files.
432.It Pa /usr/share/syscons/scrnmaps/*
433screen output map files.
434.El
435.Sh EXAMPLES
436If you want to load
437.Pa /usr/share/syscons/fonts/iso-8x16.fnt
438to the kernel, run
439.Nm
440as:
441.Pp
442.Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt
443.Pp
444So long as the font file is in
445.Pa /usr/share/syscons/fonts ,
446you may abbreviate the file name as
447.Pa iso-8x16 :
448.Pp
449.Dl vidcontrol -f 8x16 iso-8x16
450.Pp
451Furthermore, you can also omit font size
452.Dq Li 8x16 :
453.Pp
454.Dl vidcontrol -f iso-8x16
455.Pp
456Moreover, the suffix specifying the font size can be also omitted; in
457this case,
458.Nm
459will use the size of the currently displayed font to construct the
460suffix:
461.Pp
462.Dl vidcontrol -f iso
463.Pp
464Likewise, you can also abbreviate the screen output map file name for
465the
466.Fl l
467option if the file is found in
468.Pa /usr/share/syscons/scrnmaps .
469.Pp
470.Dl vidcontrol -l iso-8859-1_to_cp437
471.Pp
472The above command will load
473.Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm .
474.Pp
475The following command will set-up a 100x37 raster text mode (useful for
476some LCD models):
477.Pp
478.Dl vidcontrol -g 100x37 VESA_800x600
479.Pp
480The following command will capture the contents of the first virtual
481terminal, and redirect the output to the
482.Pa shot.scr
483file:
484.Pp
485.Dl vidcontrol -p < /dev/ttyv0 > shot.scr
486.Pp
487The following command will dump contents of the fourth virtual terminal
488to the standard output in the human readable format:
489.Pp
490.Dl vidcontrol -P < /dev/ttyv3
491.Sh SEE ALSO
492.Xr kbdcontrol 1 ,
493.Xr vidfont 1 ,
494.Xr keyboard 4 ,
495.Xr screen 4 ,
496.Xr syscons 4 ,
497.Xr vga 4 ,
498.Xr rc.conf 5 ,
499.Xr kldload 8 ,
500.Xr moused 8 ,
501.Xr watch 8
502.Pp
503The various
504.Li scr2*
505utilities in the
506.Li graphics
507and
508.Li textproc
509categories of the
510.Em "Ports Collection" .
511.Sh AUTHORS
512.An S\(/oren Schmidt Aq sos@FreeBSD.org
513.An Sascha Wildner
514