NAME

       vga_init - initialize svgalib library

SYNOPSIS

       #include <vga.h>

       int vga_init(void);

DESCRIPTION

       It  detects the chipset and gives up supervisor rights. This is the recommended first line of any program
       that uses svgalib.  vga_setchipset(3) can be called before it to avoid detection.

       Svgalib catches a bunch of signals that usually kill your program  to  restore  textmode.  If  you  catch
       signal's  before  calling vga_init() svgalib will restore textmode and prepare for shutdown and then call
       your handler routine. If you don't want this,  catch  the  signal  after  calling  vga_init  and  do  not
       daisychain to svgalib's original handler.

       WARNING!   svgalib  needs two signals for it's own purposes (that is managing console switches). To avoid
       problems it uses the otherwise unused signals SIGUSR1 and SIGUSR2.  However, this means that  you  cannot
       use them in your program by any means. They are setup by vga_init() as everything else is.

       Since  version  1.2.11 vga_init() includes code to hunt for a free virtual console on its own in case you
       are not starting the program from one (but instead over a network or modem login, from within 'screen' or
       an 'xterm'). Provided there is a free console, this succeeds if you are root or if  the  svgalib  calling
       user own the current console. This is to avoid people not using the console being able to fiddle with it.
       On  graceful  exit the program returns to the console from which it was started.  Otherwise it remains in
       text mode at the VC which svgalib allocated to allow you to see any error messages. In any case, any  I/O
       the svgalib makes in text mode (after calling vga_init) will also take place at this new console.

       Alas,  some  games  misuse their suid root priviledge and run as full root process. svgalib cannot detect
       this and allows Joe Blow User to open a new VC on the console. If this  annoys  you  ROOT_VC_SHORTCUT  in
       Makefile.cfg allows you to disable allocating a new VC for root (except when he owns the current console)
       when compiling svgalib. This is the default (disabling the allocation for root).

       vga_init()  returns  a  non-zero  value  in case of errors. As of this writing it will return -1 if it is
       unable to allocate a graphical console. Otherwise, 0 is returned.

BUGS

       Svgalib versions prior to 1.2.11 had  a  security  hole  where  it  would  be  possible  to  regain  root
       priviledges  even  after  a  vga_init()  call.  This is not necessarily a problem, but if your program is
       vulnerable to buffer overflows and other attacks, an attacker may exploit this.

       However, prior to your call, your program will need to run setuid root, so you should  be  very  careful.
       The ioperm library by Olaf Titz will allow svgalib programs to run not setuid root. However, it gives all
       programs  unlimited access to the hardware. Again, a malicious person can exploit this (albeit a bit more
       difficult) too.  Thus, in general, make your svgalib programs as secure as any setuid root program.

       Some programs may (accidently) rely on the old behaviour (which  was  probably  due  to  the  author  not
       knowing about saved uids (which might actually even not have existed in Linux at that time)). A line:

       security compat

       in the configuration file /etc/vga/libvga.conf will reinstate the old behaviour whereas

       security revoke-all-privs

       enables the (currently default) action.

SEE ALSO

       svgalib(7),   vga_setmode(3),  mouse_init(3),  vga_claimvideomemory(3),  vga_ext_set(3),  vga_fillblt(3),
       vga_getcurrentchipset(3),     vga_getdefaultmode(3),     vga_getgraphmem(3),      vga_runinbackground(3),
       vga_runinbackground_version(3),   vga_safety_fork(3),   vga_setchipset(3),  vga_setchipsetandfeatures(3),
       vgagl(7), libvga.config(5),

AUTHOR

       This manual page was edited by Michael Weller <eowmob@exp-math.uni-essen.de>. The  exact  source  of  the
       referenced function as well as of the original documentation is unknown.

       It   is   very   likely   that   both   are   at  least  to  some  extent  are  due  to  Harm  Hanemaayer
       <H.Hanemaayer@inter.nl.net>.

       Occasionally this might be wrong. I hereby asked to be excused by the original author  and  will  happily
       accept any additions or corrections to this first version of the svgalib manual.

Svgalib (>= 1.2.11)                               27 July 1997                                       vga_init(3)