1 '\" te
2 .\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH VT 7I "Sep 22, 2008"
7 .SH NAME
8 vt \- Solaris virtual console interface
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB#include <sys/kd.h> \fR
13 .fi
14
15 .LP
16 .nf
17 \fB#include <sys/vt.h> \fR
18 .fi
19
20 .SH DESCRIPTION
21 .sp
22 .LP
23 The virtual console device driver \(em also known as virtual terminal
24 (\fBVT\fR) \(em is a layer of management functions that provides facilities to
25 support and switch between multiple screen faces on a single physical device.
26 .sp
27 .LP
28 VT's are accessed in the same way as other devices. The \fBopen\fR(2) system
29 call is used to open the virtual console and \fBread\fR(2), \fBwrite\fR(2) and
30 \fBioctl\fR(2) are used in the normal way and support the functionality of the
31 underlying device. In addition, some virtual console-specific ioctls are
32 provided and described below.
33 .sp
34 .LP
35 The VT provides a link between different screen faces and the device. The
36 \fBactive virtual console\fR corresponds to the currently visible screen face.
37 Device input is directed to the active console and any device-specific modes
38 that change on a per virtual terminal basis are set to the characteristics
39 associated with the active console.
40 .sp
41 .LP
42 You manage VT's by intercepting keyboard sequences ("hot key"). To maintain
43 consistency with Xserver, the virtual console device driver supports the Ctrl,
44 Alt, F# and arrow keys.
45 .sp
46 .LP
47 The sequence \fBAltL + F#\fR (where AltL represents the Alt key and F#
48 represents function keys 1 through 12) is used to select virtual console 1-12.
49 The sequence \fBAltGraph + F#\fR (where AltGraph represents the right Alt key
50 and F# represent function keys 1 through 12) is for virtual console 13-24.
51 \fBAlt + F1\fR chooses the system console (also known as virtual console 1).
52 The sequence \fBAlt + ->\fR (where ">" represents the right directional arrow)
53 selects the next VT in a circular ring fashion and \fBAlt + <-\fR ( where "<"
54 represents the left directional arrow) changes to the previous console in a
55 circular fashion. The sequence \fBAlt + ^\fR (where "^" represents the up
56 directional arrow) is for the last used console.
57 .sp
58 .LP
59 Virtual console switching can be done automatically (\fBVT_AUTO\fR) on receipt
60 of a ``hot-key'' or by the process owning the VT (\fBVT_PROCESS\fR). When
61 performed automatically, the process associated with the virtual console is
62 unaware of the switch. Saving and restoring the device are handled by the
63 underlying device driver and the virtual console manager. Note that automatic
64 switching is the default mode.
65 .sp
66 .LP
67 When a ``hot-key'' is sent when in process-controlled switch mode, the process
68 owning the VT is sent a signal (relsig) it has specified to the virtual console
69 manager (see \fBsignal\fR(3C)) requesting the process to release the physical
70 device. At this point, the virtual console manager awaits the \fBVT_RELDISP\fR
71 ioctl from the process. If the process refuses to release the device (meaning
72 the switch does not occur), it performs a \fBVT_RELDISP\fR ioctl with an
73 argument of 0 (zero). If the process desires to release the device, it saves
74 the device state (keyboard, display, and I/O registers) and then performs a
75 \fBVT_RELDISP\fR with an argument of 1 to complete the switch.
76 .sp
77 .LP
78 A ring of VT's can contain intermixed auto mode and process control mode
79 consoles. When an auto mode process becomes active, the underlying device
80 driver and the virtual console manager handle the restoring of the device.
81 Process control mode processes are sent a specified signal (acqsig) when they
82 become the active console. The process then restores the device state
83 (keyboard, display, and I/O registers) and performs \fBVT_RELDISP\fR ioctl with
84 an argument of \fBVT_ACKACQ\fR to complete the switching protocol.
85 .sp
86 .LP
87 The modify-operations ioctls (\fBVT_SETMODE\fR, \fBVT_RELDISP\fR,
88 \fBVT_WAITACTIVE\fR, \fBKDSETMODE\fR) check if the VT is the controlling tty of
89 the calling process. If not, the sys_devices privilege is enforced.
90 \fBVT_ACTIVATE\fR requires the sys_devices privilege. Note that there is no
91 controlling tty and privilege check for query/view operations.
92 .SH IOCTLS
93 .sp
94 .LP
95 The following ioctls apply to devices that support virtual consoles:
96 .sp
97 .ne 2
98 .na
99 \fB\fBVT_ENABLED\fR\fR
100 .ad
101 .sp .6
102 .RS 4n
103 Queries to determine if VT functionality is available on the system. The
104 argument is a pointer to an integer. If VT functionality is available, the
105 integer is 1, otherwise it is 0.
106 .RE
107
108 .sp
109 .ne 2
110 .na
111 \fB\fBVT_OPENQRY\fR\fR
112 .ad
113 .sp .6
114 .RS 4n
115 Finds an available VT. The argument is a pointer to an integer. The integer is
116 filled in with the number of the first available console that no other process
117 has open (and hence, is available to be opened). If there are no available
118 VT's, -1 is filled in.
119 .RE
120
121 .sp
122 .ne 2
123 .na
124 \fB\fBVT_GETMODE\fR\fR
125 .ad
126 .sp .6
127 .RS 4n
128 Determines the VT's current mode, either \fBVT_AUTO\fR or \fBVT_PROCESS\fR. The
129 argument is the address of the following structure, as defined in
130 <\fBsys/vt.h\fR>
131 .sp
132 .in +2
133 .nf
134 struct vt_mode {
135 char mode; /* VT mode */
136 char waitv; /* not used */
137 short relsig;/* signal to use for release request */
138 short acqsig;/* signal to use for display acquired */
139 short frsig;/* not used */
140 }
141
142 /* Virtual console Modes */
143 #define VT_AUTO 0 /* automatic VT switching */
144 #define VT_PROCESS 1 /* process controls switching */
145
146
147 The structure will be filled in with the current value
148 for each field.
149 .fi
150 .in -2
151
152 .RE
153
154 .sp
155 .ne 2
156 .na
157 \fB\fBVT_SETMODE\fR\fR
158 .ad
159 .sp .6
160 .RS 4n
161 Sets the VT mode. The argument is a pointer to a vt_mode structure as defined
162 above. The structure should be filled in with the desired mode. If
163 process-control mode is specified, the signals used to communicate with the
164 process should be specified. If any signals are not specified (value is zero),
165 the signal default is \fBSIGUSR1\fR (for relsig and acqsig).
166 .RE
167
168 .sp
169 .ne 2
170 .na
171 \fB\fBVT_RELDISP\fR\fR
172 .ad
173 .sp .6
174 .RS 4n
175 Tells the VT manager if the process releases (or refuses to release) the
176 display. An argument of 1 indicates the VT is released. An argument of 0
177 indicates refusal to release. The \fBVT_ACKACQ\fR argument indicates if
178 acquisition of the VT has been completed.
179 .RE
180
181 .sp
182 .ne 2
183 .na
184 \fB\fBVT_ACTIVATE\fR\fR
185 .ad
186 .sp .6
187 .RS 4n
188 Makes the VT specified in the argument the active VT (in the same manner as if
189 a hotkey initiated the switch). If the specified VT is not open or does not
190 exist, the call fails and errno is set to \fBENXIO\fR.
191 .RE
192
193 .sp
194 .ne 2
195 .na
196 \fB\fBVT_WAITACTIVE\fR\fR
197 .ad
198 .sp .6
199 .RS 4n
200 If the specified VT is currently active, this call returns immediately.
201 Otherwise, it sleeps until the specified VT becomes active, at which point it
202 returns.
203 .RE
204
205 .sp
206 .ne 2
207 .na
208 \fB\fBVT_GETSTATE\fR\fR
209 .ad
210 .sp .6
211 .RS 4n
212 Obtains the active VT number and a list of open VTs. The argument is an address
213 to the following structure:
214 .sp
215 .in +2
216 .nf
217 struct vt_stat {
218 unsigned short v_active, /* number of the active VT */
219 v_signal, /* not used */
220 v_state; /* count of open VTs. For every 1 in this
221 field, there is an open VT */
222 }
223 .fi
224 .in -2
225
226 With \fBVT_GETSTATE\fR, the VT manager first gets the number of the active VT,
227 then determines the number of open VTs in the system and sets a 1 for each open
228 VT in v_state. Next, the VT manager transfers the information in structure
229 \fBvt_stat\fR passed by the user process.
230 .RE
231
232 .sp
233 .ne 2
234 .na
235 \fB\fBKDGETMODE\fR\fR
236 .ad
237 .sp .6
238 .RS 4n
239 Obtains the text/graphics mode associated with the VT.
240 .sp
241 .in +2
242 .nf
243 #define KD_TEXT 0
244 #define KD_GRAPHICS 1
245 .fi
246 .in -2
247
248 .RE
249
250 .sp
251 .ne 2
252 .na
253 \fB\fBKDSETMODE\fR\fR
254 .ad
255 .sp .6
256 .RS 4n
257 Sets the text/graphics mode to the VT.
258 .sp
259 \fBKD_TEXT\fR indicates that console text is displayed on the screen. Normally
260 \fBKD_TEXT\fR is combined with \fBVT_AUTO\fR mode for text console terminals,
261 so that the console text display automatically is saved and restored on the hot
262 key screen switches.
263 .sp
264 \fBKD_GRAPHICS\fR indicates that the user/application (usually Xserver) has
265 direct control of the display for this VT in graphics mode. Normally
266 \fBKD_GRAPHICS\fR is combined with \fBVT_PROCESS\fR mode for this VT indicating
267 direct control of the display in graphics mode. In this mode, all writes to the
268 VT using the write system call are ignored, and you must save and restore the
269 display on the hot key screen switches.
270 .sp
271 When the mode of the active VT is changed from \fBKD_TEXT\fR to
272 \fBKD_GRAPHICS\fR or a VT of \fBKD_GRAPHICS\fR mode is made active from a
273 previous active VT of \fBKD_TEXT\fR mode, the virtual console manager initiates
274 a \fBKDSETMODE\fR ioctl with \fBKD_GRAPHICS\fR as the argument to the
275 underlying console frame buffer device indicating that current display is
276 running into graphics mode.
277 .sp
278 When the mode of the active VT is changed from \fBKD_GRAPHICS\fR to
279 \fBKD_TEXT\fR or a VT of \fBKD_TEXT\fR mode is actived from a previous active
280 VT of \fBKD_GRAPHICS\fR mode, the virtual console manager initiates a
281 \fBKDSETMODE\fR ioctl with \fBKD_TEXT\fR as the argument to the underlying
282 console frame buffer device indicating that current display is running into
283 console text mode.
284 .RE
285
286 .SH FILES
287 .sp
288 .ne 2
289 .na
290 \fB\fB/dev/vt/#\fR \fR
291 .ad
292 .RS 14n
293 VT devices.
294 .RE
295
296 .SH SEE ALSO
297 .sp
298 .LP
299 \fBioctl\fR(2), \fBsignal\fR(3C), \fBwscons\fR(7D)
300 .SH NOTES
301 .sp
302 .LP
303 By default, there are only five virtual console instance login prompts running
304 on \fB/dev/vt/#\fR (where "#" represents 2 to 6) in addition to the system
305 console running on \fB/dev/console\fR. Normally Xorg uses the seventh virtual
306 console (\fB/dev/vt/7\fR.) To switch from consoles to Xserver (which normally
307 picks up the first available virtual console), use [ Ctrl + ] Alt + F7 .
308 .sp
309 .in +2
310 .nf
311 # svcs | grep login
312 online 17:49:11 svc:/system/console-login:default
313 online 17:49:11 svc:/system/console-login:vt2
314 online 17:49:11 svc:/system/console-login:vt3
315 online 17:49:11 svc:/system/console-login:vt4
316 online 17:49:11 svc:/system/console-login:vt5
317 online 17:49:11 svc:/system/console-login:vt6
318
319 console-login:default is for the system console, others for
320 virtual consoles.
321
322 You can modify properties/disable/enable and remove/add
323 virtual consoles using smf(5):
324
325 # svccfg -s console-login add vt8
326 # svccfg -s console-login:vt8 setprop ttymon/device=astring: "/dev/vt/8"
327 # svcadm enable console-login:vt8
328 .fi
329 .in -2
330