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