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