1 VT(7I)                          Ioctl Requests                          VT(7I)
   2 
   3 NAME
   4      vt - illumos virtual console interface
   5 
   6 SYNOPSIS
   7      #include <sys/kd.h>
   8      #include <sys/vt.h>
   9 
  10 DESCRIPTION
  11      The virtual console device driver -- also known as virtual terminal (VT)
  12      -- is a layer of management functions that provides facilities to support
  13      and switch between multiple screen faces on a single physical device.
  14 
  15      VT's are accessed in the same way as other devices.  The open(2) system
  16      call is used to open the virtual console and read(2), write(2) and
  17      ioctl(2) are used in the normal way and support the functionality of the
  18      underlying device.  In addition, some virtual console-specific ioctls are
  19      provided and described below.
  20 
  21      The VT provides a link between different screen faces and the device.
  22      The active virtual console corresponds to the currently visible screen
  23      face.  Device input is directed to the active console and any device-
  24      specific modes that change on a per virtual terminal basis are set to the
  25      characteristics associated with the active console.
  26 
  27      You manage VT's by intercepting keyboard sequences ("hot key").  To
  28      maintain consistency with Xserver, the virtual console device driver
  29      supports the Ctrl, Alt, F# and arrow keys.
  30 
  31      The sequence AltL + F# (where AltL represents the left Alt key and F#
  32      represents function keys 1 through 12) is used to select virtual console
  33      1-12.  The sequence AltGraph + F# (where AltGraph represents the right
  34      Alt key and F# represent function keys 1 through 12) is for virtual
  35      console 13-24.  Alt + F1 chooses the system console (also known as
  36      virtual console 1).  The sequence Alt + ->      (where "->" represents the
  37      right directional arrow) selects the next VT in a circular ring fashion
  38      and Alt + <- (where "<-" represents the left directional arrow) changes
  39      to the previous console in a circular fashion.  The sequence Alt + ^
  40      (where "^" represents the up directional arrow) is for the last used
  41      console.
  42 
  43      Virtual console switching can be done automatically (VT_AUTO) on receipt
  44      of a "hot-key" or by the process owning the VT (VT_PROCESS).  When
  45      performed automatically, the process associated with the virtual console
  46      is unaware of the switch.  Saving and restoring the device are handled by
  47      the underlying device driver and the virtual console manager.  Note that
  48      automatic switching is the default mode.
  49 
  50      When a "hot-key" is sent when in process-controlled switch mode, the
  51      process owning the VT is sent a signal (relsig) it has specified to the
  52      virtual console manager (see signal(3C)) requesting the process to
  53      release the physical device.  At this point, the virtual console manager
  54      awaits the VT_RELDISP ioctl from the process.  If the process refuses to
  55      release the device (meaning the switch does not occur), it performs a
  56      VT_RELDISP ioctl with an argument of 0 (zero).  If the process desires to
  57      release the device, it saves the device state (keyboard, display, and I/O
  58      registers) and then performs a VT_RELDISP with an argument of 1 to
  59      complete the switch.
  60 
  61      A ring of VT's can contain intermixed auto mode and process control mode
  62      consoles.  When an auto mode process becomes active, the underlying
  63      device driver and the virtual console manager handle the restoring of the
  64      device.  Process control mode processes are sent a specified signal
  65      (acqsig) when they become the active console.  The process then restores
  66      the device state (keyboard, display, and I/O registers) and performs
  67      VT_RELDISP ioctl with an argument of VT_ACKACQ to complete the switching
  68      protocol.
  69 
  70      The modify-operations ioctls (VT_SETMODE, VT_RELDISP, VT_WAITACTIVE,
  71      KDSETMODE) check if the VT is the controlling tty of the calling process.
  72      If not, the sys_devices privilege is enforced.  VT_ACTIVATE requires the
  73      sys_devices privilege.  Note that there is no controlling tty and
  74      privilege check for query/view operations.
  75 
  76 IOCTLS
  77      The following ioctls apply to devices that support virtual consoles:
  78 
  79      VT_ENABLED  Queries to determine if VT functionality is available on the
  80                  system.  The argument is a pointer to an integer.  If VT
  81                  functionality is available, the integer is 1, otherwise it is
  82                  0.
  83 
  84      VT_OPENQRY  Finds an available VT.  The argument is a pointer to an
  85                  integer.  The integer is filled in with the number of the
  86                  first available console that no other process has open (and
  87                  hence, is available to be opened).  If there are no available
  88                  VT's, -1 is filled in.
  89 
  90      VT_GETMODE  Determines the VT's current mode, either VT_AUTO or
  91                  VT_PROCESS.  The argument is the address of the following
  92                  structure, as defined in <sys/vt.h>
  93 
  94                    struct vt_mode {
  95                          char mode;     /* VT mode */
  96                          char waitv;    /* not used */
  97                          short relsig;  /* signal to use for release request */
  98                          short acqsig;  /* signal to use for display acquired */
  99                          short frsig;   /* not used */
 100                    }
 101 
 102                    /* Virtual console Modes */
 103                    #define VT_AUTO         0 /* automatic VT switching     */
 104                    #define VT_PROCESS      1 /* process controls switching */
 105 
 106                  The structure will be filled in with the current value for
 107                  each field.
 108 
 109      VT_SETMODE  Sets the VT mode.  The argument is a pointer to a vt_mode
 110                  structure as defined above.  The structure should be filled
 111                  in with the desired mode.  If process-control mode is
 112                  specified, the signals used to communicate with the process
 113                  should be specified.  If any signals are not specified (value
 114                  is zero), the signal default is SIGUSR1 (for relsig and
 115                  acqsig).
 116 
 117      VT_RELDISP  Tells the VT manager if the process releases (or refuses to
 118                  release) the display.  An argument of 1 indicates the VT is
 119                  released.  An argument of 0 indicates refusal to release.
 120                  The VT_ACKACQ argument indicates if acquisition of the VT has
 121                  been completed.
 122 
 123      VT_ACTIVATE
 124                  Makes the VT specified in the argument the active VT (in the
 125                  same manner as if a hotkey initiated the switch).  If the
 126                  specified VT is not open or does not exist, the call fails
 127                  and errno is set to ENXIO.
 128 
 129      VT_WAITACTIVE
 130                  If the specified VT is currently active, this call returns
 131                  immediately.  Otherwise, it sleeps until the specified VT
 132                  becomes active, at which point it returns.
 133 
 134      VT_GETSTATE
 135                  Obtains the active VT number and a list of open VTs.  The
 136                  argument is an address to the following structure:
 137 
 138                    struct vt_stat {
 139                        unsigned short v_active, /* number of the active VT */
 140                                       v_signal, /* not used */
 141                                       /*
 142                                        * count of open VTs.  For every 1 in this
 143                                        * field, there is an open VT
 144                                        */
 145                                       v_state;
 146                    }
 147 
 148                  With VT_GETSTATE, the VT manager first gets the number of the
 149                  active VT, then determines the number of open VTs in the
 150                  system and sets a 1 for each open VT in v_state.  Next, the
 151                  VT manager transfers the information in structure vt_stat
 152                  passed by the user process.
 153 
 154      KDGETMODE   Obtains the text/graphics mode associated with the VT.
 155 
 156                    #define KD_TEXT         0
 157                    #define KD_GRAPHICS     1
 158 
 159      KDSETMODE   Sets the text/graphics mode to the VT.
 160 
 161      KD_TEXT     indicates that console text is displayed on the screen.
 162                  Normally KD_TEXT is combined with VT_AUTO mode for text
 163                  console terminals, so that the console text display
 164                  automatically is saved and restored on the hot key screen
 165                  switches.
 166 
 167                  KD_GRAPHICS indicates that the user/application (usually
 168                  Xserver) has direct control of the display for this VT in
 169                  graphics mode.  Normally KD_GRAPHICS is combined with
 170                  VT_PROCESS mode for this VT indicating direct control of the
 171                  display in graphics mode.  In this mode, all writes to the VT
 172                  using the write system call are ignored, and you must save
 173                  and restore the display on the hot key screen switches.
 174 
 175                  When the mode of the active VT is changed from KD_TEXT to
 176                  KD_GRAPHICS or a VT of KD_GRAPHICS mode is made active from a
 177                  previous active VT of KD_TEXT mode, the virtual console
 178                  manager initiates a KDSETMODE ioctl with KD_GRAPHICS as the
 179                  argument to the underlying console frame buffer device
 180                  indicating that current display is running into graphics
 181                  mode.
 182 
 183                  When the mode of the active VT is changed from KD_GRAPHICS to
 184                  KD_TEXT or a VT of KD_TEXT mode is actived from a previous
 185                  active VT of KD_GRAPHICS mode, the virtual console manager
 186                  initiates a KDSETMODE ioctl with KD_TEXT as the argument to
 187                  the underlying console frame buffer device indicating that
 188                  current display is running into console text mode.
 189 
 190 FILES
 191      /dev/vt/#  VT devices.
 192 
 193 SEE ALSO
 194      ioctl(2), signal(3C), wscons(7D)
 195 
 196 NOTES
 197      By default, there are only five virtual console instance login prompts
 198      running on /dev/vt/# (where "#" represents 2 to 6) in addition to the
 199      system console running on /dev/console.  Normally Xorg uses the seventh
 200      virtual console (/dev/vt/7).  To switch from consoles to Xserver (which
 201      normally picks up the first available virtual console), use [ Ctrl + ]
 202      Alt + F7 .
 203 
 204            # svcs | grep login
 205            online         17:49:11 svc:/system/console-login:default
 206            online         17:49:11 svc:/system/console-login:vt2
 207            online         17:49:11 svc:/system/console-login:vt3
 208            online         17:49:11 svc:/system/console-login:vt4
 209            online         17:49:11 svc:/system/console-login:vt5
 210            online         17:49:11 svc:/system/console-login:vt6
 211 
 212      console-login:default is for the system console, others for virtual
 213      consoles.
 214 
 215      You can manage virtual consoles using the service management facility,
 216      smf(5):
 217 
 218            # svccfg -s console-login add vt8
 219            # svccfg -s console-login:vt8 setprop \
 220              ttymon/device=astring: "/dev/vt/8"
 221            # svcadm enable console-login:vt8
 222 
 223 illumos                        February 17, 2020                       illumos