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