home | help 
SYSCONS(4)		     Kernel Interfaces Manual		      SYSCONS(4)

NAME
     syscons, sc -- the console driver

SYNOPSIS
     options MAXCONS=N
     options SC_ALT_MOUSE_IMAGE
     options SC_CUT_SEPCHARS=_characters_
     options SC_CUT_SPACES2TABS
     options SC_DISABLE_KDBKEY
     options SC_DISABLE_REBOOT
     options SC_HISTORY_SIZE=N
     options SC_MOUSE_CHAR=C
     options SC_NO_CUTPASTE
     options SC_NO_FONT_LOADING
     options SC_NO_HISTORY
     options SC_NO_PALETTE_LOADING
     options SC_NO_SUSPEND_VTYSWITCH
     options SC_NO_SYSMOUSE
     options SC_PIXEL_MODE
     options SC_TWOBUTTON_MOUSE
     options SC_NORM_ATTR=_attribute_
     options SC_NORM_REV_ATTR=_attribute_
     options SC_KERNEL_CONS_ATTR=_attribute_
     options SC_KERNEL_CONS_REV_ATTR=_attribute_
     options SC_DFLT_FONT
     makeoptions SC_DFLT_FONT=_font_name_
     device sc

     In /boot/device.hints:
     hint.sc.0.at="isa"

DESCRIPTION
     The  syscons  driver provides multiple virtual terminals.	It resembles the
     SCO color console driver.

     The syscons driver is implemented on top of the keyboard driver  (atkbd(4))
     and  the video card driver (vga(4)) and so requires both of them to be con-
     figured in the system.

     There can be only one syscons device defined in the system.

   Virtual Terminals
     The syscons driver provides multiple virtual terminals which appear  as  if
     they  were  separate terminals.  One virtual terminal is considered current
     and exclusively occupies the screen and the  keyboard;  the  other  virtual
     terminals are placed in the background.

     In  order to use virtual terminals, they must be individually marked ``on''
     in /etc/ttys so that getty(8) will recognize them to be active and run  lo-
     gin(1)  to  let  the user log in to the system.  By default, only the first
     eight virtual terminals are activated in /etc/ttys.

     You press the Alt key and a switch key to switch between virtual terminals.
     The following table summarizes the correspondence between	the  switch  key
     and the virtual terminal.

	   Alt-F1   ttyv0      Alt-F7	ttyv6	   Shift-Alt-F1   ttyva
	   Alt-F2   ttyv1      Alt-F8	ttyv7	   Shift-Alt-F2   ttyvb
	   Alt-F3   ttyv2      Alt-F9	ttyv8	   Shift-Alt-F3   ttyvc
	   Alt-F4   ttyv3      Alt-F10	ttyv9	   Shift-Alt-F4   ttyvd
	   Alt-F5   ttyv4      Alt-F11	ttyva	   Shift-Alt-F5   ttyve
	   Alt-F6   ttyv5      Alt-F12	ttyvb	   Shift-Alt-F6   ttyvf

     You  can  also  use the ``nscr'' key (usually the PrintScreen key on the AT
     Enhanced keyboard) to cycle available virtual terminals.

     The default number of available virtual  terminals  is  16.   This  can  be
     changed with the kernel configuration option MAXCONS (see below).

     Note that the X server usually requires a virtual terminal for display pur-
     poses,  so at least one terminal must be left unused by getty(8) so that it
     can be used by the X server.

   Key Definitions and Function Key Strings
     The syscons driver, in conjunction with the  keyboard  driver,  allows  the
     user to change key definitions and function key strings.  The kbdcontrol(1)
     command  will  load  a key definition file (known as ``keymap'' file), dump
     the current keymap, and assign a string to a function key.  See keyboard(4)
     and kbdmap(5) for the keymap file.

     You may want to set the keymap variable in /etc/rc.conf.local  to	the  de-
     sired  keymap  file so that it will be automatically loaded when the system
     starts up.

   Software Font
     For most modern video cards, e.g., VGA, the syscons driver  and  the  video
     card driver allow the user to change the font used on the screen.	The vid-
     control(1)   command   can   be   used   to   load   a   font   file   from
     /usr/share/syscons/fonts.

     The font comes in various sizes: 8x8, 8x14 and 8x16.  The 8x16 font is typ-
     ically used for the VGA card in the 80-column-by-25-line mode.  Other video
     modes may require different font sizes.  It is better to  always  load  all
     three sizes of the same font.

     You may set font8x8, font8x14 and font8x16 variables in /etc/rc.conf to the
     desired  font files so that they will be automatically loaded when the sys-
     tem starts up.

     Optionally you can specify a particular font file as the default.	See  the
     SC_DFLT_FONT option below.

   Screen Map
     If  your  video card does not support software fonts, you may still be able
     to achieve a similar effect by re-mapping the font built  into  your  video
     card.   Use  vidcontrol(1) to load a screen map file which defines the map-
     ping between character codes.

   Mouse Support and Copy-and-Paste
     You can use your mouse to copy text on the screen and paste it as if it was
     typed by hand.  You must be running the mouse daemon moused(8)  and  enable
     the mouse cursor in the virtual terminal via vidcontrol(1).

     Pressing  mouse  button  1  (usually the left button) will start selection.
     Releasing button 1 will end the selection process.  The selected text  will
     be  marked  by  inverting	foreground and background colors.  You can press
     button 3 (usually the right button) to extend the selected region.  The se-
     lected text is placed in the copy buffer and can be pasted  at  the  cursor
     position  by pressing button 2 (usually the middle button) as many times as
     you like.

     If  your  mouse  has  only  two  buttons,	you  may   want   to   use   the
     SC_TWOBUTTON_MOUSE option below to make the right button to paste the text.
     Alternatively you can make the mouse daemon emulate the middle button.  See
     the man page for moused(8) for more details.

   Back Scrolling
     The  syscons  driver  allows  the	user  to  browse  the  output  which has
     ``scrolled off'' the top of the screen.

     Press the ``slock'' key (usually ScrllLock / Scroll Lock or Pause	on  many
     keyboards) and the terminal is in the ``scrollback'' mode.  It is indicated
     by  the Scroll Lock LED.  Use the arrow keys, the Page Up/Down keys and the
     Home/End keys to scroll buffered terminal output.	Press the ``slock''  key
     again to get back to the normal terminal mode.

     The  size of the scrollback buffer can be set by the SC_HISTORY_SIZE option
     described below.

   Screen Saver
     The syscons driver can be made to put up the screen saver	if  the  current
     virtual  terminal	is idle, that is, the user is not typing on the keyboard
     nor moving the mouse.  See splash(4) and vidcontrol(1) for more details.

DRIVER CONFIGURATION
   Kernel Configuration Options
     The following kernel configuration options control the syscons driver.

     MAXCONS=N
	    This option sets the number of virtual terminals to N.  The  default
	    value is 16.

     SC_ALT_MOUSE_IMAGE
	    This option selects the alternative way of displaying the mouse cur-
	    sor  in  the  virtual  terminal.  It may be expensive for some video
	    cards to draw the arrow-shaped cursor, and you may want to try  this
	    option.  However, the appearance of the alternative mouse cursor may
	    not  be very appealing.  Note that if you use the SC_NO_FONT_LOADING
	    option then you must also use this option if you wish to be able  to
	    use the mouse.

     SC_CUT_SEPCHARS=_characters_
	    This  options  specifies characters that will be looked for when the
	    driver searches for words boundaries when doing cut  operation.   By
	    default, its value is "\x20" -- a space character.

     SC_CUT_SPACES2TABS
	    This  options  instructs  the  driver to convert leading spaces into
	    tabs when copying data into cut buffer.  This  might  be  useful  to
	    preserve indentation when copying tab-indented text.

     SC_DISABLE_KDBKEY
	    This  option  disables the ``debug'' key combination (by default, it
	    is Alt-Esc, or Ctl-PrintScreen).  It will prevent users from  enter-
	    ing  the kernel debugger (KDB) by pressing the key combination.  KDB
	    will still be invoked when the kernel panics or hits a  break  point
	    if	it  is	included  in the kernel.  If this option is not defined,
	    this behavior may be controlled at runtime by the sysctl(8) variable
	    hw.syscons.kbd_debug.

     SC_DISABLE_REBOOT
	    This  option  disables  the  ``reboot''  key  (by  default,  it   is
	    Ctl-Alt-Del),  so  that  the casual user may not accidentally reboot
	    the system.  If this option is not defined,  this  behavior  may  be
	    controlled	   at	  runtime     by    the    sysctl(8)	variable
	    hw.syscons.kbd_reboot.

     SC_HISTORY_SIZE=N
	    Sets the size of back scroll buffer to N lines.  The  default  value
	    is 100.

     SC_MOUSE_CHAR=C
	    Unless the SC_ALT_MOUSE_IMAGE option above is specified, the syscons
	    driver reserves four consecutive character codes in order to display
	    the mouse cursor in the virtual terminals in some systems.	This op-
	    tion  specifies  the  first  character code to C to be used for this
	    purpose.  The default value is 0xd0.  A good candidate is 0x03.

     SC_PIXEL_MODE
	    Adds support for pixel (raster) mode console.  This mode  is  useful
	    on	some laptop computers, but less so on most other systems, and it
	    adds substantial amount of code to syscons.  If this option  is  NOT
	    defined,  you can reduce the kernel size a lot.  See the VESA800X600
	    flag below.

     SC_TWOBUTTON_MOUSE
	    If you have a two button mouse, you may want to add this  option  to
	    use the right button of the mouse to paste text.  See "Mouse Support
	    and Copy-and-Paste" above.

     SC_NORM_ATTR=_attribute_

     SC_NORM_REV_ATTR=_attribute_

     SC_KERNEL_CONS_ATTR=_attribute_

     SC_KERNEL_CONS_REV_ATTR=_attribute_
	    These options will set the default colors.	Available colors are de-
	    fined in <machine/pc/display.h>.  See "EXAMPLES" below.

     SC_DFLT_FONT
	    This  option  will	specify  the default font.  Available fonts are:
	    iso, iso2, koi8-r, koi8-u, cp437, cp850, cp865,  cp866  and  cp866u.
	    16-line,  14-line and 8-line font data will be compiled in.  Without
	    this option, the syscons driver will use whatever  font  is  already
	    loaded in the video card, unless you explicitly load a software font
	    at startup.  See "EXAMPLES" below.

     SC_NO_SUSPEND_VTYSWITCH
	    This  option,  which  is  also  available  as  loader(8) tunable and
	    sysctl(8)	variable   hw.syscons.sc_no_suspend_vtswitch,	disables
	    switching  between virtual terminals (graphics <-> text) during sus-
	    pend/resume (ACPI and APM).  Use  this  option  if	your  system  is
	    freezing when you are running X and trying to suspend.

     The following options will remove some features from the syscons driver and
     save kernel memory.

     SC_NO_CUTPASTE
	    This  option disables ``copy and paste'' operation in virtual termi-
	    nals.

     SC_NO_FONT_LOADING
	    The syscons driver can load software  fonts  on  some  video  cards.
	    This  option  removes  this feature.  Note that if you still wish to
	    use  the  mouse  with  this  option  then  you  must  also	use  the
	    SC_ALT_MOUSE_IMAGE option.

     SC_NO_HISTORY
	    This option disables back-scrolling in virtual terminals.

     SC_NO_SYSMOUSE
	    This  option removes mouse support in the syscons driver.  The mouse
	    daemon moused(8) will fail if this option is defined.   This  option
	    implies the SC_NO_CUTPASTE option too.

   Driver Flags
     The following driver flags can be used to control the syscons driver.  They
     can  be set either in /boot/device.hints, or else at the loader prompt (see
     loader(8)).

     0x0080 (VESA800X600)
	    This option puts the video card in the VESA 800x600 pixel, 16  color
	    mode.   It	may be useful for laptop computers for which the 800x600
	    mode is otherwise unsupported by the X server.  Note that  in  order
	    for  this  flag  to  work,	the  kernel  must  be  compiled with the
	    SC_PIXEL_MODE option explained above.

     0x0100 (AUTODETECT_KBD)
	    This option instructs the syscons driver to periodically scan for  a
	    keyboard  device if it is not currently attached to one.  Otherwise,
	    the driver only probes for a keyboard once during bootup.

FILES
     /dev/console
     /dev/consolectl
     /dev/ttyv? 		     virtual terminals
     /etc/ttys			     terminal initialization information
     /usr/share/syscons/fonts/*      font files
     /usr/share/syscons/keymaps/*    key map files
     /usr/share/syscons/scrmaps/*    screen map files

EXAMPLES
     As the syscons driver requires the keyboard driver and the video card  dri-
     ver, the kernel configuration file should contain the following lines.

	   device atkbdc
	   device atkbd
	   device vga
	   device sc

	   device splash
     You also need the following lines in /boot/device.hints for these drivers.

	   hint.atkbdc.0.at="isa"
	   hint.atkbdc.0.port="0x060"
	   hint.atkbd.0.at="atkbdc"
	   hint.atkbd.0.irq="1"
	   hint.vga.0.at="isa"
	   hint.sc.0.at="isa"

     If  you do not intend to load the splash image or use the screen saver, the
     last line is not necessary, and can be omitted.

     Note that the keyboard controller driver atkbdc is required by the keyboard
     driver atkbd.

     The following lines will set the default colors.  The normal text	will  be
     green on black background.  The reversed text will be yellow on green back-
     ground.  Note that you cannot put any white space inside the quoted string,
     because of the current implementation of config(8).

	   options SC_NORM_ATTR=(FG_GREEN|BG_BLACK)
	   options SC_NORM_REV_ATTR=(FG_YELLOW|BG_GREEN)

     The following lines will set the default colors of the kernel message.  The
     kernel  message  will  be	printed bright red on black background.  The re-
     versed message will be black on red background.

	   options SC_KERNEL_CONS_ATTR=(FG_LIGHTRED|BG_BLACK)
	   options SC_KERNEL_CONS_REV_ATTR=(FG_BLACK|BG_RED)

     The following example adds the font files	cp850-8x16.fnt,  cp850-8x14.font
     and cp850-8x8.font to the kernel.

	   options SC_DFLT_FONT
	   makeoptions SC_DFLT_FONT=cp850
	   device sc

CAVEATS
     The  amount  of data that is possible to insert from the cut buffer is lim-
     ited by the {MAX_INPUT}, a system limit on the number of bytes that may  be
     stored in the terminal input queue - usually 1024 bytes (see termios(4)).

SEE ALSO
     kbdcontrol(1),  login(1),	vidcontrol(1), atkbd(4), atkbdc(4), keyboard(4),
     screen(4), splash(4), ukbd(4), vga(4), kbdmap(5), rc.conf(5), ttys(5), con-
     fig(8), getty(8), kldload(8), moused(8)

HISTORY
     The syscons driver first appeared in FreeBSD 1.0.

AUTHORS
     The syscons driver was written by Soren  Schmidt  <sos@FreeBSD.org>.   This
     manual page was written by Kazutaka Yokota <yokota@FreeBSD.org>.

BUGS
     This manual page is incomplete and urgently needs revision.

FreeBSD 7.4			October 22, 2006		      SYSCONS(4)
home | help