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