VT(4I) Ioctl Requests VT(4I)

NAME

vt - Solaris virtual console interface

SYNOPSIS

#include <sys/kd.h>
#include <sys/vt.h>

DESCRIPTION

The virtual console device driver -- also known as virtual terminal
(VT) -- is a layer of management functions that provides facilities to
support and switch between multiple screen faces on a single physical
device.

VT's are accessed in the same way as other devices. The open(2) system
call is used to open the virtual console and read(2), write(2) and
ioctl(2) are used in the normal way and support the functionality of
the underlying device. In addition, some virtual console-specific
ioctls are provided and described below.

The VT provides a link between different screen faces and the device.
The active virtual console corresponds to the currently visible screen
face. Device input is directed to the active console and any device-
specific modes that change on a per virtual terminal basis are set to
the characteristics associated with the active console.

You manage VT's by intercepting keyboard sequences ("hot key"). To
maintain consistency with Xserver, the virtual console device driver
supports the Ctrl, Alt, F# and arrow keys.

The sequence AltL + F# (where AltL represents the left Alt key and F#
represents function keys 1 through 12) is used to select virtual
console 1-12. The sequence AltGraph + F# (where AltGraph represents
the right Alt key and F# represent function keys 1 through 12) is for
virtual console 13-24. Alt + F1 chooses the system console (also known
as virtual console 1). The sequence Alt + -> (where "->" represents
the right directional arrow) selects the next VT in a circular ring
fashion and Alt + <- (where "<-" represents the left directional arrow)
changes to the previous console in a circular fashion. The sequence
Alt + |^ (where "|^" represents the up directional arrow) is for the last
used console.

Virtual console switching can be done automatically (VT_AUTO) on
receipt of a "hot-key" or by the process owning the VT (VT_PROCESS).
When performed automatically, the process associated with the virtual
console is unaware of the switch. Saving and restoring the device are
handled by the underlying device driver and the virtual console
manager. Note that automatic switching is the default mode.

When a "hot-key" is sent when in process-controlled switch mode, the
process owning the VT is sent a signal (relsig) it has specified to the
virtual console manager (see signal(3C)) requesting the process to
release the physical device. At this point, the virtual console
manager awaits the VT_RELDISP ioctl from the process. If the process
refuses to release the device (meaning the switch does not occur), it
performs a VT_RELDISP ioctl with an argument of 0 (zero). If the
process desires to release the device, it saves the device state
(keyboard, display, and I/O registers) and then performs a VT_RELDISP
with an argument of 1 to complete the switch.

A ring of VT's can contain intermixed auto mode and process control
mode consoles. When an auto mode process becomes active, the
underlying device driver and the virtual console manager handle the
restoring of the device. Process control mode processes are sent a
specified signal (acqsig) when they become the active console. The
process then restores the device state (keyboard, display, and I/O
registers) and performs VT_RELDISP ioctl with an argument of VT_ACKACQ
to complete the switching protocol.

The modify-operations ioctls (VT_SETMODE, VT_RELDISP, VT_WAITACTIVE,
KDSETMODE) check if the VT is the controlling tty of the calling
process. If not, the sys_devices privilege is enforced. VT_ACTIVATE
requires the sys_devices privilege. Note that there is no controlling
tty and privilege check for query/view operations.

IOCTLS

The following ioctls apply to devices that support virtual consoles:

VT_ENABLED Queries to determine if VT functionality is available on
the system. The argument is a pointer to an integer. If
VT functionality is available, the integer is 1, otherwise
it is 0.

VT_OPENQRY Finds an available VT. The argument is a pointer to an
integer. The integer is filled in with the number of the
first available console that no other process has open (and
hence, is available to be opened). If there are no
available VT's, -1 is filled in.

VT_GETMODE Determines the VT's current mode, either VT_AUTO or
VT_PROCESS. The argument is the address of the following
structure, as defined in <sys/vt.h>

struct vt_mode {
char mode; /* VT mode */
char waitv; /* not used */
short relsig; /* signal to use for release request */
short acqsig; /* signal to use for display acquired */
short frsig; /* not used */
}

/* Virtual console Modes */
#define VT_AUTO 0 /* automatic VT switching */
#define VT_PROCESS 1 /* process controls switching */

The structure will be filled in with the current value for
each field.

VT_SETMODE Sets the VT mode. The argument is a pointer to a vt_mode
structure as defined above. The structure should be filled
in with the desired mode. If process-control mode is
specified, the signals used to communicate with the process
should be specified. If any signals are not specified
(value is zero), the signal default is SIGUSR1 (for relsig
and acqsig).

VT_RELDISP Tells the VT manager if the process releases (or refuses to
release) the display. An argument of 1 indicates the VT is
released. An argument of 0 indicates refusal to release.
The VT_ACKACQ argument indicates if acquisition of the VT
has been completed.

VT_ACTIVATE
Makes the VT specified in the argument the active VT (in
the same manner as if a hotkey initiated the switch). If
the specified VT is not open or does not exist, the call
fails and errno is set to ENXIO.

VT_WAITACTIVE
If the specified VT is currently active, this call returns
immediately. Otherwise, it sleeps until the specified VT
becomes active, at which point it returns.

VT_GETSTATE
Obtains the active VT number and a list of open VTs. The
argument is an address to the following structure:

struct vt_stat {
unsigned short v_active, /* number of the active VT */
v_signal, /* not used */
/*
* count of open VTs. For every 1 in this
* field, there is an open VT
*/
v_state;
}

With VT_GETSTATE, the VT manager first gets the number of
the active VT, then determines the number of open VTs in
the system and sets a 1 for each open VT in v_state. Next,
the VT manager transfers the information in structure
vt_stat passed by the user process.

KDGETMODE Obtains the text/graphics mode associated with the VT.

#define KD_TEXT 0
#define KD_GRAPHICS 1

KDSETMODE Sets the text/graphics mode to the VT.

KD_TEXT indicates that console text is displayed on the screen.
Normally KD_TEXT is combined with VT_AUTO mode for text
console terminals, so that the console text display
automatically is saved and restored on the hot key screen
switches.

KD_GRAPHICS indicates that the user/application (usually
Xserver) has direct control of the display for this VT in
graphics mode. Normally KD_GRAPHICS is combined with
VT_PROCESS mode for this VT indicating direct control of
the display in graphics mode. In this mode, all writes to
the VT using the write system call are ignored, and you
must save and restore the display on the hot key screen
switches.

When the mode of the active VT is changed from KD_TEXT to
KD_GRAPHICS or a VT of KD_GRAPHICS mode is made active from
a previous active VT of KD_TEXT mode, the virtual console
manager initiates a KDSETMODE ioctl with KD_GRAPHICS as the
argument to the underlying console frame buffer device
indicating that current display is running into graphics
mode.

When the mode of the active VT is changed from KD_GRAPHICS
to KD_TEXT or a VT of KD_TEXT mode is activated from a
previous active VT of KD_GRAPHICS mode, the virtual console
manager initiates a KDSETMODE ioctl with KD_TEXT as the
argument to the underlying console frame buffer device
indicating that current display is running into console
text mode.

FILES

/dev/vt/# VT devices.

SEE ALSO

ioctl(2), signal(3C), wscons(4D)

NOTES

By default, there are only five virtual console instance login prompts
running on /dev/vt/# (where "#" represents 2 to 6) in addition to the
system console running on /dev/console. Normally Xorg uses the seventh
virtual console (/dev/vt/7). To switch from consoles to Xserver (which
normally picks up the first available virtual console), use [ Ctrl + ]
Alt + F7 .

# svcs | grep login
online 17:49:11 svc:/system/console-login:default
online 17:49:11 svc:/system/console-login:vt2
online 17:49:11 svc:/system/console-login:vt3
online 17:49:11 svc:/system/console-login:vt4
online 17:49:11 svc:/system/console-login:vt5
online 17:49:11 svc:/system/console-login:vt6

console-login:default is for the system console, others for virtual
consoles.

You can modify properties of, disable/enable, and remove/add virtual
consoles using smf(7):

# svccfg -s console-login add vt8
# svccfg -s console-login:vt8 setprop \
ttymon/device=astring: "/dev/vt/8"
# svcadm enable console-login:vt8

illumos March 13, 2022 illumos