vt(7I)								  Ioctl Requests							    vt(7I)

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 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 man-
       ager 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 (key-
       board, 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  underly-
       ing  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 */
				 v_state;  /* count of open VTs.  For every 1 in this
					       field, there is an open VT */
		      }

	   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  termi-
	   nals, 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. Nor-
	   mally 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 actived 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(7D)

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/disable/enable and remove/add
		virtual consoles using smf(5):

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

SunOS 5.11							    22 Sep 2008 							    vt(7I)