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.4 2005/07/14 20:44:32 swildner 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
154See also
155.Sx Video Mode Support
156and
157.Sx EXAMPLES
158below and the man page for
159.Xr syscons 4 .
160.It Fl g Ar geometry
161Set the
162.Ar geometry
163of the text mode for the modes with selectable
164geometry.
165Currently only raster modes, such as
166.Ar VESA_800x600 ,
167support this option.
168See also
169.Sx Video Mode Support
170and
171.Sx EXAMPLES
172below.
173.It Fl h Ar size
174Set the size of the history (scrollback) buffer to
175.Ar size
176lines.
177.It Fl i Cm adapter
178Shows info about the current video adapter.
179.It Fl i Cm mode
180Shows the possible video modes with the current video hardware.
181.It Fl l Ar screen_map
182Install screen output map file from
183.Ar screen_map .
184See also
185.Xr syscons 4 .
186.It Fl L
187Install default screen output map.
188.It Fl M Ar char
189Sets the base character used to render the mouse pointer to
190.Ar char .
191.It Fl m Cm on | off
192Switch the mouse pointer
193.Cm on
194or
195.Cm off .
196Used together with the
197.Xr moused 8
198daemon for text mode cut & paste functionality.
199.It Fl p
200Capture the current contents of the video buffer corresponding
201to the terminal device referred to by standard input.
202The
203.Nm
204utility writes contents of the video buffer to the standard
205output in a raw binary format.
206For details about that
207format see
208.Sx Format of Video Buffer Dump
209below.
210.It Fl P
211Same as
212.Fl p ,
213but dump contents of the video buffer in a plain text format
214ignoring nonprintable characters and information about text
215attributes.
216.It Fl r Ar foreground background
217Change reverse mode colors to
218.Ar foreground
219and
220.Ar background .
221.It Fl S Cm on | off
222Turn vty switching on or off.
223When vty switching is off,
224attempts to switch to a different virtual terminal will fail.
225(The default is to permit vty switching.)
226.It Fl s Ar number
227Set the current vty to
228.Ar number .
229.It Fl t Ar N | Cm off
230Set the screensaver timeout to
231.Ar N
232seconds, or turns it
233.Cm off .
234.It Fl x
235Use hexadecimal digits for output.
236.El
237.Ss Video Mode Support
238Note that not all modes listed above may be supported by the video
239hardware.
240You can verify which mode is supported by the video hardware, using the
241.Fl i Cm mode
242option.
243.Pp
244The VESA BIOS support must be linked to the kernel
245or loaded as a KLD module if you wish to use VESA video modes
246or 132 column modes
247(see
248.Xr vga 4 ) .
249.Pp
250You need to compile your kernel with the
251.Ar VGA_WIDTH90
252option if you wish to use VGA 90 column modes
253(see
254.Xr vga 4 ) .
255.Pp
256Video modes other than 25 and 30 line modes may require specific size of font.
257Use
258.Fl f
259option above to load a font file to the kernel.
260If the required size of font has not been loaded to the kernel,
261.Nm
262will fail if the user attempts to set a new video mode.
263.Pp
264.Bl -column "25 line modes" "8x16 (VGA), 8x14 (EGA)" -compact
265.Sy Modes Ta Sy Font size
266.Li 25 line modes Ta 8x16 (VGA), 8x14 (EGA)
267.Li 30 line modes Ta 8x16
268.Li 43 line modes Ta 8x8
269.Li 50 line modes Ta 8x8
270.Li 60 line modes Ta 8x8
271.El
272.Pp
273It is better to always load all three sizes (8x8, 8x14 and 8x16)
274of the same font.
275.Pp
276You may set variables in
277.Pa /etc/rc.conf
278or
279.Pa /etc/rc.conf.local
280so that desired font files will be automatically loaded
281when the system starts up.
282See below.
283.Pp
284If you want to use any of the raster text modes you need to recompile your
285kernel with the
286.Dv SC_PIXEL_MODE
287option.
288See
289.Xr syscons 4
290for more details on this kernel option.
291.Ss Format of Video Buffer Dump
292The
293.Nm
294utility uses the
295.Xr syscons 4
296.Dv CONS_SCRSHOT
297.Xr ioctl 2
298to capture the current contents of the video buffer.
299The
300.Nm
301utility writes version and additional information to the standard
302output, followed by the contents of the terminal device.
303.Pp
304PC video memory is typically arranged in two byte tuples,
305one per character position.
306In each tuple, the first byte
307will be the character code, and the second byte is the
308character's color attribute.
309.Pp
310The color attribute byte is further broken down in to the
311low nibble, which specifies which of 16 different foreground
312colors is active, and the high nibble, which specifies which
313of 16 different background colors is active.
314.Pp
315.Bl -hang -offset indent -compact
316.It 0
317Black
318.It 1
319Blue
320.It 2
321Green
322.It 3
323Cyan
324.It 4
325Red
326.It 5
327Magenta
328.It 6
329Brown
330.It 7
331White
332.It 8
333Grey
334.It 9
335Light Blue
336.It 10
337Light Green
338.It 11
339Light Cyan
340.It 12
341Light Red
342.It 13
343Light Magenta
344.It 14
345Yellow
346.It 15
347White
348.El
349.Pp
350It can be seen that the last 8 colors are brighter
351versions of the first 8.
352.Pp
353For example, the two bytes
354.Pp
355.Dl "65 158"
356.Pp
357specify an uppercase A (character code 65), in
358yellow (low nibble 15) on a light blue background
359(high nibble 9).
360.Pp
361The
362.Nm
363output contains a small header which includes additional
364information which may be useful to utilities processing
365the output.
366.Pp
367The first 10 bytes are always arranged as follows:
368.Bl -column "Byte range" "Contents" -offset indent
369.It Sy "Byte Range	Contents"
370.It "1 thru 8	Literal text" Dq Li SCRSHOT_
371.It "9	File format version number"
372.It "10	Remaining number of bytes in the header"
373.El
374.Pp
375Subsequent bytes depend on the version number.
376.Bl -column "Version" "13 and up" -offset indent
377.It Sy "Version	Byte	Meaning"
378.It "1	11	Terminal width, in characters"
379.It "	12	Terminal depth, in characters"
380.It "	13 and up	The snapshot data"
381.El
382.Pp
383So a dump of an 80x25 screen would start (in hex)
384.Bd -literal -offset indent
38553 43 52 53 48 4f 54 5f 01 02 50 19
386----------------------- -- -- -- --
387          |              |  |  |  ` 25 decimal
388          |              |  |  `--- 80 decimal
389          |              |  `------ 2 remaining bytes of header data
390          |              `--------- File format version 1
391          `------------------------ Literal "SCRSHOT_"
392.Ed
393.Sh VIDEO OUTPUT CONFIGURATION
394.Ss Boot Time Configuration
395You may set the following variables in
396.Pa /etc/rc.conf
397or
398.Pa /etc/rc.conf.local
399in order to configure the video output at boot time.
400.Pp
401.Bl -tag -width foo_bar_var -compact
402.It Ar blanktime
403Sets the timeout value for the
404.Fl t
405option.
406.It Ar font8x16 , font8x14 , font8x8
407Specifies font files for the
408.Fl f
409option.
410.It Ar scrnmap
411Specifies a screen output map file for the
412.Fl l
413option.
414.El
415.Pp
416See
417.Xr rc.conf 5
418for more details.
419.Ss Driver Configuration
420The video card driver may let you change default configuration
421options, such as the default font, so that you do not need to set up
422the options at boot time.
423See video card driver manuals, (e.g.\&
424.Xr vga 4 )
425for details.
426.Sh FILES
427.Bl -tag -width /usr/share/syscons/scrnmaps/foo-bar -compact
428.It Pa /usr/share/syscons/fonts/*
429font files.
430.It Pa /usr/share/syscons/scrnmaps/*
431screen output map files.
432.El
433.Sh EXAMPLES
434If you want to load
435.Pa /usr/share/syscons/fonts/iso-8x16.fnt
436to the kernel, run
437.Nm
438as:
439.Pp
440.Dl vidcontrol -f 8x16 /usr/share/syscons/fonts/iso-8x16.fnt
441.Pp
442So long as the font file is in
443.Pa /usr/share/syscons/fonts ,
444you may abbreviate the file name as
445.Pa iso-8x16 :
446.Pp
447.Dl vidcontrol -f 8x16 iso-8x16
448.Pp
449Furthermore, you can also omit font size
450.Dq Li 8x16 :
451.Pp
452.Dl vidcontrol -f iso-8x16
453.Pp
454Moreover, the suffix specifying the font size can be also omitted; in
455this case,
456.Nm
457will use the size of the currently displayed font to construct the
458suffix:
459.Pp
460.Dl vidcontrol -f iso
461.Pp
462Likewise, you can also abbreviate the screen output map file name for
463the
464.Fl l
465option if the file is found in
466.Pa /usr/share/syscons/scrnmaps .
467.Pp
468.Dl vidcontrol -l iso-8859-1_to_cp437
469.Pp
470The above command will load
471.Pa /usr/share/syscons/scrnmaps/iso-8859-1_to_cp437.scm .
472.Pp
473The following command will set-up a 100x37 raster text mode (useful for
474some LCD models):
475.Pp
476.Dl vidcontrol -g 100x37 VESA_800x600
477.Pp
478The following command will capture the contents of the first virtual
479terminal, and redirect the output to the
480.Pa shot.scr
481file:
482.Pp
483.Dl vidcontrol -p < /dev/ttyv0 > shot.scr
484.Pp
485The following command will dump contents of the fourth virtual terminal
486to the standard output in the human readable format:
487.Pp
488.Dl vidcontrol -P < /dev/ttyv3
489.Sh SEE ALSO
490.Xr kbdcontrol 1 ,
491.Xr vidfont 1 ,
492.Xr keyboard 4 ,
493.Xr screen 4 ,
494.Xr syscons 4 ,
495.Xr vga 4 ,
496.Xr rc.conf 5 ,
497.Xr kldload 8 ,
498.Xr moused 8 ,
499.Xr watch 8
500.Pp
501The various
502.Li scr2*
503utilities in the
504.Li graphics
505and
506.Li textproc
507categories of the
508.Em "Ports Collection" .
509.Sh AUTHORS
510.An S\(/oren Schmidt Aq sos@FreeBSD.org
511.An Sascha Wildner
512